## Introduction

#### Nearby

Scribe.perl (link to the source) 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.)

Scribe.perl supports links, images, subsections and even math!

Some sample outputs: default style, with option -member, with option -team and with option -fancy.

This manual documents scribe.perl version 2, revision 158 (dated 17 October 2021). See below for the differences with version 1.

## Quick Start Guide

### Step 1: Invite RRSAgent and Zakim bot

Skip this step if you're not using W3C's IRC.

IRC Command Explanation Who?
/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

Note: If you are on a channel that has a Trackbot, the above can be replaced with the single command /trackbot, start meeting

### Step 2: Start the meeting:

IRC Command Explanation Who?
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

### Step 3: Take notes in IRC:

IRC Command Explanation Who?
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
Subtopic: Intro to feature X Use "Subtopic: …" for a subtopic. 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

### Step 4: Finish the meeting

IRC Command Explanation Who?
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

### Step 5: Generate minutes

This step is only needed if you are not using RRSAgent, or you forgot step 4 and its too late to run RRSAgent now, or if you want to make edits that are best done locally.

Shell Command Explanation
(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.)
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: …’).

## Pros and Cons of Using Scribe.perl

Pros:

• It's free, it's open source, and it usually works.
• It runs anywhere that perl is installed. (I hope! Please let me know if it doesn't.)
• Easy to use. It uses conventions that are used in many W3C working groups.
• It recognizes several input and log formats.

Cons:

• You still need to do some manual clean-up.
• It doesn't recognize all minuting conventions. (Suggestion: Learn its conventions, they're simple.)

## Running scribe.perl

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

Options described below are grouped in several categories:

There are three ways to specify options, from highest to lowest priority:

• Using the ‘ScribeOptions:’ command in IRC
• On the shell command line, when invoking scribe.perl
• Via the SCRIBEOPTIONS environment variable

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’.

### Input Style Options

These options are used to accommodate the different input syntaxes and scribing styles.

-dashTopics

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
-implicitContinuations

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.

<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 ‘…’.

-allowSpaceContinuations / -noallowSpaceContinuations

By default, scribe.perl removes leading spaces on a line and recognizes continuation lines because they start with three periods (‘...’) or an ellipsis (‘…’). -allowSpaceContinuations 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 -noallowSpaceContinuations.

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 ‘…’.

-useZakimTopics

[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.

-noUseZakimTopics

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.

### Output Format Options

These options control the output format.

-scribeOnly
Only include what the scribe wrote. Discard any statements made on IRC.
-final
-nodraft
By default, scribe.perl includes a ‘- DRAFT -’ header in the formatted output, to remind you that the generated minutes still need manual editing. -final (or -nodraft) omits the "- DRAFT -" header.
-nofinal
-draft
[DEFAULT] Include a ‘- DRAFT -’ header.
-embedDiagnostics
Embed scribe.perl's diagnostic output into the generated minutes. This is most useful when scribe.perl is run as part of an automated process that otherwise would not display the diagnostic output to the user.
-noEmbedDiagnostics
[DEFAULT] Write diagnostic output to the console (stderr).
-keeplines / -nokeepLines

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.

With -nokeepLines, the lines are instead shown as a single paragraph, without any ‘…’:

Camille: This works fine. I tested it. See the report.

Default is -keeplines.

-emphasis

Cause scribe.perl to interpret ‘ASCII highlighting’, arrows, smileys and mathematical formulas.

ASCII highlighting gives underlined, italic and bold text:

Input Output
_underlined_ underlined
/italic/ italic
*bold* 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 ASCII smileys:

Input Output
<-
<--
<=
<==
==>
=>
-->
->
:-)
;-) 😉︎
:-(
:-/ 😕︎
,-) 😜︎
\o/ 🙌︎