"Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing." - Dick Brandon
DocGen is a simple form of literate programming that enables you to generate software manuals and Forth glossaries directly from the source code of the software. The documentation is produced from formal comments within the source code. The manual for VFX Forth is itself produced this way.
Unlike some other forms of literate programming, all editing is performed directly in the source code itself with the same editor you use for editing the source code. This makes it easy to ensure that your documentation is accurate and up
In order to provide for both on-screen and printed documentation, DocGen can generate output in several forms, referred to as personalities. DocGen is supplied with several personalities.
For all operating systems, there is a range of LaTex implementations. For Windows we use Miktek from
http://www.miktex.org
or TexLive from
https://www.tug.org/texlive/
For Linux and Macs we usually use the Texlive distribution.
If you wish to generate output in other forms, instructions for writing additional personalities are provided later in this chapter.
DocGen supports the use of formatting commands (macros) within the DocGen formal comments.
The DocGen HTML personality can generate separate output files for a table of contents and an index of documented words. The Texinfo personality can also index documented words using the facilities of Texinfo.
The source code for DocGen is in the file Lib/DocGen4.fth. The earlier code that generates HTML v2 is in Lib/DocGen3.fth.
In normal use DocGen is enbled by +DOCGEN
and disabled
by -DOCGEN
which causes DocGen comments to be generated
when source code is compiled.
For use with embedded systems code that cannot be compiled
by VFX Forth replace the use of INCLUDE
by
DOCONLY
or replace INCLUDED
by PARSED
.
These can also be used to generate manuals separately from the
compilation process, which is useful when the ordering of the
manual is not the same as the compilation order. Note that the
'*>' and '*!' tags described in the section "Marking up your text"
can provide fine grain control of ordering, especially for TeX and
PDF manuals.
An example of using DocGen for a software project is the manual for the ForthEd2 text editor in Examples\ForthEd2. Examples\ForthEd2\Manual\DocFiles contains everything needed to generate an indexed manual in both HTML and PDF formats. Feel free to use these as templates for your projects.
DocGen is controlled by the following words.
defer DocGen-Spacing \ c-addr u -- c-addr' u'
If your house rules require DocGen comments to start other than
in the first column, assign an action to this DEFER
red word. The
action should remove characters before the start of the comment,
returning the modified string as c-addr' u'.
0 value DocGen? \ -- flag ; true if DOCGEN enabled
Returns true if DocGen is enabled, otherwise false.
: +DOCGEN \ -- ; enable DOCGEN
Enables DocGen generation of documentation. After using
+DOCGEN
an output file must be selected using either the
'*!' (create) or '*>' (append) tags.
: -DOCGEN \ -- ; disable DOCGEN
Disables DocGen generation of documentation. Note that the
active output file is closed, and a new output file must
be specified after +DOCGEN
is used again.
: PARSED \ c-addr u --
Similar to INCLUDED
but performs no actual compilation.
Macros are expanded, and file extensions are resolved.
PARSED
allows formal comments to be processed from any
suitable source code, for example embedded systems code
for cross compilers.
+DOCGEN
must be used before PARSED
to enable the DocGen system,
and -DOCGEN
should be used after the last file has been processed.
See also DOCONLY
below.
: DocOnly \ "<text>" -- ; DOCONLY <filename>
Similar to INCLUDE
but performs no actual compilation. This
allows formal comments to be parsed from any source code,
for example embedded systems code for the MPE cross
compilers. Use in the form DOCONLY <filename>
.
+DOCGEN
must be used before DOCONLY
to enable the
DocGen system, and -DOCGEN
should be used after the last
file has been processed.
: +InternalDocs \ --
Permits generation of documentation for internal use. DocGen
behaves as normal, but also accepts tags of the form +X as well as
the normal *X form. This can be used to generate an additional
level of documentation above that prepared for normal use.
: -InternalDocs \ --
Turns off generation of internal use documentation. Only tags of
the form *X will be accepted.
: +TOC \ --
Turn on Table of Contents generation. The table of contents
file is called "contents.ext" where ext is defined for the
personality being used.
The table of contents file is closed by -DOCGEN
.
+TOC
only affects HTML generation. Tex and Texinfo
can already handle table of contents generation.
The table of contents file has four levels, corresponding to the CH, SE, SS, and SH tags (T, S, N and H tags).
: +Index \ --
Turn on Index generation. The HTML index file is called
"indices.html". The index file is closed by -DOCGEN
.
For Texinfo and Latex2e the index entries are placed in the
output and the index is generated by Texinfo and LaTex.
At present +Index
only affects HTML and Texinfo generation.
The HTML index file can later be sorted using the command line SORT utility which is still present in all versions of Windows. The command line should be:
sort /+51 indices.html /O sorted.html
DocGen produces indices.html with word names starting in column 51. The output of the SORT utility is the file sorted.html.
The command line:
sort /?
will display the command syntax.
N.B. The index file contains no header or footer text, e.g. <HTML>, because the sorting process will move these in the file. After sorting, the file should be edited to add suitable headers and footers. For HTML output, examples follow.
<HTML><BODY bgcolor="#C2C1B4">
<BR><BR><HR><BR><H1><font color="#ff0000">
Index
</font></H1><BR><HR><BR><BR>
...
</HTML>
Texinfo and Latex indices are sorted by the makeindex program. You do not need to call this yourself as it can be handled by the texify program. See the examples at the end of the chapter for more details.
DocGen output is derived from formal comments within the source code. The output format defaults to HTML 5.0. The layout of the final document is controlled by DocGen tags at the start of the comment and by formatting macros within the body of the comments.
The DocGen comment takes one of the following two forms:
\ *xy blah blah
\ *x blah blah
where the backslash character '\' must be in the first column, and XY and X are the operation codes or tags and "blah blah" is the control text.
( *XY blah blah )
( *x blah blah )
where the open bracket must be in the first column, the closing bracket must be the last character, and XY and X are operation codes or tags and "blah blah" is the control text.
The use of two-character tags and backslash comments is recommended. Every single character tag has a corresponding two-character tag. Not all two-character tags have single character equivalents, for example the conditional documentation tags, *IF, *EL and *TH have no single-character equivalents. All new DocGen tags will be two-character tags.
Please examine MPE supplied sources for a view of how DocGen is used to build library and API documentation.
** |
The following text is a continuation for the current style. This can only be used after a GL, EX, DF, IT, QU or PA tag. |
!! |
Create and select a new output file. The control text is the filename without extension. The remaining text is the description which in HTML becomes the contents of the <title>text</title> tag. |
^^ |
Create and select a new output file. The control text is the filename without extension. No header is added. This tag allows you to generate completely custom formats in HTML using W tags. |
>> |
Select and append to an existing output file. The control text is the filename without extension. No header is added. |
## |
Finalize the current HTML page. Outputs a canned HTML footer which closes off the sections used by the canned header. |
CH |
Following text is a chapter/section title. |
SE |
Following text is a section sub-title. |
SS |
Following text is a section sub-sub-title. |
SH |
A simple heading. |
DF |
Following text is a definition. The first space delimited token is the term, the remaining text the description. |
PA |
Begins a new paragraph. |
EX |
Begins a paragraph which is a code example. |
L( |
Starts a bullet list. The first character of the text defines how the lists are marked. No text produces bullets, 1 produces a numbered list and A or a produce lettered lists. Lists may be nested. N.B. Previous markups that did not use the *( and *) tags still function as before, but the new layout is generally visually better. Note that the LaTeX personality only handles bulleted and numbered lists. See the change notes section of this chapter for more details. |
IT |
Following text is a bulleted item. |
L) |
Ends a bulleted list. |
GL |
Following text is a glossary entry. The preceeding line is output in a fixed font code format. |
RH |
Following text is output directly when using HTML output. |
RL |
Following text is output directly when using LaTeX output. |
RM |
Following text is output directly when using Markdown output. |
RT |
Following text is output directly when Using Texinfo output. |
CD |
A fixed font line, e.g. a code example |
QU |
A quotation which may extend over several lines. |
C( |
The following code will also be copied into the documentation. DocGen lines are handled as usual. You must use the *] tag to stop copying - it is not halted by other tags. Do not use any other tags before copying is stopped. |
C) |
Stops copying code into the documentation. |
HR |
Inserts a line break, full width horizontal rule and a line break. Any text after the tag is ignored. |
IF |
The text after the tag is |
EL |
If the previous IF result was non-zero, production stops until the next TH tag. If the previous IF result was zero, production restarts. |
TH |
The end of a DocGen IF ... EL ... TH set of lines. |
EV |
Evaluate the rest of the line as Forth source. Use this to define Forth flags that can later be tested by an IF tag. Out using |
*EV 1 constant Windows?
*EV 0 constant Mac?
*EV 0 constant Embedded?
* |
The following text is a continuation for the current style. This can only be used after a G, E, D, B, Q or P tag. |
! |
Create and select a new output file. The control text is the filename without extension. The remaining text is the description which in HTML becomes the contents of the <title>text</title> tag. |
^ |
Create and select a new output file. The control text is the filename without extension. No header is added. This tag allows you to generate completely custom formats in HTML using W tags. |
> |
Select and append to an existing output file. The control text is the filename without extension. No header is added. |
# |
Finalize the current HTML page. Outputs a canned HTML footer which closes off the sections used by the canned header. |
T |
Following text is a section title. |
S |
Following text is a section sub-title. |
N |
Following text is a section sub-sub-title. |
H |
A simple heading. |
D |
Following text is a definition. The first space delimited token is the term, the remaining text the description. |
P |
Begins a new paragraph. |
E |
Begins a paragraph which is a code example. |
( |
Starts a bullet list. The first character of the text defines how the lists are marked. No text produces bullets, 1 produces a numbered list and A or a produce lettered lists. Lists may be nested. N.B. Previous markups that did not use the *( and *) tags still function as before, but the new layout is generally visually better. Note that the LaTeX personality only handles bulleted and numbered lists. See the change notes section of this chapter for more details. |
B |
Following text is a bulleted entry. |
) |
Ends a bullet list. |
G |
Following text is a glossary entry. The preceeding line is output in a fixed font code format. |
R |
Following text is output directly when using TeX output. |
W |
Following text is output directly when using HTML output. |
C |
A fixed font line, e.g. a code example |
Q |
A quotation which may extend over several lines. |
[ |
The following code will also be copied into the documentation. DocGen lines are handled as usual. You must use the *] tag to stop copying - it is not halted by other tags. Do not use any other tags before copying is stopped. |
] |
Stops copying code into the documentation. |
L |
Inserts a line break, full width horizontal line and a line break. Any text after the tag is ignored. |
The following tags are reserved by MPE for use with DocGen/SC for safety critical applications.
*O *A *V *U *M *X *Y *Z
If you extend DocGen yourself, avoiding these tags will help to ensure compatibility with future versions of DocGen. DocGen/SC is described later in this chapter.
From VFX Forth v3.70 onwards DocGen supports formatting commands that can be included inside DocGen comments. Commands are of the form
... *\command{text} ...
The text is processed and output. The following commands are supported in all three default personalities.
bold |
Displays text in bold. |
b |
as bold |
fixed |
Displays text in a |
f |
as fixed |
italic |
Displays text in italic. |
i |
as italic |
forth |
Displays text in |
fo |
as forth |
br |
generates a line break. The text is ignored. |
starbslash |
Displays *\. The text is ignored. |
These commands are used to change the formatting of small pieces of text and make it easier to identify what is being referred to. For example, a reference to a Forth word can be produced by:
\ ** the word *\forth{DUP} is often used
which produces the result:
\ ** the word DUP
is often used
Tables are described using DocGen macros, which are not present in the LaTex personality.
table{list} |
Starts a table. The list contains an optional caption delimited by '"' characters, followed by space separated numbers. These are the percentage widths of each column in the table, and so the list also defines the number of columns in the table. There may be up to 16 columns. |
endtable{} |
Marks the end of the table. |
hrow{} |
Marks the start of a header row. Header rows are formatted differently from normal rows. |
row{} |
Marks the start of a normal row. |
col{} |
Marks the start of a new column in a row - you do need this for the first column. |
An image (graphics file) is incorporated using the image
macro, which is not present in the LaTex personality.
It is used in the form:
*\image{"caption" "file" "ext" hmm w%}
where caption is the text of the image caption; file is the basic file name with no extension; ext is the file extension; hmm is the image height in millimetres for Texinfo and LaTex; and w% is the image width in percent for HTML. All five parameters must be present.
Not all personalities will use all the parameters. For example, when using pdftex the file extension may be unused, and pdf images are always used. When using HTML output the hmm parameter is ignored, and the image size is taken from the percentage width.
When preparing PDF images for use with pdftex, note that most tools generate PDF pages. Consequently, when preparing an image for export as a PDF image, first select portrait or landscape page format as appropriate, then scale the image to fit the page, and then save it as a PDF file. OpenOffice Draw is a suitable tool for converting most graphics files into PDF format.
You can extend the DocGen system yourself. Many utility words
are available in the module DOCGEN
. Because of the number
of words you will have to write, we recommend that new
personalities be defined in a VOCABULARY
or a
MODULE
. Use the DocGen source code in
Sources\Lib\Docgen4.fth as a model. The previous version
is in Sources\Lib\Docgen3.fth.
WARNING: From build 1720 onwards DocGen specific utility
words defined in the DOCGEN
module are no longer
EXPORT
ed. You must now surround the code that uses
them with the following fragment:
expose-module docgen
...
previous
Defining a new personality consists of naming it, defining the file extension that will be added to the output file name, and then defining the tags that the personality will react to. It is recommended that you provide actions for all the tags provided as default, so that DocGen will still be able to generate documentation using any of the predefined personalities. The example below is for the default HTML personality.
[DocGen Docgen_html
DG_FileExt: html
\ the continuation tag entry exit continuation
DG_Tag: * 0 illegal illegal illegal
\ tags whose text must fit on one line
DG_Tag: ! -1 >newf illegal illegal
DG_Tag: > -1 >tofl illegal illegal
DG_Tag: T -1 >titl illegal illegal
DG_Tag: S -1 >sect illegal illegal
DG_Tag: N -1 >sstl illegal illegal
DG_Tag: H -1 >head illegal illegal
DG_Tag: R -1 2drop illegal illegal
DG_Tag: W -1 >rweb illegal illegal
DG_Tag: C -1 >code illegal illegal
\ tags that can have continuation lines
DG_Tag: D 1 >defn defn> defn
DG_Tag: P 1 >para para> para
DG_Tag: E 1 >exam exam> exam
DG_Tag: B 1 >bult bult> bult
DG_Tag: G 1 >glos glos> glos
DG_Tag: Q 1 >quot quot> quot
DG_Type: HTMLtype
[DG_Macros
: bold \ caddr u --
." <B>" prepro HTMLtype ." </B>"
;
: fixed \ caddr u --
." <TT>" prepro HTMLtype ." </TT>"
;
: italic \ caddr u --
." <I>" prepro HTMLtype ." </I>"
;
: forth \ caddr u --
." <B><TT>" prepro HTMLtype ." </TT></B>"
;
: starbslash \ caddr u --
2drop S" *\" HTMLtype
;
DG_Macros]
DocGen]
[DOCGEN <name>
defines a new personality. When
<name>
is executed, it becomes the current personality.
DG_FileExt: <ext>
specifies the extension that will be
added to the output file names for this personality.
DG_Tag:
specifies the character, control code, and
actions of a tag. The given character is used as the second
character of the '*x' pair. The second entry is the control
code and specifies the state conditions required, see later.
The next three entries are the names of the Forth words
executed on entry to the tag, on exit from that tag when
another tag is selected, and how that tag line should be
handled. See later for how the three action words should be
defined.
DG_Type: <name>
specifies that <name>
is the word
used for TYPE
ing output.
The pair [DG_Macros
and DG_Macros]
delimit command
words defined in the personality's private wordlist. These
provide the actions of the command macros.
DOCGEN]
marks the end of the personality description.
DocGen operates using three states - entry, exit and
continuation. When a new tag is encountered, the previous
tag's exit code is run if the control code is non-zero. The
exit code can for example add a </P>
paragraph end
marker to HTML code.
If the tag's control code is 1, the new tag becomes the currently active tag so that the '**' tag knows what to do, and the entry code for the new tag is run. This is the normal condition for a tag that can have continuation lines.
If the tag's control code is -1, the entry code is run, and the currently active tag state is set to none. A condition code of -1 is used for tags whose following text must fit on a single line, for example section titles.
If the tag's control code is 0, the continuation action of the previous tag is run.
The stack comments of the three action words are as follows. Text output
of words such as EMIT
and TYPE
has already been set to go to the last
defined output file.
: entry \ caddr u -- ; consumes the text for the line
: continue \ caddr u -- ; consumes the text for the line
: exit \ -- ; close the tag
The utility word PREPRO
is part of the primary definition and converts any
special characters in the DocGen comments. PREPRO
has the stack effect:
caddr u -- caddr' u'
where caddr u defines the input text and caddr' u' defines the output text. The MPE handlers use the following special characters apart from those special to the output format itself.
0x09 |
tab character, convert to spaces, tab width is set to 8 characters |
0x1E |
convert to open bracket character |
0x1F |
convert to close bracket character |
The following code is for the glossary *G
tag in the
HTML output. The word LASTDEFINITIONLINE
returns the
text for the previous line.
: >glos \ caddr u --
cr ." <PRE><CODE><B>" LastDefinitionLine prepro type
." </B></CODE></PRE><P ALIGN=JUSTIFY>"
cr prepro type
;
: glos \ caddr u --
cr prepro type
;
: glos> \ --
cr ." </P>" cr
;
The utility words NewDocFile
and SwitchDocFile
are provided to aid
construction of the *! and *> tags which create a new file or append to
an existing file. Both have the stack comment:
caddr u --
which is the file name without extension. NewDocFile starts a new file, and you can add any required file entry code as required. SwitchDocFile switches to the end of the named file.
The word PREPRO
is available for processing text for
tags and formatting macros. It has the stack comment
caddr len -- caddr' len'
The input text is processed and passed to an output buffer. Special DocGen charactes (TAB, 0x1E, 0x1F) are converted and format commands are processed.
DocGen supports formatting commands that can be included inside DocGen comments. Commands are of the form
... *\command{text} ...
Each command is handled by a Forth word defined in a private
wordlist
for the personality. The command word is
passed the string text, and has the stack comment
caddr len --
Formatting commands use ."
and friends for output. The
text defined by caddr/len must be processed by PREPRO
before output. The string returned by PREPRO
must be
output by a version of TYPE
specific to the personality.
caddr len --
The HTML version, called HTMLtype
outputs the text
converting special characters to the form required by the
output format, e.g it must handle '<' and '>' for HTML and
'\' for Tex.
: [DocGen \ "<spaces>name" -- ; -- ; start new DOCGEN personality
Defines the start of a new personality for DocGen. See the example above
for details of the use of [DOCGEN
and DOCGEN]
.
: DocGen] \ -- ; end personality
Marks the end of a new personality for DocGen. See the example above
for details of the use of [DOCGEN
and DOCGEN]
.
: DG_FileExt: \ "<spaces>text" -- ; define document file extension
Defines the file extension for the DocGen personality being defined.
See the example above
for details of the use of DG_FILEEXT:
.
: DG_Personality? \ xt -- ; check if xt is current personality
Check if xt is the active personality
' docgen_html DG_Personality? [if] ... [then]
: DG_Tag: \ "<char>" "<code>" "<enter>" "<exit>" "<continue>" --
Defines how a tag character is handled by DocGen.
See the example above
for details of the use of DG_TAG:
: DG_Type: \ "<word>" --
Specifies the word which performs the action of TYPE
( addr len -- ) for this personality. Special characters
are translated, e.g. in HTML the '<' character is issued
as "<". Use in the form:
DG_Type: <name>
: [DG_Macros \ -- oldcurrent
Marks the start of defining formatting macros.
: DG_Macros] \ oldcurrent --
Marks the end of defining formatting macros.
: .DG_Macros \ --
Show the available formatting macros in the current
personality.
: .DG_Tags \ --
Show the available tags in the current personality.
This personality generates HTML output. From June 2017 onwards, the output is HTML5 using a CSS stylesheet, bootstrap.3.3.7.min.css. The CSS file is "minified" to reduce its size.
The '*!' tag generates a default HTML header. When this is not needed, use the '*^' tag instead and no header is made. The '*^' tag is often used whn a fully custom index.html is being used, for example to use iframe tags.
Providing that the '*#' tag is used to provide the HTML5 footer, HTML5 files produced by DocGen will pass validation testing.
: MakeBootstrapFile \ --
HTML5 documents need a CSS file to output correctly.
This word generates the DocGen default CSS file,
bootstrap.3.3.7.min.css in the current directory.
The file is only created if it does not exist.
[DocGen Docgen_html \ -- ; -- ; select HTML5 for DOCGEN
Makes the HTML5 personality the current personality for
DocGen. HTML5 will remain the current personality until
another personality is selected.
: HTMLback \ caddr len --
Sets the HTML background colour for the next output file.
The string is the HTML colour reference (limited to 31
characters), e.g.
s" #00C1B4" HTMLback
: bold \ caddr u --
Macro to display string in bold text.
*\bold{text in bold}
: fixed \ caddr u --
Macro to display string in a fixed-width font.
*\fixed{text in fixed font}
: italic \ caddr u --
Macro to display string in an italic font.
*\italic{text in italic font}
: forth \ caddr u --
Macro to display text as Forth source - bold and fixed font.
*\forth{text in Forth font}
: br \ caddr u --
Macro to insert a line break. Any text is ignored.
*\br{}
: starbslash \ caddr u --
Macro to insert *\'. Any text is ignored.
*\starbslash{}
: table \ caddr len --
Table start macro. The text is a quoted caption followed
by a list of column widths in per-cent. For a table with
three columns, use (say)
*\table{ "Table caption" 20 20 60 }
: endtable \ caddr len --
Table end macro. Any text is discarded
*\endtable{}
: row \ caddr len --
Macro that marks the start of a normal row. Any text is
discarded.
*\row{}
: hrow \ caddr len --
Macro that marks the start of a header row. Any text is
discarded.
*\hrow{}
: col \ caddr len --
Macro that marks the start of a column. Any text is
discarded.
*\col{}
: image \ caddr len --
Macro to display an image from a file.
*\image{"caption" "file" "ext" hmm w%}
where caption is the text of the image caption; file is the basic file name with no extension; ext is the file extension; hmm is ignored for HTML; and w% is the image width in percent for HTML. All five parameters must be present.
: lname \ caddr len --
HTML specific. Defines the current location as a point in the file that
can be jumped to later by a link
. The text is the
name of the location.
*\lname{ linkname }
: link \ caddr len --
HTML specific. Create a link to a previous lname
in the current file.
the link is of the form "#linkname" and so must be in the
current output file.
*\link{linkname}
: htarget \ caddr len --
Defines the current location as a point in the file that
can be jumped to later by a href
. The caption text
is optional.
*\htarget{ "targetname" "caption" }
: href \ caddr len --
Create a link to another file or object. For HTML, the URL
text is what is linked to and the display text is what is
shown in the link.
*\href{"url" "display"}
: b bold ;
Convenient redefinition.
: f fixed ;
Convenient redefinition.
: i italic ;
Convenient redefinition.
: fo forth ;
Convenient redefinition.
This personality generates Markdown output. It does not yet support all the features of the other personalities; in particular it does not provide a table of contents or an index.
To view Markdown text, the most convenient solution is probably to add the Markdown Viewer to Google Chrome. Remember to check the box to enable access to file URLs.
[DocGen Docgen_markdown \ -- ; -- ; select Markdown for DOCGEN
Makes the Markdown personality the current personality for
DocGen. Markdown will remain the current personality until
another personality is selected.
: bold \ caddr u --
Macro to display string in bold text.
*\bold{text in bold}
: fixed \ caddr u --
Macro to display string in a fixed-width font.
*\fixed{text in fixed font}
: italic \ caddr u --
Macro to display string in an italic font.
*\italic{text in italic font}
: forth \ caddr u --
Macro to display text as Forth source - bold and fixed font.
*\forth{text in Forth font}
: br \ caddr u --
Macro to insert a line break. Any text is ignored.
*\br{}
: starbslash \ caddr u --
Macro to insert '*\'. Any text is ignored.
*\starbslash{}
: table \ caddr len --
Table start macro. The text is a quoted caption followed
by a list of column widths in per-cent. For a table with
three columns, use (say)
*\table{ "Table caption" 20 20 60 }
: endtable \ caddr len --
Table end macro. Any text is discarded
*\endtable{}
: row \ caddr len --
Macro that marks the start of a normal row. Any text is
discarded.
*\row{}
: hrow \ caddr len --
Macro that marks the start of a header row. Any text is
discarded.
*\hrow{}
: col \ caddr len --
Macro that marks the start of a column. Any text is
discarded.
*\col{}
: image \ caddr len --
Macro to display an image from a file.
*\image{"caption" "file" "ext" hmm w%}
where caption is the text of the image caption; file is the basic file name with no extension; ext is the file extension; hmm is ignored for HTML; and w% is the image width in percent for HTML. All five parameters must be present.
: href \ caddr len --
Create a link to another file or object. For HTML, the URL
text is what is linked to and the display text is what is
shown in the link.
*\href{"url" "display"}
: b bold ;
Convenient redefinition.
: f fixed ;
Convenient redefinition.
: i italic ;
Convenient redefinition.
: fo forth ;
Convenient redefinition.
This personality generates TeXinfo output, using the file texinfo.tex supplied with many TeX distributions. From TeX you can get to many other formats including PDF. Although we originally recommended
TeXinfo is under-documented, especially in terms of examples, and has quirks. Despite this, Texinfo can generate good quality PDF files with bookmarks and thumbnails, a table of contents and an index. The MikTex CD package (see below) includes the Texinfo manual file doc\texinfo\texinfo.dvi which can be viewed using bin\yap.exe. Texinfo is a real "techie" extension to LaTex, but the more we use it, the more we appreciate it. It is worth the admittedly steep learning curve. Texinfo code can be found in the examples at the end of this chapter.
Glossary entries (the ones with *G
tags are indexed.
Additional indexing macros will be added in a future release.
For Windows, the MikTeX package should be suitable for use with the output of DocGen and the file texinfo.tex is required. In addition, a converter from the TeX DVI output format to PDF will be required if PDF manuals are to be generated and if you do not have pdftex or pdflatex. MikTeX includes pdflatex which is a version of LaTeX that produces PDF files directly. Most distributions include pdftex which performs the same operation and may be more suitable for TeXinfo than pdflatex.
The MikTeX home page is at www.miktex.org. Note that the v2.4 small distribution is over 24Mb. For other distributions, which are much larger, a CD is available from the home page for a small charge. We encourage you to get the CD of the latest release if you intend to use Texinfo.
If you are using the v2.4 distribution supplied by MPE,
install the MikTex package by running the installer.
Make sure that the MIKTEX\BIN directory is in your search
path, and generate a master document file using MANUAL.TEX
as a template. Run DocGen with the DOCGEN_TEXINFO
personality
to produce your output files, and make sure that you have
included lines of the form @include file.tex for each file
in the manual. Then run LATEX.EXE MANUAL to produce a DVI
file or PDFLATEX.EXE MANUAL to produce a PDF file.
Not all versions of Tex include the indexing package texindex.exe or the Texinfo package. For windows you can get them from the GnuWin32 project:
http://gnuwin32.sourceforge.net/packages/texinfo.htm
For texindex you probably need only the binaries and can probably discard everything except the directory containing texindex.exe which needs to be put in some directory in your PATH. You may also want to keep the documentation, texindex.1.txt.
: lpc \ char -- char'
Convert char to lower case if it was alphabetic.
[DocGen DocGen_TexInfo \ -- ; -- ; select TeX personality
This word makes the TexInfo personality the current personality for
DocGen. TexInfo will remain the current personality until another
personality is selected.
: bold \ caddr u --
Macro to display string in bold text.
*\bold{text in bold}
: fixed \ caddr u --
Macro to display string in a fixed-width font.
*\fixed{text in fixed font}
: italic \ caddr u --
Macro to display string in an italic font.
*\italic{text in italic font}
: forth \ caddr u --
Macro to display text as Forth source - bold and fixed font.
*\forth{text in Forth font}
: br \ caddr u --
Macro to insert a line break. Any text is ignored.
*\br{}
: starbslash \ caddr u --
Macro to insert *\'. Any text is ignored.
*\starbslash{}
: table \ caddr len --
Table start macro. The text is a quoted caption followed
by a list of column widths in per-cent. For a table with
three columns, use (say)
*\table{ "Table caption" 20 20 60 }
: endtable \ caddr len --
Table end macro. Any text is discarded
*\endtable{}
: row \ caddr len --
Macro that marks the start of a normal row. Any text is
discarded.
*\row{}
: hrow \ caddr len --
Macro that marks the start of a header row. Any text is
discarded.
*\hrow{}
: col \ caddr len --
Macro that marks the start of a header row. Any text is
discarded.
*\hrow{}
: image \ caddr len --
Macro to display an image from a file.
*\image{"caption" "file" "ext" hmm w%}
where caption is the text of the image caption; file is the basic file name with no extension; ext is the file extension; hmm is the height in mm except for HTML; and w% is the image width in percent for HTML, ignored here. All five parameters must be present.
: rawimage \ caddr len --
Macro to display an image from a file.
*\rawimage{ "file" "w" "h" "alttext" ".ext" }
where file is the basic file name with no extension; ext is the file extension; w% is the image width in mm; and h is the height in mm. All five parameters must be present.
: href \ caddr len --
Create a link to another file or object. The URL
text is what is linked to and the display text is what is
shown in the link.
*\href{"url" "display"}
: url \ caddr len --
Create a link to another file or object. The URL
text is what is linked to and the display text is also the link.
*\url{"url"}
: b bold ;
Convenient redefinition.
: f fixed ;
Convenient redefinition.
: i italic ;
Convenient redefinition.
: fo forth ;
Convenient redefinition.
This personality generates LaTeX2e output. From LaTeX2e you can go to many other formats including PDF. See the previous TeX section for details of the required associated tools and their installation.
Install the MikTex or Texlive package by running the installer. Make sure that the MIKTEX\BIN directory is your search path, and generate a master document file using MANUAL.TEX as a template. Run DocGen with the DOCGEN_LATEX personality to produce your output files, and make sure that you have included lines of the form "\include{file}" for each file in the manual. Then run "LATEX.EXE MANUAL" to produce a DVI file, or "PDFLATEX.EXE MANUAL" or "PDFTEX MANUAL" to produce a PDF file.
The output of DocGen is a set of LaTex2e files as defined by the tags above. The manual is then generated by processing these files with PDFLATEX.EXE. An example of MANUAL.TEX is given below. Each file that you want to process should have a line of the form "\include{filename}" where the .TEX extension will be assumed.
\documentclass[a4paper, 10pt]{book}
\parindent 0pt
\parskip 1ex plus .5ex
\begin{document}
\include{docgen}
\end{document}
The output of running PDFLATEX MANUAL will be file called MANUAL.PDF ready for distribution. There will also be a large number of MANUAL.* temporary files, all of which can be deleted as required. The only one of potential interest is MANUAL.LOG, which contains the error report. In most cases, there will be many reports of the form "Overfull \hbox" which can be ignored.
You can configure the appearance of the manual by editing MANUAL.TEX as you require. LaTeX is a very powerful document processing system, and you can modify nearly everything, as well as add indices and so on. Several books about LaTeX and TeX are available from Amazon, and the best source of information about the system is at www.tex.ac.uk which will point you at implementations for many machines as well as several tutorial packages.
Adding a title page requires a few more lines, and an example is given below.
\NeedsTeXFormat{LaTeX2e}
\documentclass[a4paper, 10pt]{book}
\parindent 0pt
\parskip 1ex plus .5ex
\begin{document}
\author{MicroProcessor Engineering Ltd}
\title{DOCGEN/SC}
\maketitle
\include{docgensc}
\end{document}
Adding a table of contents requires only a few more lines, and an example is given below.
\NeedsTeXFormat{LaTeX2e}
\documentclass[a4paper, 10pt]{book}
\parindent 0pt
\parskip 1ex plus .5ex
\begin{document}
\author{MicroProcessor Engineering Ltd}
\title{DOCGEN/SC}
\maketitle
\pagenumbering{roman}
\tableofcontents
\newpage
\pagenumbering{arabic}
\include{docgensc}
\end{document}
Note that in order to generate a table of contents, LATEX needs to be run twice. On the first run, the table of contents will be inaccurate as the table of contents file will be the one from the previous run which is unlikely to match the new first run. After the second run on the same files, the table of contents will be accurate.
[DocGen DocGen_LaTex \ -- ; -- ; select LaTeX personality
This word makes the LaTex personality the current personality for
DocGen. LaTex will remain the current personality until another
personality is selected. See the previous section about TeX for
details of the system requirements.
: bold \ caddr u --
Macro to display string in bold text.
*\bold{text in bold}
: fixed \ caddr u --
Macro to display string in a fixed-width font.
*\fixed{text in fixed font}
: italic \ caddr u --
Macro to display string in an italic font.
*\italic{text in italic font}
: forth \ caddr u --
Macro to display text as Forth source - bold and fixed font.
*\forth{text in Forth font}
: br \ caddr u --
Macro to insert a line break. Any text is ignored.
*\br{}
: starbslash \ caddr u --
Macro to insert *\'. Any text is ignored.
*\startbslash{}
: href \ caddr len --
Create a link to another file or object. For HTML, the URL
text is what is linked to and the display text is what is
shown in the link.
*\href{"url" "display"}
The hyperref package is needed. Include the line below where other packages are loaded.
\usepackage{hyperref}
: b bold ;
Convenient redefinition.
: f fixed ;
Convenient redefinition.
: i italic ;
Convenient redefinition.
: fo forth ;
Convenient redefinition.
The VFX Forth Kernel contains DEFER
ed hooks at strategic
points within the compiler/interpreter. These hooks are used by
DocGen to install and uninstall itself.
The DocGen hooks are:-
defer DOCGEN_PREREFILL \ --
Called within REFILL
before another line of text is read.
defer DOCGEN_REFILL \ --
Called within REFILL
after the next text line has been read.
at this point you may process the INPUT buffer (from SOURCE
) but
you must not under any circumstances change it.
defer -DOCGEN_HOOK \ --
Disables DocGen without closing the active output file. This
is useful for conditional generation of documentation,
particularly if several versions of the software exist.
Note that files containing such phrases must be INCLUDE
d,
as DocOnly
turns off the Forth interpreter.
[undefined] <someword> [if] -docgen_hook [then]
\ ** This documentation is needed if <someword>
\ ** exists ...
+docgen_hook
defer +DOCGEN_HOOK \ --
Enables DocGen output again. See the previous example
You can make manual generation very much easier by creating some auxiliary files which manage the process.
INCLUDE
d by VFX Forth to create
the HTML and/or Tex files. This file often also
INCLUDE
s the file below. To distinguish it, we
usually give this file a ".DGS" extension.Examples are given of all of these files, somewhat attenuated to remove obvious repetition. The examples are taken from the documentation for the MPE ARM USB Stamp on-board software. Both HTML and PDF files are produced.
These examples contain several "MPEisms", in particular the use of ### files. After DocGen has finished, we will find files ###.html and ###.tex. If these files have anything in them, some documentation has been missed. When a source file ends, the following section adds further DocGen output to the junk file:
\ ======
\ *> ###
\ ======
At the start of each source file, you must declare where output goes using one of the '*!' or '*>' tags. Thus the ### junk files collect any documentation that has been written but not associated with an output file. Looking at the junk files tells you if this has happened.
There are two sections to this file, one for the HTML documentation and one for the Texinfo code that then creates the PDF documentation.
\ USBSTAMP.DGS - ARM USB Stamp DOCGEN control file
\ turn on DOCGEN and select personality
+docgen docgen_html
cr ." Starting HTML manual generation" cr
The following section produces the main HTML file with a left-hand chapter selection menu.
\ *^ index
\ *W <!DOCTYPE html>
\ *W <html lang="en">
\ *W <head>
\ *W <meta charset="utf-8">
\ *W <meta http-equiv="X-UA-Compatible" content="IE=edge">
\ *W <meta name="viewport" content="width=device-width, initial-scale=1">
\ *W <title>MPE VFX Forth for Windows User Manual</title>
\ *W
\ *W <!-- Bootstrap core CSS -->
\ *W <link href="bootstrap.min.css" rel="stylesheet">
\ *W <script src="script.js"></script>
\ *W <style type="text/css">
\ *W #left_frame {
\ *W width: 30%;
\ *W height: 100vh;
\ *W border: 0px;
\ *W }
\ *W #right_frame {
\ *W width: 70%;
\ *W height: 100vh;
\ *W border: 0px;
\ *W }
\ *W #left_frame,
\ *W #right_frame { float: left; }
\ *W
\ *W </style>
\ *W </head>
\ *W
\ *W <body>
\ *W
\ *W <iframe id="left_frame" src="mainmenu.html" name="menu"></iframe>
\ *W <iframe id="right_frame" src="titlepg.html" name="main"></iframe>
\ *W
\ *W </body>
\ *W </html>
\ *> ###
Then we can create the chapter selection menu, which references the HTML files produced by DocGen.
\ *! menu
\ *W <A target="main" HREF="stamptitle.html" >Home</A><BR>
\ *W <A target="main" HREF="intro.html" >Introduction</A><BR>
\ *W <A target="main" HREF="codearm.html" >Low level Kernel</A><BR>
...
\ *W <A target="main" HREF="romforth.html" >ROM FORTH extensions</A><BR>
\ *W <A target="main" HREF="xmodemtxrx.html" >XModem File Transfers</A><BR>
\ *> ###
We can create a title page.
\ *! stamptitle
\ *W <TABLE border=0 cellPadding=0 cellSpacing=0 width="100%">
\ *W <TBODY>
\ *W <TR><TD>
\ *W <IMG src="mpelogo.gif">
\ *W </TD></TR>
\ *W </TBODY>
\ *W </TABLE>
\ *W <CENTER>
\ *W <H1>MPE ARM Stamp Software Reference Manual</H1>
\ *W <P>7 October 2004</P>
\ *W <P><I>Documentation derived from the source code by DOCGEN
\ *W with VFX Forth for Windows
\ *W </I></P>
\ *W <BR><BR><BR>
\ *W <B>(C)opyright 2004 MicroProcessor Engineering Limited.</B>
\ *W </CENTER>
\ *> ###
Now we can generate all the other files from the second file. Because DocGen automatically adds a colour to the start of the INDEX.HTML file, we include a comment to remove it because it will be in the wrong place when frames are used.
include stampfiles
cr ." HTML Manual generation done" cr
cr
cr ." ***********************************"
cr ." Remove the BODY tag in the first line of INDEX.HTML"
cr ." ***********************************"
cr
-docgen
The procedure is essentially the same for the PDF documentation, except that the table of contents is produced by Texinfo.
\ turn on DOCGEN and select personality
+docgen docgen_texinfo
cr ." Starting Texinfo manual generation" cr
\ ===============
\ Tex manual file
\ ===============
\ *! manual
\ *R \input texinfo
\ *R @setfilename usbstamp.info
\ *R @setcontentsaftertitlepage
\ *R @afourpaper
\ *R @settitle MPE USB Stamp
\ *R @setchapternewpage odd
\ *R @paragraphindent 0
\ *R @exampleindent 0
\ *R @finalout
\ *R @include titlepg.tex
\ *R @include intro.tex
\ *R @include codearm.tex
...
\ *R @include romforth.tex
\ *R @include xmodemtxrx.tex
\ *R @bye
\ *> ###
include stampfiles
cr ." Texinfo Manual generation done" cr
-docgen
If you are generating an index, add the following three lines before the line containing "@bye"
\ *R @unnumbered{Index}
\ *R @*
\ *R @printindex fn
The first section defines a set of text macros to reduce typing and ease changes when the project directories (folders) are moved.
\ STAMPFILES.FTH - DOCGEN include files
c" c:\buildkit.dev\software\rom\arm"
setmacro CpuDir
c" c:\buildkit.dev\software\rom\common"
setmacro CommonDir
c" c:\buildkit.dev\software\rom\examples"
setmacro ExampleDir
c" c:\buildkit.dev\software\rom\arm\hardware\LPC210x"
setmacro StampDir
Now comes the list of files. This file was started before
the word DocOnly
was available. The .FTH extension
is not required as the smart file include system will try
a range of extensions. MPE habit is to give files that
only contain DocGen comments a .MAN extension.
s" intro.man" parsed
s" %CpuDir%\codearm.fth" parsed
s" %CommonDir%\kernel62.fth" parsed
...
s" %CommonDir%\voctools.fth" parsed
s" %CommonDir%\xmodemtxrx.fth" parsed
DocOnly romforth.man
DocOnly examples.man
DocOnly titlepg.man
The batch file controls the whole operation and removes the collection of temporary files produced by PDFTEX or TEXIFY. The "start /w" command is used to make the batch file wait until a GUI program has finished.
Note that if an index is being generated by Texinfo, the line
pdftex manual
must be replaced by
texify -p manual.tex
where the extension must be supplied.
@echo off
rem B.BAT controls the operation
echo *****************************
echo Date changed in USBSTAMP.DGS?
echo *****************************
del *.html
del *.tex
start /w c:\products\pfwvfx\bin\pfwvfx include usbstamp.dgs
echo Error log will be in manual.log
del manual.log
echo starting pass 1 ..
pdftex manual
echo .. pass1 complete, starting pass 2 ..
pdftex manual
echo .. pass 2 completed
pause
move manual.pdf USBStampCode.pdf
echo Manual is in file USBStampCode.pdf
echo Deleting temporary files
move manual.log temp.log
del manual.*
move temp.log manual.log
echo ***********************************
echo Modify the first line of INDEX.HTML
echo ***********************************
echo Press Control-C not to issue manuals
pause
del ###.*
del ..\*.html
del *.tex
move *.html ..
move *.pdf ..
copy *.gif ..
echo Done
pause
This example only applies to the Texinfo personality.
\ ==========
\ *! titlepg
\ ==========
\ *R @titlepage
\ *R
\ *R @title MPE ARM USB Stamp
\ *R @subtitle v1.0
\ *R @author Microprocessor Engineering Limited
\ *R @page
\ *R
\ *R @vskip 0pt plus 1filll
\ *R
\ *R Copyright @copyright{} 2004 Microprocessor Engineering Limited
\ *R
\ *R Published by Microprocessor Engineering
\ *R
\ *R
\ *R
\ *R @page
\ *R
\ *R MPE ARM USB Stamp @*
\ *R User manual @*
\ *R Manual revision 1.00 @*
\ *R @today{} @*
\ *R @*
\ *R @*
\ *R Software @*
\ *R Software version 6.20 @*
\ *R @*
\ *R @*
\ *R For technical support @*
\ *R Please contact your supplier @*
\ *R @*
\ *R @*
\ *R For further information @*
\ *R MicroProcessor Engineering Limited @*
\ *R 133 Hill Lane @*
\ *R Southampton SO15 5AF @*
\ *R UK @*
\ *R @*
\ *R Tel: +44 (0)23 8063 1441 @*
\ *R e-mail: mpe@@mpeforth.com @*
\ *R tech-support@@mpeforth.com @*
\ *R web: www.mpeforth.com @*
\ *R @*
\ *R @page
\ *R @end titlepage
\ ======
\ *> ###
\ ======
DocGen/SC is an extension of DocGen for documenting safety critical systems. DocGen/SC allows test code to be provided after each word and to be extracted to separate test files, so automating the production of regression tests.
DocGen/SC produces documentation that has been accepted by organisations such as the US FDA for medical equipment. The documentation format and test files are also suitable for other authorities and application domains including avionics and transport systems. Contact MPE for more details.
All the tags of DocGen work as they did before. Some new tags have been defined to control the safety critical documentation process.
O |
followed by "initials" "name" "organisation". A list ofauthors is kept and authors only need to be defined once. |
A |
followed by "initials" selects the current author. Onceselected, the author's name and organisation will be outputfor each word definition. |
V |
followed by "version_text" sets the version informationproduced in the header for each definition. |
U |
followed by "10" sets the width of hard tabs, ASCII code 9,to the given integer value. This value defaults to 8, and isused when expanding tab characters in the source code andtest code output. In general, we recommend that hard tabsare always set to 8 characters as this is the default valueused by many applications. |
M |
starts the notes section of the output. |
X |
followed by "filename" defines the file used to containthe test code. This file is closed after each source file is |
Y |
marks the start of the test code section. |
Z |
marks the end of the definition and triggers checks. |