troff2page is a Lua script that makes Web pages from troff manuscripts. It reads an input document that is marked up in troff (-man or -ms) and produces an output document with the functionally equivalent HTML markup.
troff is a venerable typesetting program that produces high-quality print output from plain text source. It doesn’t require special-purpose software to create content; any text editor will do. troff macros and standard Unix external tools can be used to arbitrarily enhance troff’s print output. troff is very compact (unlike its great rival TeX) and is practically ubiquitous, being available by default on all Unixish machines. These are significant benefits: so even though troff is a toolchain of some vintage, there continues to be a devoted band of troffglodytes preserving the tradition. Troff2page lets you put your troff documents on the Web without your having to learn a new system or to maintain separate documents. Troff2page can be instructed to also produce an Info version of your document that’s suitable for browsing on a text terminal (chapter 11).
First, ensure that the script troff2page is in a directory in your PATH.
To convert an input troff document named jobname.ms, type the following on the operating-system command line.
at your operating-system prompt. This creates an output HTML file jobname.html in the current directory. (This HTML file has the same basename as the input troff file (i.e., jobname), but its extension is .html.)
If the input troff uses the page-break request .bp, then the output HTML consists of a series of interlinked files: The first file is named jobname.html; the rest are jobname-Z-H-1.html, jobname-Z-H-2.html, etc.
troff2page takes some, but not all, of the same options as groff, a widely used and actively developed implementation of troff. viz.,
| -v or --version | display version |
| -h or --help | display help |
| -m | load macro files from GROFF_TMAC_PATH |
| -r | pre-set number registers |
| -d | pre-define strings |
| -c | turn off color |
| -- | signal end of options |
In the unlikely event that you have a document file named --help (and wish to process it), use
troff2page ignores all other groff options, most with a warning. The options -z, -t, and -U are silently ignored, as they’re always valid for Troff2page.
Macro file options must be given without the suffix .tmac or prefix tmac.. Thus, -mxyz or -m xyz looks for the macro file xyz.tmac or tmac.xyz, whichever is found first in the macro directories, and loads it.
If you find you need to specify an option that troff2page doesn’t accept, you can always supply it in a macro file via -m.
The options can be varied with each call to troff2page, just as with groff. Please see the groff man page for details on all the provided options.
The arguments remaining after all the option processing are considered to be the names of document files.
If there is one file argument, say filename.ext, troff2page converts it to filename.html (and possibly some auxiliary HTML files whose names are of form filename-Z-H-number.html). This is unlike groff, which writes to console (“standard output”).
If there is more than one file argument, say f1.e1, f2.e2, ... flast.elast, troff2page concatenates their content to create a corresponding HTML version in flast.html (and possibly some aux HTML files flast-Z-H-number.html). Again, this is unlike groff.
If any of the argument files don’t exist, troff2page, like groff, issues a “cannot open ... No such file or directory” diagnostic, but does its best with the files that do exist.
If after all the option processing, no file arguments remain, and the options for help or version were not used, troff2page reads from the console (“standard input”), like groff. The output HTML file(s) in this case use the basename troffput.1 This part is unlike groff, which always writes to console.
troff2page can read directives in some autoloaded files without the need to explicitly use a command-line option. These are useful to specify information that is relevant only for the HTML output, and they’re loaded before the input document is processed.
i. The first such file is named .troff2pagerc: Troff2page looks for it in your macro directories: GROFF_TMAC_PATH, working directory, home — in that order.2 The working directory is a good location if your changes are meant only for those documents that are in that directory. If your changes will be used in all your documents, place it in your home or a private (not a system!) GROFF_TMAC_PATH directory.
That your home directory is the last place Troff2page looks in for .troff2pagerc has a nice benefit: Use ~/.troff2pagerc for standard boilerplate customization that you want unthinkingly autoloaded for most of your documents, but easily disable it for the documents that need special TLC by simply placing an empty or different .troff2pagerc in the working directory.
A more system-level GROFF_TMAC_PATH placement is typically unadvised for such an ad hoc file.
troff2page loads only the first .troff2pagerc it finds.
ii. Next, troff2page will also pick up a file jobname.t2p, where jobname is the basename of the input document. This is useful for directives that are specific to this document. jobname.t2p, unlike .troff2pagerc, is looked for only in the working directory, and not more generally in GROFF_TMAC_PATH.
(Note that groff itself will not load either .troff2pagerc or jobname.t2p automatically. But that is presumably OK, since these two files typically contain information that’s relevant for HTML only.)
iii. Finally, If the input file is recognizably a man page (i.e., it has the command .TH), both Troff2page and groff will load, if it exists, the init file man.local. This init file, like .troff2pagerc, is searched for in the GROFF_TMAC_PATH, working directory, and home, in that order.
None of the autoloaded file disables the loading of the others. However, because of the order in which they’re loaded, settings in man.local can override or shadow jobname.t2p, which in its turn shadows .troff2pagerc.
The script troff2page runs on the command-line on Unix-esque machines that have Lua installed. For more installation information, please see the file INSTALL.adoc in the distribution.
However, it is not necessary to run the file troff2page as a Unix script. You can load troff2page.lua (troff2page is a soft link to the Lua file troff2page.lua) into Lua, and then call the Lua procedure troff2page on your source document. E.g.,
The procedure troff2page can be called several times, on the same or different documents, from within the same Lua session. It takes the same options as the script, supplied as multiple string arguments.