XTRAN Example — Translate HP (Digital, Compaq) Runoff to HTML

The following example uses a set of XTRAN rules comprising 628 non-comment lines of XTRAN's rules language ("meta-code") to translate Runoff to HTML.  Runoff is a document markup language that is an ancestor of Unix's Nroff, and is commonly found on HP (Digital, Compaq) computers.

This example shows XTRAN's power as a text manipulator.  The rules read a Runoff source file, translate the Runoff commands and embedded formatting to their HTML equivalents, and write out the resulting HTML file.  The version of XTRAN used was built with only a rules language parser and no code generators, since the only language it must parse is its own rules language, and it produces nothing but text.  The parsing of the Runoff commands and text, and the generation of the HTML tags and text, are done completely in meta-code.

The rules fetch the values of environment variables to determine the document's author and owner.  They implement a substantial subset of Runoff's commands, and are easily extensible to add more.

We actually used XTRAN with these rules, years ago, to translate our XTRAN User's Manual from Runoff to HTML.

The rules support three notable Runoff usage features:


Process Flowchart

Here is a flowchart for this process, in which the elements are color coded:

process flowchart

Input to XTRAN (Runoff):

.CHAPTER Chapter name
.;
This is an ^&underlined\& word in a sentence by itself.
.S
This is another sentence by itself; it has an _# escaped sharp.
.BR
This follows a hard line break; it has an _\ escaped backslash.
.PG
This follows a hard page break; it has {curly} brackets.  It continues as a
long paragraph, requiring automatic wrapping etc.  It continues as a long
paragraph, requiring automatic wrapping etc.  It continues as a long paragraph,
requiring automatic wrapping etc.  It continues as a long paragraph, requiring
automatic wrapping etc.
.S
Following is a table done with .LM and .I:
.S
.LM +16
.I -12
<foo>######Description of foo, which continues to more lines by going on and
on and on and on.
.I -12
<barski>###Description of barski, which continues to more lines by going on
and on and on and on.
.LM -16
.S
.C;Centered text
.S
.HL 1 Heading 1-1
This sentence follows a level 1 heading and has a hyphenation char=acter
between "char" and "acter".  It continues as a long paragraph, requiring
automatic wrapping etc.  It continues as a long paragraph, requiring automatic
wrapping etc.  It is followed by a level 2 heading.
.HL 2 Heading 2-1
.NF
This paragraph is with "fill"
turned off.
.S
So is this paragraph, which
consists of 2 lines.
.S
.F
This paragraph was originally
2 lines, but "fill" is turned on.
.S
Following are bullets done with .LM and .I:
.S
.LM +2
.I -2
o#This is a bullet, which continues to more lines by going on and on and on and
on and on.
.I -2
o#This is another bullet, which continues to more lines by going on and on and
on and on and on.
.LM -2
.S
.NJ
.HL 1 Heading 1-2
This sentence is the start of a long paragraph,
which goes on and on and on and on and on and on and on and on and on and on
and on and on and on and
on and on and on and on.  It has very ragged lines, and it has "justify"
turned off but "fill" turned on.
.S
This sentence has \# an escaped sharp sign, and <left and right angles>.
This sentence has a hard#space between "hard" and "space".
.S
.J
This sentence is the start of a long paragraph,
which goes on and on and on and on and on and on and on and on and on and on
and on and on and on and
on and on and on and on.  It has very ragged lines, and it has "justify"
turned back on; "fill" is still turned on.
.S
This paragraph is followed by a 3-level list:
.LS
.LE Level 1 list element 1
.LE Level 1 list element 2
.LS
.LE Level 2 list element 1
.LE Level 2 list element 2
.LS
.LE Level 3 list element 1
.LE Level 3 list element 2
.ELS
.LE Level 2 list element 3
.ELS
.LE Level 1 list element 3
.ELS
This is the final sentence, which follows the list.


Output from XTRAN (HTML), as rendered by your browser:


Chapter name

This is an underlined word in a sentence by itself.

This is another sentence by itself; it has an # escaped sharp.
This follows a hard line break; it has an \ escaped backslash.

This follows a hard page break; it has {curly} brackets. It continues as a long paragraph, requiring automatic wrapping etc. It continues as a long paragraph, requiring automatic wrapping etc. It continues as a long paragraph, requiring automatic wrapping etc. It continues as a long paragraph, requiring automatic wrapping etc.

Following is a table done with .LM and .I:

<foo> Description of foo, which continues to more lines by going on and on and on and on.
  <barski> Description of barski, which continues to more lines by going on and on and on and on.

Centered text

Heading 1-1

This sentence follows a level 1 heading and has a hyphenation character between "char" and "acter". It continues as a long paragraph, requiring automatic wrapping etc. It continues as a long paragraph, requiring automatic wrapping etc. It is followed by a level 2 heading.

Heading 2-1

This paragraph is with "fill"
turned off.
 
So is this paragraph, which
consists of 2 lines.

This paragraph was originally 2 lines, but "fill" is turned on.

Following are bullets done with .LM and .I:

Heading 1-2

This sentence is the start of a long paragraph, which goes on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on. It has very ragged lines, and it has "justify" turned off but "fill" turned on.

This sentence has \  an escaped sharp sign, and <left and right angles>. This sentence has a hard space between "hard" and "space".

This sentence is the start of a long paragraph, which goes on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on. It has very ragged lines, and it has "justify" turned back on; "fill" is still turned on.

This paragraph is followed by a 3-level list:

This is the final sentence, which follows the list.


Output from XTRAN (HTML source):

<HTML>
<HEAD>
<TITLE>rno2htm</TITLE>
<!-- Author:  S. F. Heffner -->
</HEAD>
<H1>Chapter name</H1>
<P>
This is an <B>underlined</B> word in a sentence by itself.
</P>
<P>
This is another sentence by itself; it has an # escaped sharp.
<BR>
This follows a hard line break; it has an \ escaped backslash.
<BR>
 <BR>
This follows a hard page break; it has {curly} brackets.  It continues as a
long paragraph, requiring automatic wrapping etc.  It continues as a long
paragraph, requiring automatic wrapping etc.  It continues as a long paragraph,
requiring automatic wrapping etc.  It continues as a long paragraph, requiring
automatic wrapping etc.
</P>
<P>
Following is a table done with .LM and .I:
</P>
<TABLE CELLSPACING=0 BORDER=0 CELLPADDING=7 WIDTH=623>
<TD WIDTH="5%" VALIGN="TOP"></TD>
<TD WIDTH="15%" VALIGN="TOP">
&lt;foo&gt;
</TD>
<TD WIDTH="80%" VALIGN="TOP">
Description of foo, which continues to more lines by going on and
on and on and on.
</TD>
</TR>
<TD WIDTH="5%" VALIGN="TOP"></TD>
<TD WIDTH="15%" VALIGN="TOP">
&lt;barski&gt;
</TD>
<TD WIDTH="80%" VALIGN="TOP">
Description of barski, which continues to more lines by going on
and on and on and on.
</TD>
</TR>
</TABLE>
<DIV ALIGN="CENTER">
Centered text
</DIV>
<H2>Heading 1-1</H2>
<P>
This sentence follows a level 1 heading and has a hyphenation character
between "char" and "acter".  It continues as a long paragraph, requiring
automatic wrapping etc.  It continues as a long paragraph, requiring automatic
wrapping etc.  It is followed by a level 2 heading.
</P>
<H3>Heading 2-1</H3>
<PRE>
This paragraph is with "fill"
turned off.
 <BR>
So is this paragraph, which
consists of 2 lines.
 <BR>
</PRE>
This paragraph was originally
2 lines, but "fill" is turned on.
<P>
Following are bullets done with .LM and .I:
</P>
<UL>
<LI>
This is a bullet, which continues to more lines by going on and on and on and
on and on.
</LI>
<LI>
This is another bullet, which continues to more lines by going on and on and
on and on and on.
</LI>
</UL>
<H2>Heading 1-2</H2>
<P>
This sentence is the start of a long paragraph,
which goes on and on and on and on and on and on and on and on and on and on
and on and on and on and
on and on and on and on.  It has very ragged lines, and it has "justify"
turned off but "fill" turned on.
</P>
<P>
This sentence has \  an escaped sharp sign, and &lt;left and right angles&gt;.
This sentence has a hard space between "hard" and "space".
</P>
<P>
This sentence is the start of a long paragraph,
which goes on and on and on and on and on and on and on and on and on and on
and on and on and on and
on and on and on and on.  It has very ragged lines, and it has "justify"
turned back on; "fill" is still turned on.
</P>
<P>
This paragraph is followed by a 3-level list:
</P>
<UL>
<LI>Level 1 list element 1</LI>
<LI>Level 1 list element 2
<UL>
<LI>Level 2 list element 1</LI>
<LI>Level 2 list element 2
<UL>
<LI>Level 3 list element 1</LI>
<LI>Level 3 list element 2</LI>
</UL></LI>
<LI>Level 2 list element 3</LI>
</UL></LI>
<LI>Level 1 list element 3</LI>
</LI>
</UL>
This is the final sentence, which follows the list.
</HTML>