[Groff] generating macro files

[Erich Hoffmann]

Hello all.

I'm rather hesitating to present my project here which perhaps does
not make sense to anyone but myself.

   It is a tmac file that formats and outputs tmac files, called
"ac.tmac".  The tarball is in bz2 format 15KB size (tarball with
ac.tmac alone 9,5KB), containing the tmac file itself, a sample source
code "ash.mm" that can be formatted into "ash.tmac" with mac, and then
a sample file that can be processed with that ash.tmac.  This is the
procedure ac.tmac is meant to be used.  A manpage is included.

   Having no homepage I could mail that to the list if there is interest.
Problem is that I don't know nothing about licenses etcetera, so I
copied a license out of another tmac file into mine - hope that this
is more or less correct, at any rate I'd be grateful for a comment
on that.

Follows a description extracted from ac.tmac which explains it.

erich


~~~~~~~~~~~~~~~~~Quoted from ac.tmac~~~~~~~~~~~~~

Writing comments in source code is a problem. Formatting of paragraphs
for better readability can be done  with  a  good  editor  and  Thomas
Jensens  "boxes"  program  (http://home.pages.de/~jensen/boxes/).  But
when it comes to document  structure  like  numbered  headings  or  an
index,  another  world begins. You have to insert everything manually.
This is why PERL has  its  own  macro  set  called  "pod"  (plain  old
documentation) which has been compared to old nroff.
     Why  not use modern groff for this purpose? Why not have numbered
headings, table of contents, index, cross references and variables  as
comment  structure in a source code? -- This is what mac does for tmac
files. The idea is very simple. I write my tmac  code  as  usual.  But
then, with the help of mac macros, instead of classical comment markup
I insert groff mm macros, process the  file  and  have  a  structured,
numbered,  cross referenced tmac file text with everything that mm can
offer.
     To get an idea what that means have a  look  at  this  tmac  file
which  is  an  example  of  its  own method. It is an extension to the
groff_mm(7) set and uses its macros for the  formatting  of  the  tmac
file. The structure of a primitive mac file may look like this:

     ._TMAC:
     ,_R:
     (comment region with groff mm markup)
     ._r:
     (verbatim region with groff tmac code)
     ,_R:
     (comment region with groff mm markup)
     ._r:
     (verbatim region with groff tmac code)
     ...etc...
     ,_APX:
     ,_EOF:

The  first  and the last macro (._TMAC: and ,_EOF:) are needed by mac.
Between ,_R: and ._r: are the comment parts,  formatted  by  groff  mm
(headings,  paragraphs,  lists,  index  entries and cross references).
After ._r: and before ,_R: the groff tmac code is  inserted,  this  is
"verbatim  mode".  "Verbatim  mode"  means that escaping is turned off
with the {.eo} request and that the control characters are  redefined:
{.cc} is {,} (comma) instead of {.} (dot) and {.c2} is {;} (semicolon)
instead of {'} (quote). Thus, any macro call within verbatim mode  has
do be done with comma instead of dot, hence "{,_R:}", but "{._r:}". --
{,_APX:} inserts Index and Table of Contents (i.e. a file structure, a
list of the headings) formatted by mm. Output is:

     .ig
     (formatted output, headings, paragraphs...)
     ..
     (unformatted output as-is, groff code)
     .ig
     (formatted output, headings, paragraphs...)
     ..
     (unformatted output as-is, groff code)
     ...
     .\"
     .\"  Index
     .\"
     .\"  item (section)
     .\"  item (section)
     .\"  item (section)
     .\"
     .\"
     .\"  Table Of Contents
     .\"
     .\"  (number) heading
     .\"  (number) heading
     .\"  (number) heading
     .\"      "     "     "     "
     .\" Total of macros : (number)
     .\" END OF FILE

In  verbatim mode you define macros as usual with {.de}-{..}. However,
mac offers two other possibilities: First, the ,_D: macro. With

     ,_D: MACRONAME
     (code)
     ..

a macro is defined. At the same  time  an  index  entry  MACRONAME  is
created and the macro is counted. Output is:

     .de MACRONAME
     (macro definition)
     ..

With

     ,_M: MACRONAME
     (code)
     ,_m:

a  macro  is defined, counted an indexed, but the output is surrounded
by comments, and if you omit the lowercase ,_m:, mac complains. Output
is:

     .\"
     .\"     "    "    "    "    "    "    "    "    "     \
     .\"                                  START {MACRONAME} (nr.)
     .de MACRONAME
     (code)
     ..
     .\"                                  end   {MACRONAME} (nr.)
     .\"     "    "    "    "    "    "    "    "    "    /
     .\"


These  macros  were  helpful when I reformatted m.tmac into a mac tmac
file which was a question of minutes. First, I inserted ._TMAC: on top
and  ,_APX:  with  ,_EOF:  at  the  end of the file. Next step was the
insertion of a heading after ._TMAC: with mac {,_H: 1 "heading text"},
because  the index function complains when there is no heading active.
Then I replaced the {.de} - {..} pairs with ,_M: - ,_m:  by  a  simple
sed operation:

     sed -e 's/.de/,_M:/' -e 's/^../,_m:/'

When I processed that file with

     mmroff -s -P-c -P-b -P-u -mac -Tascii

mac  told  me  that  the  TL definition  (line 2947 of m.tmac) was not
ended by {..}, but continued with {cov*title AU} - {..}  (Same  effect
with  .de AS, line 2995). When I now inserted {,_D: TL} and {,_D: AS},
everything went well and I re-generated m.tmac with the difference  of
a  macro  definition markup like in this ac.tmac and a list of all 214
macros.
     Another effect is the escaping function in verbatim mode which is
turned  off  by  default. Escaping is turned off with the .eo request.
With {,_EC_CHAR:} you can turn it  on;  and  that  means  the  use  of
variables.
     (Default  escape  character  is ^. If this character clashes with
your tmac file, choose another one by  navigating  to  the  line  {.ds
EC_CHAR}  in  sect.  3.1 below. It is the first .ds-definition in this
file. To turn escaping in verbatim off  again,  use  the  {,_EO_MODE:}
macro.)
     Now  escaping  is  possible again with ^ (see sect. 2.2). In fact
this possibility was one of the reason why I thought I needed  a  tool
like  mac. I am experimenting with a macro file for typesetting chess.
Now for en passant captures mac has to recognize the input  "P"  as  a
"PAWN".  But in the german bias a pawn is a "B" (Bauer), which in turn
is a "Bishop" in english. But if I define:

     {.ds PAWN P}
     (or ,ds PAWN P in verbatim mode)

- I can use ^*[PAWN] as a variable for  the  input  P.  To  switch  to
german  I  redefine  ^*[PAWN]  to  B  (consequently  ^*[BISHOP]  to  L
("Laeufer") etc.), reprocess the code, and that was  it.  Thus  it  is
possible,  with  only  12  redefinitions  (6  white  6  black), and no
additional package, to have my chess tmac file in any language.

     Mac is relatively small: The pure code with no  comments  is  321
lines  long. Apart from mm markup, the normal user has to learn only a
handful of macros. Minimal use requires 4 (._TMAC:, ,_EOF:,  ,_R:  and
._r:); normal use roughly a dozen. Here is a list:
(...)

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~