Scribe



Table of Contents


  1. Scribe - basic Syntax rules
  2. General Settings - start of 'myquistman.mss'
  3. Command Definitions - Nyquist Scribe commands
  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.

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)

'@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