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:
(...)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
_______________________________________________
Groff mailing list
address@hidden
http://lists.gnu.org/mailman/listinfo/groff