# Scribe

- @@ - insert an '@' sign
- @+ - superscript
- @− - subscript
- @~ - unknown meaning
- @\ - horizontal tabulator
- @* - force a line break
- @appendix - start appendix chapter
- @b - bold text
- @begin - start a region

- center - centered text
- code - code example, use typewriter font
- comment - invisible in the final document
- description - definition list
- detail - use small font
- display - non-justified text
- enumerate - ordered list
- example - code example, use typewriter font
- fdescription - special definition-list format
- fgroup - special PDF format for function definitions
- figure - insert a figure
- fndefs - special PDF format for function definitions
- itemize - unordered list
- math - render and insert a math formula
- pdescription - special definition-list format
- programexample - code example, typewriter font
- smallcode - typewriter font, use small font in PDF
- titlebox - put text into the title box
- titlepage - define the title page
- transparent - transparent background color

- @blankspace - insert witepace with specific width
- @c - small capitals
- @caption - add text to an object
- @chapter - start an numbered chapter
- @center - centered text
- @cite - cite an entry from the bibliograpy
- @code - inline code example, use typewriter font
- @codef - inline code example, use typewriter font
- @commandstring - define printing commands [for CMU use only]
- @comment - a comment, invisible in the final document
- @dash - insert a horizontal dash with specific width
- @define - define a command or a variable
- @device - the printer device [for CMU use only]
- @display - non-justified text
- @end - end of a region
- @fillcaption - add formatted text to an object
- @foot - add a footnote
- @graphic - insert a picture
- @html - insert text in HTML only
- @htmltitle - insert a HTML header with title (HTML only)
- @i - italics
- @include - read a different Scribe file
- @index - index reference
- @itemsep - insert a horizontal dash with specific width
- @label - add a label to a section
- @libraryfile - load Scribe library [for CMU use only]
- @majorheading - document title
- @make - printer output format [for CMU use only]
- @math - render and insert a math formula
- @mult - insert a multiplication sign
- @modify - change internal Scribe settings [for CMU use only]
- @newpage - force a page break
- @p - bold italics
- @pageheading - format of the page heading
- @pageref - insert the page number of a @label
- @paragraph - start a new paragraph
- @parm - unknown meaning
- @part - faciliates separate compilation of parts of a larger document
- @pragma - control the 's2h.lsp' HTML converter
- @ref - insert the section number of a @label
- @section - start a section
- @set - set a Scribe variable [for CMU use only]
- @style - change a Scribe document preset [for CMU use only]
- @subsection - start a sub-section
- @subtract - insert a horizontal dash with specific width
- @t - use typewriter font
- @tabclear - reset tabulator settings
- @tabset - define new tabulator settings
- @tag - add a label to a figure or table
- @textform - define a text-formatting Scribe command
- @title - define the page heading title
- @unnumbered - start an unnumbered chapter
- @use - use a external database file
- @value - insert the value of a command or a variable

## Table of Contents

1. Scribe - basic Syntax rules
2. General Settings - start of 'myquistman.mss'

- Dashes with different Width
- Commands for Large Documents
- The '@style' Command
- Numbering Pages and Page Headings

3. Command Definitions - Nyquist Scribe commands

- HTML Commands - controling the 's2l.lsp' HTML converter

4. Inline Markup
5. Regions
6. Lists
7. Comments
8. Footnotes
9. Indexing
10. Headings
11. Title Page
12. Tab Stops and Whitespace
13. Line and Page Breaks
14. Cross References
15. Bibliography and Citation
16. Figures and Tables

## Scribe

Scribe is a markup language and word processing system. It was designed and developed by Brian Reid of Carnegie Mellon University around 1980.

- http://en.wikipedia.org/wiki/Scribe_(markup_language)

A source file prepared for input to Scribe consists primarily of plain text. Paragraphs are separated by blank lines, and commands, if present, are flagged with '@' signs. If you want an '@' sign to appear within your output, you must type two of them '@@'. A file containing no commands at all will work just fine, it will yield simple justified paragraphed text. A Scribe source file should be given the extension '.mss'. Upper and lower case may be used interchangeably in any Scribe command.

A perhaps confusing aspect of Scribe is that you get to use any bracket as long as you close it with a matching one, so for example:

    @i(This is italic.)
    @i[This is also italic]
    @i{This italic has (parentheses) but it's ok because there is no curly brace}
    @begin(i)This form is allows [any] (brackets) {in} the text, but "at" (@@) must be escaped@end(i)

Legal delimiter pairs are:

`` | `(...)` | , | `[...]` | , | `<...>` | , | `"..."`

It doesn't really matter which delimiter is used as long as the closing delimiter matches the opening limiter.

Back to top

## General Settings

Most of the definitions in this section affect the Scribe system at the CMU only.

    @device(mac52postscript)          @comment(printer device)
    @make(manual)                     @comment(printer output format)
    @libraryfile(mathematics10)
    @libraryfile(picture)
    @libraryfile(multilevelindex)
    @style(font timesroman)           @comment(printer font)
    @style(fontscale 11)              @comment(printer font size)
    @commandstring(dash @Y[M])
    @commandstring(subtract @Y[N])
    @commandstring(itemsep @Y[M])
    @Modify(indexenv, above=2 lines, leftmargin 8, columns=3, boxed)
    @define(prg=i)

The '@commandstring' lines define three formatting directices:

`` | `@dash` | , | `@subtract` | , | `@itemsep` | - | a minus sign in HTML, but different widths in PDF

[A block with Command Definitions follows here in the original file, moved to a separate paragraph below.]

    @use(bibliography = "../bib/music.bib")
    @style(references ClosedAlphabetic)
    @counter(dummy-counter)
    @modify(FigureCounter,Within=dummy-counter,
            Numbered <@@b[Figure@@ @1:@@ @@ ]@@$>,
            Referenced "@1",Init 0)
    @modify(TableCounter,Within=dummy-counter,
            Numbered <@@b[Table@@ @1:@@ @@ ]@@$>,
            Referenced "@1",Init 0)
    @pageheading(left "", center "@value(page)", right "")
    @include(../template/filcap.mss)

Scribe commands for producing large documents:

`` | `@part(text)` | - | faciliates separate compilation of parts of a larger document.
`` | `@use(text)` | - | tells Scribe to use a particular database file, used to include the bibliography file
`` | `@include(text)` | - | read another Scribe file

The @style Command

The database entry for a document type presets the value of all Scribe parameters. The '@style' command can be used to override these values. All '@style' commands used in a document must come at the beginning. Styles can't be changed in the middle of a document. Here is a list of '@style' commands used in the Nymqust manual:

    @style(font timesroman)
    @style(fontscale 11)
    @style(references ClosedAlphabetic)
    @style(pagenumbers="@i")
    @style(pagenumbers="@1")

Numbering Pages and Page Headings

The page heading and footing areas are divided into three parts. A 'left' part, a 'center' part, and a 'right' part:

    @pageheading(left "", center "@value(page)", right "")
    @pageheading(even, left "Page @Value(Page)", right "@c(Nyquist Manual)")
    @pageheading(odd, left "@c[@title(chapter)]", right "Page @Value(page)")

The text fields inside the quotes can contain anything, including Scribe commands.

Back to top

## Command Definitions

The definitions in this section are used in the Scribe sources.

    @define(detail=text, size 9, spacing 1.2, indent 0)
    @define(code, FaceCode T, size 11)
    @define(codef, FaceCode T, size 11)
    @define(smallcode, FaceCode T, size 8, spacing 0.8) @comment(was 10)
    @define(rbdisplay = display, group)
    @define(fndefs = description, leftmargin 0.5in, indent -0.5in)
    @define(fdescription = text, leftmargin +0.5in, indent -0.5in, spread 1)
    @define(pdescription = text, leftmargin +0.5in, indent -0.5in, spread 0)
    @define(fgroup = text, indent -0.5in, spread 0)

- detail defines text with a small font
- code and codef define text with a typewriter font
- smallcode defines text with typewriter font, with a small font in PDF
- 'rbdisplay' seems nowhere else to be used in the Nyquist manual
- fndefs and fgroup define special PDF formatting parameters for function definitions
- fdesription and pdescription define a special definition list format

'@codef' is used to define a lisp function or variable. A processor uses this to extract completion hint info for NyquistIDE.

HTML Commands

Three Scribe commands are added for the 's2h.lsp' HTML converter::

    @textform(html = [])
    @textform(htmltitle = [])
    @textform(pragma = [])

The first two commands insert text in the HTML file only, but not in the PDF:

`` | `@html(text)` | - | insert HTML text
`` | `@htmltitle(text)` | - | insert a HTML header with title

The '@pragma' command controls the 's2h.lsp' HTML converter:

`` | `@pragma(defn)` | - | the next @index marks a term's definition in the manual
`` | `@pragma(startscribe)` | - | ignore scribe file starting here
`` | `@pragma(endscribe)` | - | stop ignoring scribe file
`` | `@pragma(startref)` | - | use text between here and an @ref or @pageref as link text
`` | `@pragma(doinclude)` | - | process the next include file (default is to ignore)
`` | `@pragma(endcodef)` | - | end a code definition (used for completion list)

RBD: '@pragma(defn)' is used to mark a term's point of definition. I tried to define(defn=index), but that didn't work in Scribe, so the approach now is to mark definitions. In s2h, the 'defn' pragma sets a flag that the NEXT index term is a definition. The 's2h.lsp' processor uses this to map terms defined within 'codef' (which go into the completion list) to URLs for the help system.

Back to top

## Inline Markup

`` | Scribe |  | HTML
`` | `@b(text)` | → | `<b>text</b>` | - | bold
`` | `@i(text)` | → | `<i>text</i>` | - | italics
`` | `@p(text)` | → | `<b><i>text</i></b>` | - | bold + italics
`` | `@t(text)` | → | `<tt>text</tt>` | - | typewriter font
`` | `@c(text)` | → | `<small>text</small>` | - | small capitals
`` | `@+(text)` | → | `<sup>text</sup>` | - | superscript
`` | `@−(text)` | → | `<sub>text</sub>` | - | subscript
User-defined Scribe commands:
`` | `@code(text)` | → | `<code>text</code>` | - | code example inside text
`` | `@codef(text)` | → | `<code>text</code>` | - | code example inside text
Named entities:
`` | `@mult` | → | `*` | - | insert a multiplication sign

Back to top

## Regions

Text-formatting Scribe commands can be written as inline command or as a region command, delimited by '@begin' and '@end':

`` | `@command(text)` | - | inline command
`` | `@begin(command) text @end(command)` | - | region command

The most often used Scribe region commands in the Nyquist manual are:

`` | Scribe |  | HTML
`` | `@begin(programexample) text @end(programexample)` | → | `<pre> text </pre>` | - | code example, typewriter font
`` | `@begin(example) text @end(example)` | → | `<pre> text </pre>` | - | code example, typewriter font
`` | `@begin(display) text @end(display)` | → | `<blockquote> text </blockquote>` | - | normal text, non-justified, each line separate
`` | `@display(text)` | - | same as above
Scribe: The 'example' and 'display' inserts types are very similar, they differ only in the type face that will be used. In either 'example' or 'display' inserts, each line of the manuscript will produce one line in the document. Since 'example' is for showing examples of computer type-in and type-out, it will appear in a typeface that is designed to look like computer output. 'display' inserts will appear in the normal body typeface. If the document is printed on a device that cannot change fonts, then 'example' and 'display' will look nearly identical.
`` | `@begin(center) text @end(center)` | → | `<center> text </center>` | - | each line centered
`` | `@center(text)` | - | same as above
Scribe: The 'center' insert is similar to 'display', except that it centers its lines rather than left-justifying them. Like 'display', 'center' produces one line in the document for each line of the manuscript file that is inside the 'center'. If there is more than one line in a 'center' insert, each line will be centered individually.
`` | `@begin(detail) text @end(detail)` | → | `<small> text </small>` | - | use small font
`` | `@begin(code) text @end(code)` | → | `<code> text </code>` | - | typewriter font
`` | `@begin(smallcode) text @end(smallcode)` | → | `<code> text </code>` | - | typewriter font, use small font in PDF

Back to top

## Lists

`` | Scribe |  | HTML
`` | `@begin(itemize) item-1 item-2 item-3 @end(itemize)` | → | `<ul> <li>item-1 <li>item-2 <li>item-3 </ul>` | - | unordered list
`` | `@begin(enumerate) item-1 item-2 item-3 @end(enumerate)` | → | `<ol> <li>item-1 <li>item-2 <li>item-3 </ol>` | - | ordered list
Scribe: 'itemize' and 'enumerate' each expect a sequence of paragraphs, separated by blank lines, and each justifies those paragraphs into inset margins and puts a mark in front of each. 'itemize' puts a tick-mark or a bullet in front of each paragraph, while 'enumerate' puts a number in front of each.
`` | `@begin(description) item-1@\text-1 item-2@\text-2 item-3@\text-3 @end(description)` | → | `<dl> <dt>item-1<dd>text-1 <dt>item-2<dd>text-2 <dt>item-3<dd>text-3 </dl>` | - | definition list
Scribe: A 'description' insert is designed for the 'command description' style that is very common in reference manuals. The first line of a 'description' insert will be at the left margin, and the second and remaining lines will be indented substantially, so that the word or phrase at the end of the head of the description stands out. If three or more blanks in a row are found in the first line of a 'description', they will be taken as a signal to tab to the left margin provided that the left margin has not been passed.
`` | `@begin(fdescription) item @begin(pdescription) text-1 text-2 text-3 @end(pdescription) @end(fdescription)` | → | `<dl> <dt> item <dd> text-1<br> text-2<br> text-3<br> </dl>` | - | definition list

Back to top

## Comments

Comments produce no text in the final document and can be written as inline or as region command:

`` | `@comment(text)` | - | inline comment
`` | `@begin(comment) text @end(comment)` | - | region comment

Nach oben

## Footnotes

`` | `@foot(text)` | - | footnote

Back to top

## Indexing

`` | `@index(text)` | → | `<a name="indexXX">` | - | nothing will appear in the printed text, but the 'text' will appear in the index together with the current page number.

Back to top

## Headings

`` | Scribe |  | HTML
`` | `@majorheading(text)` | → | `<h1>text</h1>` | - | document title
`` | `@unnumbered(text)` | → | `<h2>text</h2>` | - | unnumbered chapter (e.g. preface)
`` | `@chapter(text)` | → | `<h2>text</h2>` | - | numbered chapter
`` | `@appendix(text)` | → | `<h2>text</h2>` | - | appendix
Scribe: Notice that 'unnumbered', 'chapter', and 'appendix' cause Scribe to start at the top of a new page.
`` | `@section(text)` | → | `<h3>text</h3>` | - | section
`` | `@subsection(text)` | → | `<h4>text</h4>` | - | subsection
`` | `@paragraph(text)` | → | `<h5>text</h5>` | - | paragraph

Back to top

## Title Page

`` | `@begin(titlepage) text @end(titlepage)` | - | this will cause the title page to be a page by itself, and text within the titlepage will be centered.
Scribe: The title page for a technical report usually has the title, author, and date of publication visible within a box that will be reproduced on the cover of the report. The 'titlebox' command can be used to put text in this box:
`` | `@begin(titlebox) text @end(titlebox)` | - | this will produce a titlebox.

Back to top

## Tab Stops and Whitespace

`` | `@tabclear` | - | clear all tabs
`` | `@tabset(number unit)` | - | set tab width to 'number' of units, 'unit' should be 'inch' or 'inches'
`` | `@\` | - | go to the right until the next tab. If there is no tab stop to the right of the cursor position, then the cursor will be moved to the right margin.

    @tabset(.5 inches)
    @tabset(0.8 in, 3 in, 3.8 in)
    @tabset(1.5 inch)
    @tabset(0.8 inches)
    @tabset(0.5 inch)

`` | `@blankspace(number)` | - | forces a 'number' units of whitespace
`` | `@blankspace(number unit)` | - | forces a 'number' units of whitespace, 'unit' should be 'inch' or 'inches'

    @blankspace(0.3 inches)
    @blankspace(0.5 inch)
    @blankspace(0.3 inch)
    @blankspace(1 inch)
    @blankspace(5 inches)
    @blankspace(1)

Back to top

## Line and Page Breaks

`` | `@*` | - | force a line break
`` | `@newpage` | - | force a page break

Back to top

## Cross References

`` | `@label(word)` | - | define a label (text reference to a section or page number)
`` | `@ref(word)` | - | insert the section number of the label
`` | `@pageref(word)` | - | insert the page number of the label
`` | `@tag(word)` | - | define a tag (object reference to a figure or a table)

Scribe: The difference between a 'label' and a tag is a bit subtle. A section document has many different sequences of numbers that identify the pieces of it. Pages are numbered sequentially, chapters and sections are usually numbered independently of the pages. Figures and tables are often numbered within a chapter, ignoring section numbers. If you want to attach a codeword to the section number of the section that contains a particular figure or table, then use '@label'. If you want to attach a codeword to the figure or table, rather than to the section that it is contained in, then use the '@tag' command.

Back to top

## Bibliography and Citation

A bibliography is a labeled list of books, articles, or papers. A citation is a marker in the text that refers to an entry in the bibliography. Because Scribe selects and prints only those entries in a bibliography that are actually cited in the text, a common bibliography file may be used for many different documents. The bibliography file consists of a series of entries, each with an identifier.

    @book(Touretzky
            ,key "Touretzky"
            ,author "Touretzky, David S."
            ,title "LISP: a gentle introduction to symbolic computation"
            ,address "New York"
            ,publisher "Harper & Row"
            ,year 1984
            )

    @inproceedings(ICMCFugue
            ,key "Dannenberg"
            ,author "Dannenberg, R. B. and C. L. Fraley"
            ,title "Fugue: Composition and Sound Synthesis With Lazy Evaluation
            and Behavioral Abstraction"
            ,booktitle = "Proceedings of the 1989
                    International Computer Music Conference"
            ,editor "T. Wells and D. Butler"
            ,year = "1989"
            ,organization = "International Computer Music Association"
            ,address "San Francisco"
            ,pages "76-79"
            )

Then just put a '@cite' command into the text at the spot where the citation should appear:

    @cite(Touretzky)
    @cite(icmcfugue)

RBD: HTML citations are translated by 's2h.lsp' to links according to data in 'docsrc/s2h/citations.lsp'. The actual bibliographic references must be hand-translated to HTML.

Back to top

## Figures and Tables

`` | `@begin(figure) text @end(figure)` | - | define a region to insert an object

`` | `@graphic(text)` | - | insert a picture
`` | `@math(text)` | - | insert a rendered math formula

`` | `@caption(text)` | - | add text to an object
`` | `@fillcaption(text)` | - | add formatted text to an object and modify object counters

With the Scribe @tag command a label can be added to an object. The best place to put the @tag command is after the '@caption' or '@fillcaption' command. If the @tag command appears before the '@caption' or '@fillcaption' command, then the wrong figure number will get assigned to the tag, because the number will not yet have been incremented.

The '@fillcaption' command is defined in the file 'docsrc/template/filcap.mss':

    @textform[FillCaption="@begin(transparent)@modify(captionenv,fill,indent 0,
    leftmargin +0.5 inch,rightmargin +0.5 inch)@modify(figurecounter,
    numbered <@@b[Figure@@ @#@:-@1:@@ @@ ]>)@modify(tablecounter,
    numbered <@@b[Figure@@ @#@:-@1:@@ @@ ]>)@caption<@parm<text>>@~
    @end(transparent)"]

The exact meaning of the Scribe '@parm' and '@~' commands are currently unknown.

Back to top

## Formatting of the Nyquist Manual

The 's2h.lsp' HTML converter assumes a number of definitions in Scribe source, so for example, @dash is defined for Scribe by:

    @commandstring(dash @Y[M])

In the Scribe output this will create an 'em-dash' (horizontal dash with a width of the letter 'm'), but the 's2h.lsp' HTML converter will always translate @dash to a hyphen character, regardless of the Scribe @commandstring definition, which 's2h.lsp' ignores. In other words, 's2h.lsp' is not written to handle any of the mechanisms provided by Scribe to extend the command set, but there are some built-in extensions such as @dash so that 's2h.lsp' can translate Nyquist manuals.

`` |
`@codef(name)`
| - | @codef is used to define a lisp function or variable. A processor uses this to extract completion hint info for NyquistIDE.
`` |
`@pragma(defn)`
| - | @pragma(defn) tells 's2h.lsp' that the next @index marks a term's definition in the manual.
`` |
`@index(term)`
| - | @index is used to insert 'term' in the manual's index.

Although Scribe has no support for marking up why a location is indexed, 's2h.lsp' uses @pragma(defn) before @index(term) to indicate that this location in the text provides the definition of 'term'. This information helps 's2h.lsp' give priority to this location in the text in cases where term may be indexed from multiple locations. In short, if you define a term, you should insert:

    @pragma(defn)@index(term)

at the beginning of the definition.

Function definitions in the Nyquist manual should be documented like this:

    @begin(fndefs)
    @codef[myfunction(@pragma(defn)@index(myfunction) ... parameters ...]@\Description of myfunction.

    @codef[myotherfn(@pragma(defn)@index(myotherfn) ... parameters ...]@\Description of myothernfn.
    @end(fndefs)

Where one or more function definitions can be inside the @begin(fndefs) and @end(fndefs) brackets.

Another style of documenting functions, used in the XLISP documentation is to document the function and provide indented detailed descriptions of each parameter and the return value. This style is shown here and uses @fdescription and @pdescription:

    @begin(fdescription)
            (eval@pragma(defn)@index(eval) @i<expr>) @itemsep evaluate an xlisp expression
    @begin(pdescription)
                @i<expr> @itemsep     the expression to be evaluated

                returns @itemsep     the result of evaluating the expression
    @end(pdescription)
    @blankspace(1)

Back to top