Scribe.perl is a perl script for generating meeting minutes from an IRC, IM or other log file that follows some simple minuting conventions. It is easy to use and requires no installation. It was primarily designed for use in and around W3C, but can also be used in other environments. (For use in other environments, see the Input Formats section.)
Some sample outputs: default style, with option -member, with option -team and with option -fancy.
This manual documents scribe.perl version 2, revision 81 (dated 29 May 2019). See below for the differences with version 1.
Skip this step if you're not using W3C's IRC.
|/invite rrsagent||calls RRSAagent to the your IRC channel||anybody|
|/invite zakim||calls Zakim to your IRC channel||anybody|
|zakim, this will be ws_arch||ws_arch will be your meeting name||anybody|
|Scribe: dbooth||dbooth is the IRC nickname of the scribe. If you don't give this command scribe.perl will guess the scribe. Use the command again if the scribe changes. There are several useful variants of this command, see the scribe command below.||anybody|
|Meeting: WS Arch Teleconference||Record meeting title||anybody|
|Chair: Mike||Record who chaired||anybody|
|Previous meeting: http://example.org/20180918||If you want a link to the previous meeting at the top of the minutes.||anybody|
|Next meeting: http://example.org/20181002||Ditto for the next meeting.||anybody|
|Agenda: http://example.org/agenda||If you want a link to the agenda at the top of the minutes.||anybody|
|Topic: Debate on Feature X||Use "Topic: …" at the start of each agenda topic. Alternatively, you can use Zakim bot's agenda control, which is recognized by default. (See the -useZakimTopics option below.)||anybody|
|Mike: Feature X is great||Record what Mike said.||scribe|
|… and easy to implement.||Mike's statement continues. Use either three periods or the ellipsis character ‘…’. (Some IRC clients automatically replace the former with the latter.)||scribe|
|General agreement.||A description or summary, not attributed to a particular speaker. Only works when the scribe writes this.||scribe|
|ACTION: Frank to order lunch||Record new action.||anybody|
|Issue: Is it proven that 1+1=2?||Record new issue.||anybody|
|RESOLUTION: Accept Frank's proposal||Indicate how an issue or topic was resolved. ‘RESOLVED’ is an alias for ‘RESOLUTION’.||anybody|
|… with Pete's modified text||Resolutions can be more than one line long. This line is added to the resolution in the previous line. (Such continuation lines also work for topics, issues and actions.)||anybody|
|s/Mary/Marie/||Change most recent occurrence of ‘Mary’ to ‘Marie’. The old string is a literal string, not a regex. Alternate syntax: s|Mary|Marie|||anybody|
|s/Mary/Marie/g||Change all previous occurrences of "Mary" to "Marie".||anybody|
|s/Mary/Marie/G||Change all previous and future occurrences of ‘Mary’ to ‘Marie’ (within this document).||anybody|
|i/Time to vote/Topic: Vote on Feature Y||Insert a ‘Topic: Vote on Feature Y’ line before the line containing the literal string ‘Time to vote’ (not a regex). Alternate syntax: i|Time to vote|Topic: Vote on Feature Y||anybody|
|<dbooth> :-)||When dbooth is scribe and wants to add a remark on IRC as himself, rather than in his role of scribe, he can start the remark with his nick in angle brackets. (Hint: auto-completion in some IRC clients may reduce this to two or three keystrokes.)||scribe|
|zakim, bye||Dismiss zakim bot, which will generate a list of attendees. Use ‘Present: ...’ (described below) instead if you aren't using zakim bot.||anybody|
|rrsagent, make log public||(For public minutes and logs) Change the permissions on the IRC logs. Note that the permission changes are queued and it may be a minute or so before they take effect.||anybody|
|rrsagent, draft minutes v2||Tell RRSAgent to generate minutes from the log as written so far, inheriting access permissions from the log permissions. Note the location of the generated minutes. Skip this step if you are not using RRSAgent.||anybody|
|rrsagent, bye||Dismiss RRSAgent (if used).||anybody|
|(Download and edit the generated minutes)||If you're using RRSAgent, then just edit the generated minutes and you are done.||anybody|
Continue to Step 5 if you wish to run scribe.perl manually or if you are not using RRSAgent.
|(Save a copy of the IRC log, such as http://www.w3.org/2002/04/05-arch-irc.txt)||(Hint: If RRSAgent wrote the minutes to http://...foo-minutes, then the IRC log will be at http://...foo-irc.txt.)|
|(Download scribe.perl)||No installation is needed, but you must have perl.|
|perl scribe.perl log.txt > minutes.html||Generate minutes.|
|(Review and make adjustments.)||If the result isn't good enough, either: 1. edit your copy of the log file and regenerate the HTML; or 2. manually edit the resulting HTML. Option 1 is best if you forgot to indicate who is scribe (‘Scribe: …’), or if you forgot to mark a topic start (‘Topic: …’).|
Scribe.perl reads from the files given as arguments, or standard input if there are none; and writes to standard output:
perl scribe.perl [options] < log.txt > minutes.html
It can also be invoked by RRSAgent from IRC (provided you're using RRSAgent):
rrsagent, draft minutes
Options described below are grouped in several categories:
There are three ways to specify options, from highest to lowest priority:
Options can be written with two dashes (‘--final’) or a single one (‘-final’) and they can be abbreviated as long as the abbreviation is unambiguous (‘--embedDiagnostics’ can be written ‘--embed’, but not ‘--em’, because that clashes with ‘--emphasis’). Case doesn't matter: ‘--dashTopics’ is the same as ‘--dashtopics’.
Options that require an argument can be separated from the argument with either a space or an equals sign: ‘--scribenick jvm’ or ‘--scribenick=jvm’.
These options are used to accommodate the different input syntaxes and scribing styles.
Indicate that dash lines are used to indicate that the next line is the start of a new topic, such as:
<Philippe> --- <Philippe> Review of Action Items
<Philippe> Topic: Review of Action Items
Indicate that the scribe used implicit continuation lines like this:
<dbooth> Mary: Now is the time <dbooth> for all good men and women <dbooth> to come to the aid of their party.
instead of this:
<dbooth> Mary: Now is the time <dbooth> ... for all good men and women <dbooth> ... to come to the aid of their party.
The implicit continuation style is not recommended, because it is ambiguous. For example, the "(Group agrees)" statement below will be incorrectly attributed to Mary, instead of being a scribe comment:
<dbooth> Mary: Now is the time <dbooth> for all good men and women <dbooth> to come to the aid of their party. <dbooth> (Group agrees)
This option only applies to text assigned to a speaker. To continue topics, resolutions, actions or issues on the next line, you must still use ‘...’ or ‘…’.
By default, scribe.perl removes leading spaces on a line and
recognizes continuation lines because they start with three periods
(‘...’) or an ellipsis (‘…’).
forces scribe.perl to treat lines that start with a space as
continuation lines (if there is a line to continue), even if they
don't start with ‘...’ For example, scribe.perl would normally
interpret this fragment
<jim-scribe> Anna: Is the 5th OK? <jim-scribe> Silence. <jim-scribe> Jen: maybe
as three separate items: Anna saying ‘Is the 5th OK?’, the scribe
giving a summary ‘Silence’ and Jen saying ‘maybe’. The extra spaces
are ignored. With
-allowSpaceContinuations, the three
lines become a single statement attributed to Anna (‘Anna: Is the
5th OK? Silence. Jen: maybe’)
The default is
This option only applies to text assigned to a speaker. To continue topics, resolutions, actions or issues on the next line, you must still use ‘...’ or ‘…’.
[Default] Recognize when Zakim bot is used to manage the agenda and the list of attendees. Specifically, treat Zakim statements like:
<Zakim> agendum 2. "UTF16 PR issue" taken up [from MSMscribe]
as equivalent to the command:
<scribe> Topic: UTF16 PR issue
and use Zakim's lines such as ‘As of this point the attendees were…’ as an additional source of names for the presence list.
Turn off the -useZakimTopics option. This also causes commands for Zakim (‘next agendum’, ‘q+’, ‘zakim, list participants’, etc.) and Zakim's answers to be treated as normal text for the minutes, rather than skipped.
These options control the output format.
-nodraft) omits the "- DRAFT -" header.
In the formatted minutes, continuation lines are, by default, shown on a line of their own, starting with ‘…’. (The HTML output contains a <br> to force a new line to start.). E.g., input such as
<pdh> Camille: This works fine. <pdh> ... I tested it. <pdh> ... See the report.
Will produce output similar to this:
Camille: This works fine.
… I tested it.
… See the report.
-nokeepLines, the lines are instead shown as
a single paragraph, without any ‘…’:
Camille: This works fine. I tested it. See the report.
This is _underlined_ and /italic/ and *even bold.*’ leads to ‘This is underlined and italic and even bold..’ Highlighted phrases must be surrounded by spaces to be recognized or be at the edge of the line. The option also causes the replacement of ASCII arrows
<- <-- <= <== ==> => -->and
->by arrow characters (← ⟵ ⇐ ⟸ ⟹ ⇒ ⟶ →) and ASCII smileys
:-) ;-) :-( :-/ ,-) \o/and
/o\by emoticons ☺ 😉 ☹ 😕 😜 🙆 and 🙎.
Scribe.perl can generate HTML with a couple of different styles:
-member, use the 2004 style for team, resp. member minutes.
<a href="https://www.w3.org/"><img src="https://www.w3.org/Icons/w3c_home\" alt=W3C border=0 height=48 width=72></a>is replaced by markup. To suppress the logo, use
scribenickcommand also applies to the lines before that command.)
Commands are interspersed with other minuted text in your IRC log, except that each command must be on a line by itself. Commands may be issued by anyone, not only the scribe. Syntax is shown below by example, with italicized portions variable.
These editing commands are usually the easiest way to correct simple mistakes or add clarifications. (Of course, they don't take effect until you run scribe.perl on your IRC log.)
s/old/new/ s/old/new s|old|new| s|old|new
Replace the most recent occurrence of old with new. Old is a literal string, not a regular expression. These commands are processed in order, first to last. (I.e., each command works on the text that results after the previous command.)
New may contain slashes and vertical bars. E.g., this works:
s/@@/http://example.org/path/. But note that the last
slash is taken as part of the command, not of the new string. To
include a final slash, double it
s/@@/http://example.org/path// or use the alternative
Unlike in Perl, backslashes are not special. E.g.,
s/and\/or/but will try to replace ‘and\’ by ‘or/but’
Successful substitutions are removed from the minutes. Unsuccessful ones are left in the minutes, so they can be manually edited.
Replace globally from this point backward.
Replace globally, both forward and backward.
i/locationString/lineToInsert i/locationString/lineToInsert/ i|locationString|lineToInsert i|locationString|lineToInsert|
Insert lineToInsert before the line containing locationString, which is a literal string, not a regular expression. This is most helpful if you forgot to insert a ‘Topic: ’ command.
For example, the following use of the i// command:
<Arthur> Finished with issue LC71; on to LC82. <Arthur> Frank: This is about syntax <Arthur> ... Do we care about syntax? <dbooth> i/Frank: This is about/Topic: Issue LC82
is converted to:
<Arthur> Finished with issue LC71; on to LC82. <inserted> Topic: Issue LC82 <Arthur> Frank: This is about syntax <Arthur> ... Do we care about syntax?
The following commands may be written with any mix of uppercase and lowercase letters: ‘Meeting’, ‘MEETING’ and ‘mEeTiNg’ are all the same thing.
Meeting: Baking Club
Use "Baking Club" as the title of the meeting minutes. If used multiple times, only the last one has effect.
Jonathan was the meeting chair. If used multiple times, only the last one has effect.
chair: Jonathan, Louis Chair+ Mia chair+ Zoe, Pete, Annabel
If there are multiple chairs, you can separate their names with commas, or use the ‘chair+’ command. The combined result of the three lines above is that the meeting minutes will show that there were six chairs.
chair- Louis, Pete
If you made a mistake, you can remove individual names from the list of chairs.
And if you use ‘chair+’ or ‘chair-’ without any names, it means that you add, respectively remove, your own nickname from the list of chairs.
Scribe: MaryScr ScribeNick: MaryScr
Tells scribe.perl that the IRC name of the scribe is MaryScr. If somebody else takes over as scribe, just give the command again, with the nick name of the new scribe.
‘Scribenick’ is an alternative spelling. Whenever you use ‘scribe’, you can also use ‘scribenick’.
Scribe: jon2 = John Smith Scribe: jon2 / John Smith
You can add the scribe's real name, separated from the IRC name with a slash or an equals sign. This changes how the scribe will be called in the summary at the top of the minutes. Useful if the IRC name is cryptic.
Scribe: Adam, Teo, Ana Scribe:+ Adam/Adamsky, Teo, Ana=Jo-Ana
Multiple scribes can be active at the same time. Separate their names with commas. Of course, you can also add their real name after the nick name.
Scribe+ jon2 Scribe+: jon2 Scribe+ jon2/John Smith Scribe+ jon2, adam=Adamsky
Use ‘scribe+’ (with or without a ‘:’) if one or more scribes start taking minutes in addition to, rather than replacing, the previous scribes.
Scribe- adam Scribe- adam,teo
Indicates when some scribes stop taking minutes.
If there are no names after the ‘+’ or ‘-’, it means the person typing the command is adding or removing himself from the current list of scribes.
A scribe can, e.g., temporarily stop taking minutes
scribe-) and resume later (
A ‘*’ as the scribenick means there is no designated
scribe, but everybody is taking notes together. This is useful,
e.g., when IRC is used for taking notes in a face-to-face meeting,
when IRC isn't needed as a second conversation channel. (But people
can still start their lines with their own nick,
..., see above, to make remarks
outside the minutes.)
People cannot remove themselves from the scribe list with
scribe- after this command.
Specify the agenda URL (optional). If used multiple times, only the last one has effect.
Present: Jonathan, Mary, Barbara, Steve
Indicate who was present.
Regrets: Nathan, Emma
Indicate who sent regrets (optional).
<frank> present+: Janine, Brian <frank> present- Nathan <frank> regrets+ Marja, Leonard <frank> Present+
Add or remove names from the present/regrets lists. The colon is optional after + or -. With no names, it adds or removes the speaker himself, i.e., the last line adds "frank".
Date: 05 Dec 2002
Specify the meeting date. Not usually needed, because the default is guessed from the log URL reported by RRSAgent.
ACTION: Frank, Mary and Kate to propose solution for issue 42 action Ann: publish report 17 Action Fred to do something
Three ways to give an action item: ‘action:’, ‘action name:’ and ‘action name to’. (Other bots, such as Tracker, may require that only one of these syntaxes is used.)
RESOLUTION: Issue 42 closed as duplicate of issue 21 Resolved: next-object does not wrap
Indicate a decision that the group has made. Both keywords may be used interchangeably.
ScribeOptions: -dashTopics -embedDiagnostics
Specify options inline, as if they had been written on the
command line like:
perl scribe.perl -dashTopics -embedDiagnostics. Can be
used multiple times and the options are added to previous ones.
Cause a named anchor ‘foo’ to be generated at this point in the minutes. Leading and trailing spaces are ignored and other spaces are converted to underlines (‘_’). The name can be almost anything, except ‘xNN’, where N is a digit, because those are reserved for scribe.perl's internal use. A few other words (toc, meeting, attendees, links, resolutionsummary, and actionsummary) are also forbidden, because scribe.perl uses them itself.
Next meeting: http:///example.org/20180214/mins Previous meeting: http://example.org/20180228/mins
You can add a link to the previous and next meeting at the top of the minutes.
This adds a link to the meeting agenda at the top of the minutes.
Scribe.perl automatically recognizes most URLs
mailto:…, etc.) and turns them
into links. See the command line option
-urlDisplay for different ways
to format URLs.
A ‘Ralph link’ has
-> followed by a URL followed
by anchor text, like this:
<dbooth> See -> https://www.example.org/ns/w2 wall 2 <dbooth> And -> https://www.example.org/ns/w2 "wall 2", too. <dbooth> -> https://www.example.org/ns/w2 'wall 2' also.
If the anchor text is quoted (as in the second and third lines above), scribe.perl uses only the quoted text as anchor, otherwise it takes all the text until the end of the line. Thus, all three lines contain the link wall 2.
<dbooth> wall 2 -> https://www.example.org/ns/w2
The anchor text is all the text leading up to the
->. You should not put quotes around it, unless you
actually want quotes in the anchor text.
The anchor text and URL can also swap places. This is known as an ‘inverted Xueyuan link’:
<dbooth> See https://www.example.org/ns/w2 -> wall 2 <dbooth> And https://www.example.org/ns/w2 -> "wall 2", too. <dbooth> https://www.example.org/ns/w2 -> 'wall 2' also.
In this case, like with the Ralph links, you can use quotes to limit what goes into the anchor text.
<dbooth> -> wall 2 https://www.example.org/ns/w2 <dbooth> And -> wall 2 https://www.example.org/ns/w2 too.
Like Xueyuan links, Ivan links should not have quotes around the text (unless you actually want the anchor text to contain quotes).
In addition to the ‘realtime’ editing commands above, you may manually edit your IRC log with a text editor (by mimicking the log format) before running scribe.perl. This is most useful for commands that have a broad effect on the generated HTML. Scribe.perl also recognizes RRSAgent's log format without time stamps, so can leave those off, rather than invent fake ones.
Here is an example snippet of an IRC log in which the commands ‘ScribeNick: tw’ and ‘Topic: Fire Alarms’ have been inserted using a text editor.
20:11:21 <tw> Scribe: TedWilliams <tw> ScribeNick: tw 20:11:34 <tw> Topic: Printers 20:11:49 <tw> alan: Printers are working now <tw> Topic: Fire Alarms 20:12:27 <tw> ralph: Fire marshall assured us that the system is working.
Note that the IRC name <tw> is required, though for most commands it does not matter what IRC name is specified.
Several log formats are recognized, and are described below:
Scribe.perl guesses which format you have used by trying each in turn until it finds one one that matches.
If you have a log format that is not recognized:
The plain text format (*.txt) produced by RRSAgent. Hint: add ".txt" to the RRSAgent log URL to get the text version, such as: http://www.w3.org/2002/11/07-ws-arch-irc.txt . The timestamps are ignored (except in guessing the input format), so you can safely edit the log and add lines without having to fake timestamps. Example:
20:41:27 <dbooth> Mike: Feature X would benefit users. 20:41:37 <dbooth> ... and implementation would be easy. 20:41:47 <ericn> I agree.
Timestamped log format produced by mIRC. Example:
[19:35] <Zakim> Steven should now be muted [19:36] <ph> http://lists.w3.org/Archives/Member/w3c-html-cg/2004JanMar/0038.html [19:36] * Zakim hears Steven's hand up [19:36] * Zakim sees Steven on the speaker queue
The format produced by mIRC when you do Buffer→Save As. Example:
<dbooth> Mike: Feature X would benefit users. <dbooth> ... and implementation would be easy. <dbooth> This is pretending to be a long line that mIRC breaks in order to display, but scribe.perl will re-join into a single line. <ericn> I agree.
Timestamped log format produced by X-Chat. Example:
**** BEGIN LOGGING AT Mon Feb 14 11:02:06 2005 Feb 14 11:02:06 --> You are now talking on &arch Feb 14 11:02:06 --- Topic for &arch is W3C Architecture Mardi Gras Meeting Feb 14 11:02:06 --- Topic for &arch set by plh at Tue Feb 8 13:43:31 2005 Feb 14 11:02:11 <Zakim> ok, plh; the call is being made Feb 14 11:02:18 <Zakim> WS_Team()11:00AM has now started Feb 14 11:02:19 <Zakim> +Plh Feb 14 11:02:23 <larryk> This is an on-the-record comment Feb 14 11:02:26 * Yves This is an off-the-record comment **** ENDING LOGGING AT Mon Feb 14 10:22:09 2005
The format produced by Irssi logging with ISO8601 timestamp prefixes. Example:
2003-12-18T15:27:21-0500 <dbooth> Mike: Feature X would benefit users. 2003-12-18T15:27:36-0500 <dbooth> ... and implementation would be easy. 2003-12-18T15:27:36-0500 <ericn> I agree.
The date, seconds and timezone are optional, so the following is also recognized:
15:27 <dbooth> Mike: Feature X would benefit users. 15:27 <dbooth> ... and implementation would be easy. 15:27 <ericn> I agree.
The format produced when you save a Yahoo IM session. Example:
dbooth: Mike: Feature X would benefit users. dbooth: ... and implementation would be easy. ericn: I agree.
Line-oriented plain text format. This format is intended for occasions when the scribe doesn't have access to IRC, and simply takes notes in a text editor. Example:
Mike: Feature X would benefit users.... and implementation would be easy. Eric agrees.
The style of IRSSI logs as used by Bert Bos, characterized by a date & time at the start and a vertical bar separating the nick name and the message. This is almost identical to the elho theme for IRSSI, which should work here as well. Here is an example:
--- Log opened Thu Mar 19 12:57:23 2015 12:57 «Users» | 23 nicks (0 ops, 0 halfops, 0 voices, 23 normal 12:57 «Mode» | Channel &global was created on Fri Apr 11 21:35:25 2014 13:08 * | koalie veronica :D 13:08 --> | naomi_ (email@example.com) has joined &global 13:10 Zakim | +Plh 13:11 scribe | Angel: Short meeting. 13:13 «Quit» | naomi (firstname.lastname@example.org) has signed off (Ping timeout: 180 seconds) 13:14 veronica | q? 13:15 * | Zakim sees no one on the speaker queue 13:15 scribe | Veronica: Please everyone update the FTMS records.
The SCRIBEOPTIONS environment variable holds the default options that one wants to use. It is not required. Example for a Bourne-style shell:
Scribe.perl version 2 accepts most of the same options as version 1 and recognizes most of the same commands in the input. The following are different:
Status codes for actions are not supported. An action preceded
by a status code, such as ‘
[PENDING] ACTION: Joe to write
text’, is not recognized as an action. It will be
a simple text. A status cade after the action, such as
ACTION: Joe to write text [PENDING]’, is simply
part of the action description.
There is no
-template option. Scribe.perl
version 2 does not accept external HTML templates.
A ‘scribeOptions’ command takes priority over command line options, instead of the other way round.
The ‘-keeplines’ option (and its inverse ‘-nokeeplines’) is new.
The ‘-inputFormat’ option is not supported. It is not possible to override the automatic selection of the input format.
The ‘-tidy’ option is not supported. Scribe.perl version 2 always generates valid HTML (HTML5, currently).
The ‘-trustRRSAgent’ option is not supported. When RSSAgent is dismissed, it summarizes the actions and resolutions it has seen, but scribe.perl version 2 does not use them.
The ‘-plain’, ‘-public’ and ‘-mit’ options are not supported. Scribe.perl version 2 does not currently have style sheets for ‘-plain’ and ‘-mit’. Note that the public style is the default.
The ‘-scribe’ option is not supported.
The ‘-sampleInput’ and ‘-sampleOutput’ options are not supported.
The ‘Log:’ command is not supported. It was rarely needed, because the URL of the IRC log, if any, can usually be inferred from the messages by RRSAgent.
The ‘-emphasis’ option is new.
The scribe can make IRC statements as himself by prefixing his text with his own nick in angle brackets (see example above).
scribenick commands no
longer have different functions. Both of them set the IRC name
and the real name of the scribes. In order to set a real
name that is different from the IRC name, use the syntax with ‘/’ or ‘=’.
The '-philippe' and '-plh' options are not supported. Use '-dashTopics' instead.