Linux IP Stacks Commentary Web Edition

Commentary Markup Language Specification

This specification is preliminary. The page will be updated as new information about the markup language becomes available

The markup language described here follows in the footsteps of the UNIX system’s documentation markup languages used in troff, nroff, groff, and so forth. Unlike the troff-derived markup languages, there are no macros, only commands. Keeping it simple.

In the descriptions, the caret (^) says “at the beginning of the line,” and the dollar sign ($) says “at the end of the line.” Lines are delimited by newline (\n) characters.

Commands always start at the beginning of a line, at the beginning of file or after a newline(\n) character. The parsing of the input goes like this:

Pass 1:
- Append a newline at the end of the file.
Pass 2:
- s/\\”.*\n/\n/g – Remove comments
Pass 3:
- s/[\n+]/\n/.p\n/g – Replace two or more consecutive newlines to a paragraph marker command
Pass 4:
- s/\n.([^\n]*)\n/\n/ – Extract commands, saving each command, perform each command
- Copy the remaining text, consolidating tabs, spaces, and newlines into a single space
Generate HTML

Comments

^\"	Full line comment
\"	Ignore to, but not including, end of line; if at the beginning of a line, treat as blank line

Text formatting

When the page-build program is started, the defaults are:

no bold
no italic
no underline
font is Serif (browser default)
size is 12 points

Text modes bold, italic, and underline are “sticky”, that once set they stay set their state, except when using the word-insert form of the mode command. Size and font are also “sticky”.

^.<arguments>$	Adjust current mode for bold, italic, underline
^.$	Reset current mode to not bold, not italic, not underline (roman)
^.<arguments> text$	Insert text in the indicate mode for bold, italic, underline.
^.size <number> $	Set type size in points
^.font <name> $	Set typeface by name: serif, san-serif
^.br$	Insert line break (not new paragraph
^.p$	Start new paragraph
$$	Start new paragraph
^.p <style> $	Start new paragraph with specified style
^.hr	Insert horizontal rule

With an empty <arguments>, indicates that bold, italic, and underline are off.

Arguments are “b” for bold, “i” for italic, ‘u’ for underline.

To set the text Emphasized in the middle of a line, use the command, starting at the beginning of the line:

^.biu Emphasized

Insert the word with the indicated formatting options. Do not set the current formatting options for remaining text.

The text that follows the inserted text will be set in the mode currently in effect before this command.

Hypertext insertion

Hypertext to be inserted into the output stream is delimited by two commands:

^.html$	Start of HTML to be inserted
^./html$	End of HTML to be inserted
^.html <text> $	HTML line to be inserted

The first two commands are used to permit insertion of more complex structures such as tables and formulas, without requiring adding to the syntax of this markup code language or requiring macros. The third command allows for in-line insertion of code, such as text with superscripts and subscripts.

Code insertion

Directory path, filepath, start points and end points are “sticky”. (Need to consider clearing start and end points after an insert command, to make diagnosing missing issues easier.)

^.dir dirpath	Set the current direction to the indicated name
^.file filepath	Set the file path to the indicated name
^.start regexp	Set the start point to the beginning of text matching the regular expression
^.end regexp	Set the end point before the beginning of text matching the regular expression
^.insert	Insert the code between the beginning of the start point, up to and excluding, the end point

The indicated code is inserted with the insert command.

All inserted code uses the style “code”, which is monospace, bold, 12 point. Endlines in the inserted text are converted to <br/>. The entire code block is encapsulated in an HTML paragraph with a program-defined style setting.

No attempt is made to word-wrap code to fit in the window of a mobile device — if the line is longer than the viewport set in the HTML header, then Google will just have to lump it and say the page is not mobile-friendly.

Back to About page