RE: [Groff] poll: which macro packages are in common use / and w

[Ted Harding]

On 23-Sep-04 Klaus Robert Suetterlin wrote:
> [...]
> I tried to identify the macro package that would fill my needs.
> These are mainly cross references, customisable headers and footers,
> bibliographic references (which can be done by use of external
> tools) and two column formatting.  Of mm, ms and mom, there seems to
> be only mm that has cross references.  ms seems to be quite far
> on the do it Yourself side of groff macros -- I'm not a typesetter
> or printer or macro-hacker and don't want to invent the wheel of
> page layout again, so I fear ms is not my way to go.
> [...]

I have to agree that ms (which is what I use myself) is on the DIY
side. My reason for sticking with it is that it's what I've used
since starting with Unix troff 20 years ago: I know it, and also
I have customised it a lot (including a large private macro package
which has been built up over the years to work well with ms).
So I don't feel inclined to re-write all that in some other macro
package which I would have to take the time to get equally intimate
with!

Cross-references with ms take a bit of work. It's essentially a
two-pass job. While creating your troff source file, you plant named
tags at the places you will want to refer to; these are done by
a macro which has the name as argument and has the effect, when
formatting, of writing out name and the page or section (or equation
number or whatever you want) to an auxiliary file. At the places where
you want to make the reference you place another macro with the same
name as argument, which inserts a string which includes something like
"\*[XrefName] which has been defined in the auxiliary file; this is
read in on the second pass. While this works, it clearly involves
a bit of work. Also, there is always the possibility that the formatting
changes slightly on the second pass, so that a page number can come out
wrong by 1. Since 'ms' does not include macros for this kind of job,
you have to write your own; however, this does have the advantage
that you can fashion it to your own purposes.

Customisable headers and footers should not be a big problem with ms,
since all the definitions of the standard headers and footers can be
re-written to your taste. For the most part, I find that simply
defining the strings LH, CH, RH and LF, CF, RF is sufficient, but
if something radically different is needed then you have to redefine
pg*OH, pg*EH, pg*OF and pg*EF.

As you say, bibliographic references are best done with external
tools: I have found 'refer' to be too limited and inflexible, and
very difficult to modify.

It's much the same with indexing: There is a tool 'makeindex' which
was designed for TeX but can be used with troff by invoking it with
a "troff" style file. While this is very flexible, it can sometimes
lead to some tricky hand-work for special effects. Again this is a
two-pass job: my script for this includes the lines

  groff -Tascii -p -ms -mted $1 > /dev/null 2>$1.idx
  makeindex -r -s /usr/share/groff/tmac/mkindex.ist $1.idx
  groff -Tps -e -ms -mted $1.ind > $1.ps

where the first line discards the normal groff output and stores
the "stderr" output (which is written by the indexing entries in
"$1" under macro control) into $1.idx. The second line reads this
file and writes a file $1.ind; this is a 'groff' source file which,
when formatted by the third line, produced the index pages exactly
as you want them. The file "mkindex.ist" is the troff style file.
The third line could be suppressed if you chose to include the
file $1.ind into the original source file.

Two-column formatting with 'ms', using the '.2C' macro, is fine up
to a point. That point is where you want to break into two columns
part-way down a page and then drop back into one column on the same
page. The 'ms' macros don't allow for that (since they force a page
break when dropping back to 1 column). All this is governed by the
".MC" macro in 'ms' and I have never worked out a clean way of
over-riding how this works.

Maybe you don't really want to know all this, if you are already
not too enthusiastic about 'ms'! However, I hope it helps.

Best wishes
Ted.


--------------------------------------------------------------------
E-Mail: (Ted Harding) <address@hidden>
Fax-to-email: +44 (0)870 094 0861   [NB: New number!]
Date: 23-Sep-04                                       Time: 11:13:51
------------------------------ XFMail ------------------------------