Scribe is a markup language and word processing system.
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
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.
Most of the definitions in this section affect the Scribe system at the
@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
@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.
@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.
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.
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
|
@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.
|
|||||
|
@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 | ||
|
@code(text) |
<code>text</code> |
code example inside text | ||
|
@codef(text) |
<code>text</code> |
code example inside text | ||
|
@mult |
* |
insert a multiplication sign |
|
@command(text) |
inline command | |
|
|
region command |
The most often used Scribe region commands in the Nyquist manual are:
Comments produce no text in the final document and can be written as inline or as region command:
|
@comment(text) |
inline comment | |
|
|
region comment |
|
@foot(text) |
footnote |
|
@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. |
|
|||||
|
@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 |
|
|
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. |
|||
|
|
this will produce a titlebox. |
|
@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)
|
@* |
force a line break | |
|
@newpage |
force a page break |
|
@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 bibliography is a labeled list of books, articles, or papers.
@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 '
|
|
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
'
@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.
The 's2h.lsp' HTML converter assumes a number of definitions in Scribe
source, so for example, @dash is defined for
@commandstring(dash @Y[M])
In the Scribe output this will create an '
|
|
@codef is used to define a
lisp function or variable. |
||
|
|
@pragma(defn) tells 's2h.lsp' that the next @index marks a term's definition in the manual. | ||
|
|
@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)@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
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)