UGRIND 1

NAME

ugrind − troff preprocessor which highlight source code

SYNOPSIS

@BINDIR@/ugrind [−d file] [−h header] [−l language] [−t size] name ...

DESCRIPTION

Ugrind insert string definition in files to highlight the source code they contain. Ugrind runs in two basic modes: regular mode or whole file mode.

• In regular mode, ugrind only highlight code which is between the vS and vE macros. The language is specified by the first argument of the vs macro.
• In whole file mode, ugrind highlight the whole file. The language is specified by the −l argument.

The options are:

• −d: Specifies an alternate language definitions file (default is @LIBDIR@/ugrindefs).
• −h: Specify a header string. The header will be printed as argument of the .vH macro.
• −l: Enter whole file mode, and pecifies the language to use.
• −t: Specify a nondefault tab size (default is 4).

Currently, known languages are C (−lc), C++ (−lc++), CSH (−lcsh), FORTRAN (−lfortran), ICON (−lI,) ISP (−lisp), LDL (−ldl), LISP LIKE (−ml), MODEL (−lm), MODULA2 (−lmod2), PASCAL (−lp), POSTXML (−lpostxml), RATFOR (−lr), RUSSEL (lrussell), SHELL (−lsh), TROFF (−ltr), XML (−lxml), and YACC (−lyacc),

PROGRAMMING STYLE

Ugrind assumes that a certain programming style is followed:

• C and C++: Functions names can be preceded on a line only by spaces, tabs, or an asterisk. The parenthesized arguments must also be on the same line.
• PASCAL: Function names need to appear on the same line as the keywords fuctions or procedure.
• MODEL: Function names need to appear on the same line as the keywords is beginproc.
• TROFF: Between .vS and .vE macros in regular mode, and in the whole file in whole file mode, ugrind will take care to escape all the commands, macros, strings and number register that could be interpreted by troff. That means that to highlight troff source code, one juste has to write the code as is. That also means that it is not possible to insert formatting commands inside the code that has to be highlighted.

More generally, arbitrary formatting styles for programs mostly look bad. The use of spaces to align source code fails miserably; if you plan to ugrind your program you should use tabs. This is somewhat inevitable since the font used by ugrind is variable width.

MACROS AND STRINGS

To highlight code, ugrind insert strings in the file, and use some macros, so, to format the output of ugrind with troff, the following strings and macros must be defined by your macro file.

Macros

• vS: In regular mode, start a code block to highlight. The first argument define the language. See the −l option to get the list of supported languages.
• vE: In regular mode, end a code block to highlight.
• vF: In whole file mode, start a new file. The first argument is the name of the file.
• vH: The header defined by the −h option is defined as argument of this macro.
• vO: Indicate that a function begins on the next line. The first argument is the function name.
• vC: Indicate that a function gets closed on the previous line.

Strings

• +C: Begin a comment,
• -C: End a comment,
• +K: Begin a keyword,
• -K: End a keyword,
• +S: Begin a string,
• -S: End a string,
• +V: Begin a variable,
• -V: End a variable,
• e: a slash (\),
• -: a tiret (−),
• _: a bottom tiret (_).

HISTORY

Ugrind is a hack of vfontedpr (that probably means visual-font-edit-print), which is the preprocesor used by the mostly forgotten vgrind script, which aims to visually "grind nice listing of programms" with troff. The code that vfontedpr use to read the language description file is "stolen almost totally from termcap". Vgrind and vfontedpr have been written by Dave Presotto and William Joy, for 4.3BSD-Tahoe. They have been modified by Gunnar Ritter as part of the Heirloom documentation tools.

LICENSE

Ugrind and its man page are distributed under the bsd4 license. The code which highlight troff language, written from scratch, is distributed under a bsd2 license. The language description file (@LIBDIR@/ugrindefs) is distributed under the cddl license.

FILES

@BINDIR@/ugrind preprocessor @LIBDIR@/ugrindefs language descriptions

SEE ALSO

troff(1)

AUTHORS

Written by Dave Presotto and William Joy. Modified by Gunnar Ritter for the Heirloom Project and later Pierre-Jean Fichet for Utroff.