Re: [Groff] Re: Simplifying groff documentation

[Eric S. Raymond]

Larry Kollar <address@hidden>:
> Taking a brief look at the manpages on my computer, .in and .ti
> primarily appear in examples (see unzip.1) or nested lists
> (see tcpdump.1). Looking at tcpdump, I expect that it would
> give doclifter fits as well.

Nope, I handle tcpdump fine.  In at least this case, .in and .ti are
presentation-level only (.in used to tune the appearance of the Synopsis,
.ti used to indent examples that are flagged by .nf/.fi)

unzip.1 is handled by the rule you cite next:
 
> Anyway, .nf/.fi would almost always signal a listing or some
> kind of example, and any .in/.ti appearing in between could be
> safely ignored.

And that's exactly how I do it.  I have quite a lot of machinery
designed to extract information from .nf/.fi.  Basically what happens
is doclifter says "Hmm, this must be some kind of example or display,
now I'll do content analysis to figure out whether something specific
like <screen> or <programlisting> should be emitted.  If not, I'll
fall back on <literallayout>."

At one point .in was in my "complain" set, which meant instances
generated warnings to stderr.  Upon investigating the warnings, I
found that with only two exceptions (emacs.1 and compress.1) out of
13,000, the .in request was never conveying any structural information
at all.  Either it was doing pure presentation or it was effectively
redundant with nearby markup like .nf/.fi or .RS/.RE that I could
uae to deduce structure.

So I put .in in my ignore set and made a TODO note about 
emacs.1 and compress.1

I'm not as sure about .ti, mainly because it's much less commonly used
so I didn't investigate as closely before consigning it to the ignore
set.  But I have yet to find cases other than emacs.1 or compress.1
where it does anything structurally interesting.

> Another construct I found in my quick perusal looks like:
> 
>   .LP
>   .ti +8
>   \fBsome error message\fP
> 
> The amount of indent isn't important, which is fortunate since
> it varies from manpage to manpage. But it looks like .in/.ti can
> help to derive structure if doclifter (as I expect it does) can
> look at more than just one request/macro at a time.

It sure can.  One of my most important cliches related to this is

.RS
.nf
    ...stuff...
.fi
.RE

But it's far from clear what doclifter should do in your case other
than emit a normal <para> tag, which it's going to do because of the
.LP anyway.  (Of course the \fB and \fR turn into <emphasis remap=".B">.)

I have the machinery to do anything you want; I can push an arbitrary open tag,
then set a trap to emit a matching close tag.  The question is what pattern 
checks I can apply to "some error message" that would justify overriding
the normal processing.

I suppose I could change the fallback to emitting <blockquote> around
the line, but it's not clear to me that this would be doing more than
adding noise to the XML output.

I could also have it emit a FIXME warning that hand polishing might be
needed here.  I try to avoid those without a really good reason,
though.  Presently I think there's only one, attached to a truly wacky
edge case in processing of list markup.

I'm open to other suggestions.
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>