troffcvt Front End Writing

Paul DuBois
dubois@primate.wisc.edu

Wisconsin Regional Primate Research Center
Revision date: 11 April 1997

troffcvt converts troff input into an intermediary easily-parsed token stream. troffcvt postprocessors turn that token stream into some other target format. For example, tc2rtf turns the token stream into Rich Text Format (RTF), whereas tc2text turns it into slightly-formatted plain text.

A front end is typically a shell or Perl script that glues troffcvt and some postprocessor together via a pipe. It provides a convenience for users, who then need neither know nor care about the existence of troffcvt itself or the postprocessor; they only know that their troff input turns into some other format by invoking the front end.

When you write a troffcvt front end, the main thing you need to be concerned about is argument processing. troffcvt understands a certain set of flags, and the postprocessor very likely understands certain flags as well. The front end can determine its own syntax to some extent, but some of troffcvt's options should be recognized and passed straight through. For instance, in order to preserve the correspondence between troff and troffcvt, the front end should pass through any -mxxx flags.

Suppose you normally use something like this to format a document myfile.ms:

   % troff -ms myfile.ms
With troffcvt, you might use a command like this:
   % troffcvt -ms -a tc.ms myfile.ms | postprocessor

If additional files are used for the postprocessor, the front end can typically deduce what they are on the basis of any -mxx argument. In most cases, if -mxx is specified, the front end should also pass -a tc.mxx to provides any general -mxx-specific redefinitions. The front end may also pass a file that provides redefinitions that are appropriate for a specific postprocessor. For example, if -ms is specified, troff2html will pass not only tc.ms, but tc.ms-html as well. There may be other arguments that the front end supplies. For example, tc2html has its own action file (actions-html), that's used in addition to the standard action file (actions) that troffcvt reads when it starts up:
   % troffcvt -a actions-html -ms -a tc.ms -a tc.ms-html myfile.ms | tc2html