Ada formatting tool.
Copyright 2000, 2002, 2004, 2005, 2006, 2007, 2009, 2011, 2012 AXE Consultants.
P.O. Box 1512, Madison WI 53701
E-Mail: randy@rrsoftware.com
ARM_Form is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License version 3
as published by the Free Software Foundation.
AXE CONSULTANTS MAKES THIS TOOL AND SOURCE CODE AVAILABLE ON AN "AS IS"
BASIS AND MAKES NO WARRANTY, EXPRESS OR IMPLIED, AS TO THE ACCURACY,
CAPABILITY, EFFICIENCY, MERCHANTABILITY, OR FUNCTIONING OF THIS TOOL.
IN NO EVENT WILL AXE CONSULTANTS BE LIABLE FOR ANY GENERAL,
CONSEQUENTIAL, INDIRECT, INCIDENTAL, EXEMPLARY, OR SPECIAL DAMAGES,
EVEN IF AXE CONSULTANTS HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
A copy of the GNU General Public License is available in the file
gpl-3-0.txt in the standard distribution of the ARM_Form tool.
Otherwise, see .
If the GPLv3 license is not satisfactory for your needs, a commercial
use license is available for this tool. Contact Randy at AXE Consultants
for more information.
The formatting tool is written in Ada 2005, but mainly uses Ada 95 constructs.
Thus, it should be possible to compile it with an Ada 95 compiler with only
small modifications.
Running the formating tool:
The formating tool reads the source text input files (.MSS files) in a
Scribe-like format. The files to read, and general formatting parameters,
are controlled by a master input file (.MSM file). The tool allows determining
the output document, format, and other properties.
The output of the tool is written into a subdirectory
"Output" of the directory where Arm_Form is run. The tool is self-contained; it
does not require any pre or post processing except to have Word create the real
table of contents for the .RTF outout.
Usage: Arm_Form [[ [ [ ]]]]
The specifies the layout of the document to generate (see below).
If has no extension, ".MSM" is assumed.
The formats are:
Text: Pure text files. These are missing a lot of formatting; we recommend
using the HTML versions instead.
HTML: (Default) HTML files. The HTML is designed for HTML version 4.0. Old
browsers may display the documents with little formatting.
RTF: RTF files. The RTF files are designed for Word 97 and later. PDF
versions should be created from these file using Word and Adobe tools.
Corr: Text files with !corrigendum like markup.
Info: File in the open source Info format (not supported by AXE).
are:
No-Changes: The original text (same as specifying version 0).
New-Only: Text with changes applied through the specified version.
Show-Changes: The text with changes up through the specified version
applied, and changes marked. For HTML, deleted text is shown
as struck-through and inserted text as underlined. Changes for
different versions are in different colors.
For RTF, this uses Word's "changes" mechanisms, which can
shows changes in different colors.
Changes-Only: The text with changes up through the specified version
applied, and changes for the specified version only marked
as described above.
New-Changes: The text with changes up through the specified version
applied, and insertions marked. Deletions are marked by just a
single blank space. (See above for how these are marked). This
form is intended to be used with revision bars in Word 97/2000
(Older versions of Word do not reformat the document when
deletions are hidden, leaving unsightly blank spaces. This is
not a problem with current versions of Word)
= a value in 0 .. 9 representing the change version desired.
= the path to which to write the result files. This must end
with a path separator.
Summary of commands used in the ARM text input files (.MSM and .MSS files):
Syntax summary:
Commands are represented by @[]. The command name can be an
identifier, or certain special characters. The command name is not
case-sensitive: @newpage; @NewPage; @NEWPAGE; all represent the same command.
The argument list (if any) is surrounded by one of the bracket pairs
(), {}, [], <>, `', or "". These pairs are equivalent, however the matching end
character must be used to close an argument list. The arguments can be
anything. It can be another sequence of text, keywords, or other items
(described below). In this list below, arguments are always signified by {},
but any of the other characters can be used. (Note that there is no escape
character for the brackets, so if one of the bracket characters appears
in the text, a different pair of bracket characters should be used. Also
note that there is no sane way to tell the end of a quoted parameter from a
nested one, so parameters nested in a "" pair should never used "" as their
brackets.)
-----------------
Master file (.MSM) command summary:
The master file determines the source files that make up a document and their
collating order, along with general properties of the output as a whole.
Note that regular source commands are not allowed in the master file, unless
otherwise noted.
Source commands (the order of these determines the collating order):
@Source{Name=,SectionName=,SectionNumber=,NewSection=[T|F]} -
Specifies a source file for the document. The indicates where
the source file is found, and may include a path if desired. If
does not include an extension, ".MSS" is assumed. gives
a short name for the section; it will be used to name the output files,
if appropriate for the specified kind of output. specifies the
section number; it is either a number in the range 0 to 20, or a letter
from A .. Z. If NewSection is true (T), this is the first file for the
indicated section; otherwise, this is a continuation file for the
section. (If this setting is wrong, there will be extra or missing headers
for the section.)
@TOC
Specifies where the table of contents will appear in the collating order;
if this is omitted, there will be no table of contents.
Global properties:
@ShowIndexEntries
If given in the master file, index and glossary entries are visibly
displayed in the document. If this command is not given, these items are
not displayed (although they may create links if the
output format supports links).
@HideIndexEntries
If given in the master file, or ShowIndexEntries is not given, Index and
glossary entries are not displayed in the document (although they may
create links if the output format supports links).
@ShowAnnotations
If given in the master file, annotations will be included in the output.
"Annotations" are often described as belonging to the "AARM" below.
"RMOnly" text is not included in the output. If this command is not given,
the annotations are not included in any form, and "RMOnly" text is
included.
@HideAnnotations
If given in the master file, or ShowAnnotations is not given,
annotations are not included in the output in any form, and "RMOnly"
text is included in the output.
@ShowISO
If given in the master file, text marked "ISOOnly" will be included in the
output. "NotISO" text is not included in the output. If this command is
not given, "ISOOnly" text is not included in any form, and "NotISO" text
is included.
@HideISO
If given in the master file, or ShowISO is not given,
"ISOOnly" text is not included in the output in any form, and "NotISO"
text is included in the output.
@LinkNonTerminals
If given in the master file, non-terminals are linked to their original
definition (as given in @Syn and similar commands). Otherwise,
non-terminals are not linked.
@NumberParagraphs
If given in the master file, paragraphs are numbered per subclause
(as in the Ada Reference Manual). Otherwise, paragraphs are not numbered.
@Title{Version=[],Text=[]}
The document title for version, this is used in headers and footers.
If no title is given for the current version, the title of the previous
version is used; to use the same title for all versions, give the title
for Version=[0].
@FilePrefix{}
This specifies the prefix of the output file(s). All of the output files
will start with this prefix. Keep this short!
@ExampleFont{Swiss|Fixed|Roman}
This specifies which font is used to display examples.
This changes the @Exam{} and @begin{Example} formats.
By default, the Fixed font is used.
@BodyFont{Swiss|Roman}
This specifies which font is used to display the body of the document.
This changes all styles that are not defined to use a specific font.
By default, the Roman font is used.
@NoteFormat{Ada95|ISO2004}
This specifies the format of notes sections.
If Ada95, the word "NOTES" is on a separate line, and each note is
numbered, with the numbers starting at 1 for each section.
If ISO2004, each note starts with the word "NOTE", and a number,
with the numbers starting from 1 for each subclause.
If there is only one note in a subclause, the number should be omitted.
@ContentsFormat{Ada95|ISO2004}
This specifies the format of contents sections.
If Ada95, the title is "Table of Contents".
If ISO2004, the title is "Contents".
@ListFormat{Ada95|ISO2004}
This specifies the format of numbered lists ("enumerate").
If Ada95, they're numbered "1.";
If ISO2004, they're lettered "a)"; inner lists are numbered "1)".
@SubdivisionNames{Chapter|Section|Clause}
This specifies the names of subdivisions and the format of section headers.
Note: In this document, top-level subdivisions are called sections,
and lower-level subdivisions are called clauses, subclauses,
and subsubclauses. The names in the final output may be different.
If Chapter, top-level subdivisions are called "chapters" and this appears
in the titles. Lower-level subdivisions are called "sections". If Section,
top-level subdivisions are called "sections" and this appears in the
titles. Lower-level subdivisions are called "clauses". If Clause,
top-level subdivisions are called "clauses" and this does not appear in
the title of top-level subdivisions (Annex still appears). Lower-level
subdivisions are called "subclauses". If this is not given, "Section"
is used.
HTML Output properties:
@SingleHTMLOutputFile
If given in the master file, generate a single large file for
the output, rather than one file per clause. If this is not given,
smaller files are generated.
@UseMSDOSFilenames
If given in the master file, use 8.3 MS-DOS style filenames.
In this case, the @FilePrefix must be less than 4 characters in size,
and no clause or subclause number should exceed 35
if @SingleHTMLOutputFile isn't given.
@HTMLKind{Version=[3|4Comp|4],Unicode=[T|F]}
Specifies the kind of HTML that will be output.
If Version=3, HTML compatible with (virtually) all browsers will be
generated, but it will have limited formatting. The Unicode setting is
ignored; special characters will be output using ASCII equivalents,
and explicit output with the @Unicode command is prohibited and will
cause an error.
If Version=4Comp, the HTML will have more extensive formatting, but older
browsers will have more limited formatting. If Unicode is true (T),
Unicode characters will be used where appropriate (presuming the
characters are available on the US version of Windows 2000); otherwise
ASCII equivalents will be used. In either case, explicit Unicode
characters (@Unicode) are generated.
If Version=4, the HTML will have the best formatting on modern
browsers (IE 5.0, Firefox 1.0, Netscape 6.2, and later versions of these)
but older browsers will have almost no formatting. If Unicode is true (T),
Unicode characters will be used where appropriate (presuming the
characters are available on the US version of Windows 2000); otherwise
ASCII equivalents will be used. In either case, explicit Unicode
characters (@Unicode) are generated.
The default is a version of 4Comp with Unicode = T.
@HTMLTabs{[SingleSpace|QuadSpace|EmulateFixedOnly|EmulateFixedOnlyQuad|EmulateAll]}
Specifies how tabs are emulated for text.
(HTML does not have tabs, they have to be faked.)
For SingleSpace, the tabs are replaced by a single space (always).
For QuadSpace, the tabs are replaced by a four hard spaces (always).
For EmulateFixedOnly, the tabs are replaced by an appropriate number of
hard spaces for styles using fixed fonts (or if the tab is the first
character on a line); for other styles, a single space is used.
For EmulateFixedOnlyQuad, the tabs are replaced by an appropriate number
of hard spaces for styles using fixed fonts; for other styles, four hard
spaces are used.
For EmulateAll, the tabs are replaced by an appropriate number of
hard spaces for all styles. Note that the number of spaces is a guess
for non-fixed fonts, and it is unlikely that the tabbed text will line up
perfectly.
EmulateFixedOnly is the default (as the result will look correct in a
fixed font).
@HTMLNavBar{RefName=[],SrchName=[],IndexName=[],
UseButtons=[T|F],OnTop=[T|F],OnBottom=[T|F]}
Specifies the properties of the Navigation Bar in the files.
RefName gives the URL of the references page. This can be part of the
current document (in which case the URL can be relative), or an external
page. It will be the URL assigned to the "References" button/label; if set
to null, the "References" button/label will link to the section named
"References" if one exists, or the button/label will be omitted otherwise.
SrchName gives the URL of the search page. This can be a relative or
absolute URL. It will be the URL assigned to the "Search" button/label; if
set to null, the "Search" button/label will link to the section named
"Search" if one exists, or the button/label will be omitted otherwise.
IndexName gives the URL of the search page. This can be a relative or
absolute URL. It will be the URL assigned to the "Index" button/label;
if set to null, the "Index" button/label will link to the section named
"Index" if one exists, or the button/label will be omitted otherwise.
If UseButtons is true (T), the navigation bar will use graphic buttons;
otherwise, text labels will be generated.
If OnTop is true (T), the navigation bar will be on the top of the
document page(s) in the header; otherwise it will not appear on top.
If OnBottom is true (T), the navigation bar will be on the bottom of the
document page(s) in the footer; otherwise it will not appear on the bottom.
One of OnTop or OnBottom should be true, or navigation will be difficult!
By default, the "References" and "Search" buttons are omitted, buttons
are used, and navigation bars are shown on the top and bottom of every
page.
@HTMLHeader{}
Specifies HTML markup for the header of the the document. This will be
repeated on every page, and needs to be a self-contained HTML fragment.
By default, this is empty.
@HTMLFooter{}
Specifies HTML markup for the footer of the the document. This will be
repeated on every page, and needs to be a self-contained HTML fragment.
By default, this is empty.
@HTMLColor{Text=[,Background=[],Link=[],VLink=[],
ALink=[]}
Specifies the default text, background and link colors for the document.
is a color in standard HTML format ("#rrggbb", with each letter
replaced by a hex digit).
VLink is the color for visited links; ALink is the color for links
being clicked. The default is:
@HTMLColor{Text=[#000000],Background=[#FFFFF0],Link=[#0000FF],
VLink=[#800080],ALink=[#FF0000]}
That is, black text, cream background, blue links, purple visited links,
and red active links.
RTF Output properties:
@SingleRTFOutputFile
If given in the master file, generate a single large file for
the output, rather than one file per section. If this is not given,
smaller files are generated.
@RTFHeaderPrefix{Version=[],Text=[]}
The text given in the header before the title; this is *RTF* text; no
embedded commands can be given here. If no header prefix is given for the
current version, the prefix of the previous version is used; to use the
same prefix for all versions, give the prefix for Version=[0]. If this is
empty, only the title will be used.
@RTFFooterText{Version=[],Text=[]}
The fixed text given in the footer; this is *RTF* text; no embedded
commands can be given here. If no footer text is given for the current
version, the text of the previous version is used; to use the same text for
all versions, give the prefix for Version=[0]. This text will not be used
if UseClauseName is True.
@RTFFooter{UseDate=[T|F],UseClauseName=[T|F],UseISOFormat=[T|F]}
Specifies the format of the footer. The date will be included if
UseDate is true (T), otherwise it will be omitted; by default it is
included. The footer text will be the name of the clause that starts the
page (other clauses may start on the page) if UseClauseName is true (T),
otherwise it will be the FooterText. The defailt is to use clause names.
The text font and size will match the ISO requirements if UseISOFormat
is true (T) - this means the footer will be in a Swiss font with multiple
sizes; otherwise (and this is the default) the footer will be in the body
font with a single size.
@RTFPageSize{Letter|A4|HalfLetter|Ada95}
Specifies the size of the RTF output; Letter is used if this is not
specified. Letter is 8.5"x11"; A4 is European standard size; HalfLetter
is 5.5"x8.5"; Ada95 is 7"x9".
@RTFFonts{Serif=[Times|Souvenir],SansSerif=[Arial|Helvetica]}
Specifies the specific fonts used for the Serif and Sans Serif fonts.
If not specified, Times ("Times New Roman") and Arial are used.
@RTFVersionName{Version=[],Text=[]}
The specified text names the version as the "author" of any revisions.
For instance, for the Ada Standard, @RTFVersionName{Version=[2],Text=[Amendment 1]}
gives the author name "Amendment 1" to all version 2 revisions.
Other commands:
@comment{} - The text is a comment to the master file, and is ignored
on output.
---------------------
Source file (.MSS) command summary:
Meta-commands:
@; - Signifies nothing. Used to break a parameterless command from following
text: "@LegalityName@;s" (otherwise the command "LegalityNames" would be
looked for).
@: - After a period, signifies an sentence ending period, rather than a
initial period. Not used currently, but remains in text in case someone
cares eventually. (Only matters if the amount of space after sentences
is different than the amount between words within a sentence.)
@| - Marks a potential line break point, without inserting a hyphen. (Scribe
says that it is a "zero-length word".) Not used currently, as the RTF
command (\zwbo) prints a square box in both Word 97 and Word 2000 -- and
no break. Similarly, zero-width space in HTML 4.0 doesn't work on Internet
Exploder 4.1 - it also prints a square box and no break.
@! - Marks a potential line break point, inserting a hyphen if the break is
used. (A so-called "soft-hyphen"). Unlike the above, this actually
works in Word 97 and HTML. ­.
Text commands:
@@ - the literal character '@'.
@\ - A tab, or end of centered text. Also used to mark the separation between
hanging text and the rest of the paragraph.
@^ - Sets a tab stop at the current text location. (*Can't implement in RTF and
HTML does not have tabs at all; has been removed from the text *)
@ - [@] - A hard space; cannot be used to insert a line break.
@* - Line break inside a paragraph.
@+{} - Superscript text (text size will be smaller).
@-{} - Subscript text (text size will be smaller).
@b{} - Bold text.
@i{} - Italic text.
@r{} - Roman font text.
@ri{} -Roman italic text (use for comments in examples).
@s{} - Swiss font text.
@f{} - Fixed-width font text.
@shrink{} - Text is one size smaller. (Typically 1 point smaller).
@grow{} - Text is one size larger. (Typically 1 point larger).
@black{} - Text is in a black color.
@red{} - Text is in a red color.
@green{} - Text is in a green color.
@blue{} - Text is in a blue color.
@comment{} - The text is a comment to the input files, and is ignored
on output.
@newpage - Insert a page break. Ends a paragraph.
@rmnewpage - Insert a page break in the RM (that is, when HideAnnotations is
used), ignored otherwise. Ends a paragraph. Use to insert page
breaks to make the printed RM look better.
@newcolumn - Insert a column break. Only allowed in a multi-column formats.
Ends a paragraph.
@newpagever{Version=[} - Insert a page break if we are generating
(and ends a paragraph). Otherwise, does nothing.
@rmnewpagever{Version=[} - Insert a page break in the RM (that is,
when HideAnnotations is used) and we are generating ,
ignored otherwise. Ends a paragraph. Use to insert page
breaks to make the printed RM look better.
@isoonlyrmnewpagever{Version=[} - Insert a page break in the RM (that
is, when HideAnnotations is used), @ShowISO was given in
the master file, and we are generating ,
ignored otherwise. Ends a paragraph. Use to insert page
breaks to make the printed RM look better.
@notisormnewpagever{Version=[} - Insert a page break in the RM (that
is, when HideAnnotations is used), @ShowISO was not given in
the master file, and we are generating ,
ignored otherwise. Ends a paragraph. Use to insert page
breaks to make the printed RM look better.
@newcolumnver{Version=[} - - Insert a column break if we are generating
, otherwise does nothing. Only allowed in a multi-column
formats. Ends a paragraph.
@softpage - Insert a soft page break in a format that does not generally
allow one. A page is allowed (but not required) at this point.
[Note: This doesn't seem to work in Word 97, but we've kept it
anyway.]
@noprefix - The following paragraph does not have a prefix (that is, hanging
text, numbers, or bullets). For example, if the paragraph is in
a bulleted list, it will not have a bullet. This command must be
given before any text for the paragraph (including index entries
and even spaces in example formats).
@keepnext - Keep this paragraph with the next one (usually used on leadins,
like "The following example shows...:"). This command must be
given before any text for the paragraph.
@leading - This paragraph leads in an example or list. Cut the space
following the paragraph (usually by 30%). This command must be
given before any text for the paragraph.
@trailing - This paragraph ends an item of some sort. Increase the space
following the paragraph (usually by 50%). This command must be
given before any text for the paragraph.
@noparanum - This paragraph has no number. This command must be
given before any text for the paragraph.
@thinline - Draw a thin separator line across the page. Ends any paragraph.
@thickline - Draw a thick separator line across the page. Ends any paragraph.
-- Section/Clause commands:
@LabeledSection{} - Start a labeled section (chapter). The title will be
"text". The formatter assigns section numbers.
@LabeledSectionNoBreak{} - Start a labeled section (chapter). The
title will be "text". The formatter assigns section numbers. No page
break before it.
@LabeledAnnex{} - Start a labeled (unqualified) annex. The title
will be "text". The formatter assigns annex letters.
@LabeledInformativeAnnex{} - Start a labeled informative annex. The title
will be "text". The formatter assigns annex letters.
@LabeledNormativeAnnex{} - Start a labeled normative annex. The title
will be "text". The formatter assigns annex letters.
@LabeledClause{} - Start a labeled clause. The title will be "text".
The formatter assigns clause numbers.
@LabeledSubClause{} - Start a labeled subclause. The title will be "text".
The formatter assigns subclause numbers.
@LabeledSubSubClause{} - Start a labeled subsubclause. The title will be "text".
The formatter assigns subsubclause numbers.
@LabeledRevisedAnnex{Version=[],
[InitialVersion=[],]New=[],Old=[]} -
Start a labeled (unqualified) annex. The title will be "new_text". If
we are generating an old version of the document, the title is "old_text"
instead. (Note that annex references in commands always use the
new_text name.) The formatter assigns annex letters. Version is the
version number of the change (see @ChgRef for details); InitialVersion
is the original insertion version of the Old text (this defaults to 0
if not given).
@LabeledRevisedNormativeAnnex{Version=[],
[InitialVersion=[],]New=[],Old=[]} -
Start a labeled normative annex. The title will be "new_text". If we
are generating an old version of the document, the title is "old_text"
instead. (Note that annex references in commands always use the
new_text name.) The formatter assigns annex letters. Version is the
version number of the change (see @ChgRef for details); InitialVersion
is the original insertion version of the Old text (this defaults to 0
if not given).
@LabeledRevisedInformativeAnnex{Version=[],
[InitialVersion=[],]New=[],Old=[]} -
Start a labeled informative annex. The title will be "new_text". If we
are generating an old version of the document, the title is "old_text"
instead. (Note that annex references in commands always use the
new_text name.) The formatter assigns annex letters. Version is the
version number of the change (see @ChgRef for details); InitialVersion
is the original insertion version of the Old text (this defaults to 0
if not given).
@LabeledRevisedSection{Version=[],
[InitialVersion=[],]New=[],Old=[]} -
Start a labeled section (chapter). The title will be "new_text". If we are
generating an old version of the document, the title is "old_text" instead.
(Note that clause references in commands always use the new_text name.)
The formatter assigns clause numbers. Version is the
version number of the change (see @ChgRef for details); InitialVersion
is the original insertion version of the Old text (this defaults to 0
if not given).
@LabeledRevisedClause{Version=[],
[InitialVersion=[],]New=[],Old=[]} -
Start a labeled clause. The title will be "new_text". If we are
generating an old version of the document, the title is "old_text" instead.
(Note that clause references in commands always use the new_text name.)
The formatter assigns clause numbers. Version is the
version number of the change (see @ChgRef for details); InitialVersion
is the original insertion version of the Old text (this defaults to 0
if not given).
@LabeledRevisedSubClause{Version=[],
[InitialVersion=[],]New=[],Old=[]} -
Start a labeled subclause. The title will be "new_text". If we are
generating an old version of the document, the title is "old_text" instead.
(Note that clause references in commands always use the new_text name.)
The formatter assigns subclause numbers. Version is the
version number of the change (see @ChgRef for details); InitialVersion
is the original insertion version of the Old text (this defaults to 0
if not given).
@LabeledRevisedSubSubClause{Version=[],
[InitialVersion=[],]New=[],Old=[]} -
Start a labeled subsubclause. The title will be "new_text". If we are
generating an old version of the document, the title is "old_text" instead.
(Note that clause references in commands always use the new_text name.)
The formatter assigns subsubclause numbers. Version is the
version number of the change (see @ChgRef for details); InitialVersion
is the original insertion version of the Old text (this defaults to 0
if not given).
@LabeledAddedSection{Version=[],Name=[]} - Start a labeled
section (chapter). The title will be "new_text". If we are generating an old
version of the document, this clause does not exist. (Any clause references
ought to be in new text.) The formatter assigns clause numbers. Version
is the version number of the change (see @ChgRef for details).
@LabeledAddedClause{Version=[],Name=[]} - Start a labeled
clause. The title will be "new_text". If we are generating an old
version of the document, this clause does not exist. (Any clause references
ought to be in new text.) The formatter assigns clause numbers. Version
is the version number of the change (see @ChgRef for details).
@LabeledAddedSubClause{Version=[],Name=[]} - Start a labeled
subclause. The title will be "new_text". If we are generating an old
version of the document, this subclause does not exist. (Any subclause
references ought to be in new text.) The formatter assigns subclause
numbers. Version is the version number of the change (see @ChgRef for
details).
@LabeledAddedSubSubClause{Version=[],Name=[]} - Start a labeled
subsubclause. The title will be "new_text". If we are generating an old
version of the document, this subsubclause does not exist. (Any subsubclause
references ought to be in new text.) The formatter assigns subsubclause
numbers. Version is the version number of the change (see @ChgRef for
details).
@LabeledAddedAnnex{Version=[],Name=[]]} -
Start a labeled (unqualified) annex. The title will be "new_text". If we
are generating an old version of the document, this annex does not appear.
(Any annex references in commands ought to be "new text".) The
formatter assigns annex letters. Version is the
version number of the change (see @ChgRef for details).
@LabeledAddedNormativeAnnex{Version=[],Name=[]]} -
Start a labeled normative annex. The title will be "new_text". If we
are generating an old version of the document, this annex does not appear.
(Any annex references in commands ought to be "new text".) The
formatter assigns annex letters. Version is the
version number of the change (see @ChgRef for details).
@LabeledAddedInformativeAnnex{Version=[],Name=[]} -
Start a labeled informative annex. The title will be "new_text". If we
are generating an old version of the document, this annex does not appear.
(Any annex references in commands ought to be "new text".) The
formatter assigns annex letters. Version is the
version number of the change (see @ChgRef for details).
@LabeledDeletedClause{Version=[],Name=[]} - Start a labeled
clause. The title will be "old_text". If we are generating a new
version of the document, this clause does not exist. (Any clause references
ought to be in old deleted text.) The formatter assigns clause numbers. Version
is the version number of the change (see @ChgRef for details).
[Note: We do not support deleting sections or annexes.]
@LabeledDeletedSubClause{Version=[],Name=[]} - Start a labeled
subclause. The title will be "old_text". If we are generating a new
version of the document, this subclause does not exist. (Any subclause
references ought to be in old deleted text.) The formatter assigns subclause
numbers. Version is the version number of the change (see @ChgRef for
details).
@LabeledDeletedSubSubClause{Version=[],Name=[]} - Start a labeled
subsubclause. The title will be "old_text". If we are generating a new
version of the document, this subsubclause does not exist. (Any subsubclause
references ought to be in old deleted text.) The formatter assigns subsubclause
numbers. Version is the version number of the change (see @ChgRef for
details).
@UnnumberedSection{} - Start an unnumbered section. (These are the
Forward and Introduction). This *can* be referenced by a reference,
and will appear in the table of contents.
@Subheading{} - Start an unnumbered subclause (a subclause of an
unnumbered section). These are formatting only, they cannot be
referenced, nor do they appear in the table of contents.
@Heading{} - Start an unnumbered clause (a clause of an unnumbered
section). These are formatting only, they cannot be referenced, nor do
they appear in the table of contents.
@Center{} - Center the otherwise normal text. Note that this is a
paragraph style and is treated like a header.
@Right{} - Right justify the otherwise normal text. Note that this is a
paragraph style and is treated like a header.
@PrefaceClause{} - Start a new clause without numbering or title - just a
page break to an odd page.
@RefSec{} - Generates a reference to the clause "title". (This must
match exactly except for case). The reference is of the form
", ``''". (The ARG has directed that this be
changed to ', ""').
@RefSecNum{} - Generates a reference to the clause "title". (This must
match exactly except for case). The reference is of the form
"".
@RefSecbyNum{} - Generates a reference to the clause with as a
clause number. This is intended to be used internally to the tool,
not in document source (the tool assigns the clause numbers).
@LocalTarget{Target=[],Text=[]} - Generates a target for
future @LocalLink commands at the current location.
should be short, using alphanumeric characters. will be
generated normally, using the current formatting (no formatting
is allowed in ).
@LocalLink{Target=[],Sec=[],Text=[]} - Generates a
link to the target specifed in the section given by "title" (this
should have been defined by a @LocalTarget command). will be
generated as the body of the link, using the current formatting (no
formatting in ).
@URLLink{URL=[],Text=[]} - Generates a link to the URL specified;
will be the body of the link, using the current formatting (no
formatting in ). The URL should be a complete URL, including
"http://".
@AILink{AI=[],Text=[]} - Generates a link to the AI specified;
will be the body of the link, using the current formatting (no
formatting in ). The AI should be an AI number in the full
format (AI95-0yyyy-zz, AI05-yyyy-z, or SI99-yyyy-z).
-- Ada specific commands:
@nt{} - A non-terminal in normal text. This will be set in a Swiss
(sans-serif) font. Also, for HTML, this will linked to the
definition text; use @ntf instead if this is not a real
non-terminal.
@ntf{} - Format as a non-terminal in normal text. This will be set
in a Swiss (sans-serif) font.
@key{} - A keyword in normal text. This will be set in boldface.
@exam{} - Example text occurring in normal text. This will be set
in the example font (which is selected in the master file).
@examcom{} - The body of an example comment; this is shown in the
roman font in italics. (This is the same as the @RI command, but
by using a separate name, we can change the format in the future.)
@redundant{} - Marks text thought to be unnecessary in the RM. That is,
the rules are explained elsewhere. The text is formatted normally.
When annotations are shown, this text is surrounded in brackets.
When annotations are not shown, no special formatting is used.
@syn{[Tabs=, ]LHS=, RHS=}
- Marks a syntax production.
contains @syn2 (and @synf) commands for RHS non-terminals.
defines any tabs needed by the .
The is indexed. The and
(and the clause number) are sent to the syntax manager. Also, saves
for any following @Syn2 to use. The command also writes
@nt ::=
to the output.
Note: and allow @Chg commands.
@syni{} - Generates in the italics of a non-terminal prefix.
@syn2{} - Marks a non-terminal name in the production of a syntax rule.
If the current non-terminal is not null, generates a cross reference
entry: in at . Also, generate an index
entry for the item: @Defn2(Term=,Sec=@i{used}). (For the purposes
of the index, all of Annex P is a single paragraph). Otherwise, is the
same as @nt.
@synf{} - Marks a non-terminal name in the production of a syntax rule,
for which there is no formal definition in the document. (Character
set names in Ada fall into this category).
If the current non-terminal is not null, generates a cross reference
entry: in at . Also, generate an index
entry for the item: @Defn2(Term=,Sec=@i{used}). (For the purposes
of the index, all of Annex P is a single paragraph). Otherwise, is the
same as @ntf.
@syntaxsummary -- Generate the syntax summary at this point. *No paragraph
numbers*!
@syntaxxref -- Generate the syntax cross-reference at this point. *No paragraph
numbers*!
@AddedSyn{Version=[],[Tabs=, ]LHS=, RHS=}
Add a syntax production for Version. Otherwise, the meaning is the
same as for @Syn, above. Note: and need
@Chg commands; this command only adds processing for "::=" and overall
inclusion or skipping when necessary.
@DeletedSyn{Version=[],[Tabs=, ]LHS=, RHS=}
Delete a syntax production for version. Otherwise, the meaning is the
same as for @Syn, above. Note: and need
@Chg commands; this command only adds processing for "::=" and overall
inclusion or skipping when necessary.
@Attribute{Prefix=,AttrName=,Text=}
Defines an attribute. Creates a hanging text item ',
with the specified text. The text can contain arbitrary commands;
it will be run through the full evaluation code.
The attribute and text is also sent to a database used to later create
Annex K. (This uses the current value of PrefixType.) Finally, the
attribute is indexed as by calling @Defn2{Term=[Attribute],
Sec=}, and as by calling @Defn{ attribute}. See also
ChgAttribute.
@AttributeLeading{Prefix=,AttrName=,Text=}
Same as attribute, except that the first paragraph is a "Leading"
paragraph. (Use when the second paragraph is a DescExample, such
as when a function specification is given.)
@AttributeList
Dumps the summary list of all attributes from the attribute database
to the output file.
@PrefixType{text}
Save the indicated text to use as part of any following attribute
definitions. The text is also written to the output. The text should
fit in the phrase: "For {text}:". For instance, the text could be
"every scalar subtype S". See also ChgPrefixType.
@EndPrefixType{}
(The parameter list must exist and be empty) Set the saved attribute
text to "@b{NONE!}". This exists to ensure that the prefixes are set
properly, and aren't just set by accident.
@PragmaSyn{}
Defines a pragma. The text is displayed in the current format.
The text should contain an @prag command (which specifies and indexes
the name - see below.) The text can contain arbitrary commands;
it will be run through the full evaluation code.
The text is also sent to a database used to later create Annex L.
@AddedPragmaSyn{Version=[],}
Defines a pragma added by . Otherwise, the text is as
described for PragmaSyntax. Text includes an appropriate @Chg;
the purpose of the Version number here is
to determine whether (and how) this is entered into Annex L,
along with the cross-reference text.
@DeletedPragmaSyn{Version=[],InitialVersion=[],}
Defines a pragma deleted by , originally added by
. Otherwise, the text is as
described for PragmaSyntax. Text includes an appropriate @Chg;
the purpose of the Version number here is to determine whether
(and how) this is entered into Annex L, along with the cross-reference
text.
@PragmaList
Dumps the summary list of all pragmas from the pragma database
to the output file.
-- Indexing:
If Show-Index-Entries is not used on the command line, indexing entries
are transparent (this is usually the case for the RM).
If Show-Index-Entries is used on the command line, indexing entries show as
italized in curly brackets. RootDefn adds "[distributed]", PDefn adds
"[partial]", IndexSee adds ": see ", and IndexSeeAlso adds
": see also " to the reference.
@IndexList - Generates the index at this point.
@defn{} - Defines a term, where the entire definition is given in the
referenced paragraph.
@rootdefn{} - Defines a term, where the definition is given in several
paragraphs. This is the primary definition.
@pdefn{} - Defines a term, where the definition is given in several
paragraphs. This is one of the secondary definitions.
@defn2{Term=[],Sec=()} - Same as Defn, except a subterm is
allowed. The subterm will be indexed under the primary term.
@rootdefn2{Term=[],Sec=()} - Same as RootDefn, except a
subterm is allowed.
@pdefn2{Term=[],Sec=()} - Same as PDefn, except a subterm is
allowed.
@seeother{Primary=[],Other=()} - Generates a See
reference to in the index. No page/clause reference is
generated.
@seealso{Primary=[],Other=()} - Generates a See also
reference to in the index. No page/clause reference is
generated.
@indexsee{Term=[],See=()} - Generates a See
reference to in the index. A page/clause reference is
generated.
@indexseealso{Term=[],See=()} - Generates a See also
reference to in the index. A page/clause reference is
generated.
@ChildUnit{Parent=[],Child=[]}
Generates three index entries: An index entry for , with a secondary
of "@i{child of} ", an index entry for "Language-Defined
Library Units" with a secondary entry of ., and an index
entry for .. The Unit is set to ..
(For version 2 or later, the Language-Defined entry is not generated.)
The first entry is added to the package list as well.
@SubChildUnit{Parent=[],Child=[]}
Same as @ChildUnit, except that the first entry is added to the
subprogram list, rather than the package list.
@RootLibUnit{