Re: [Groff] poll: which macro packages are in common use / and why.

[Keith Marshall]

On Thursday 23 September 2004 9:45 am, Klaus Robert Suetterlin wrote:
> the short story is:  I want to poll who is using which macro
> package, why, and for what.  For example all You ms-hackers out
> there how do You do cross references?  Anyone doing articles or
> reports regularly -- which macro package?

I use ms almost exclusively, for much the same reason's as Ted -- i.e. its 
the first package I learnt, it generally fits my requirements, and I don't 
have the will to overcome the inertia of continuing to use it, rather than 
experiment with something else.

I write process control system software for a UK based oil refinery, and my 
primary use of groff is to create 'Operator Guides', as reference documents 
for the process operators.  These are normally produced in PDF format, using 
ghostscript to convert the grops output.

For me, the DIY nature of ms, and particularly the ease with which it can be 
customised and extended, is one of its strengths.  Indeed, I am currently 
developing a set of PDF 'feature support' macros, with bindings for ms, and 
with particular emphasis on supporting 'active' cross references -- i.e. 
references which behave much like href links and anchors in html.  I handle 
these much along the line suggested by Ted and Robert G., i.e. by using 
macros to place the reference marks. These ultimately use the .tm request to 
write reference info to stdout, which I capture in an auxiliary file, and 
source in a second groff pass, to resolve the references at the link 
hot-spots.

As Ted has noted, it is possible for the resolution of references in pass two 
to cause small rearrangements in the document layout, which can result in 
page numbers being off by one.  In my experience, this can be avoided by 
running *three* passes, rather than two -- the first pass generates the 
initial reference 'map'; the second pass uses this map to resolve the 
references, *and* generates an updated map; the third pass uses this updated 
map to resolve the references, and produce the formatted document, e.g.

  groff -Tps -ms -Z 2>&1 1>/dev/null mydoc.ms | filter > init.ref
  groff -Tps -ms -Z 2>&1 1>/dev/null init.ref mdoc.ms | filter > mydoc.ref
  groff -Tps -ms mydoc.ref mydoc.ms > mydoc.ps

(Note that I generally use a sed or awk filter to separate the reference info 
from any other junk which may appear on stderr, and massage it into an 
appropriate sequence of .ds or .nr requests, for use in the subsequent groff 
passes.  I also like to use makefiles or shell scripts, to automate the 
multiple pass groff processing sequence).

One problem I have noted with this strategy -- and it's exacerbated by the 
requirement to store a significant volume of mapping co-ordinates for the 
bounding boxes of PDF link hot-spots -- is that it is possible to overflow 
the available string space, causing groff to abort with an 'input stack 
overflow error'.  I have noticed this quite recently, in a 12 page document, 
which does make rather heavy use of cross references.  I am currently 
exploring strategies for working around this problem.

Best regards,
Keith.