Re: Summary of man-page formatting

[tlaronde%polynum.com@localhost]

On Sun, Nov 15, 2020 at 12:43:58PM -0500, Mouse wrote:
> >>  - switch to something else (anything else?)
> > As a general purpose doc tool [TeX] is fine,
> 
> Only for typeset doc.  For read-as-text doc - which, at least
> personally, is far more important - it is, well, see below.  (For
> almost all purposes, if I'm faced with typeset documentation,
> regardless of PS vs PDF vs whatever format, my first step is to convert
> it to plain text, manually if necessary.)
> 
> > and it doesn't take much arguing to convince people that it produces
> > better results than anything *roff can ever do, but it doesn't format
> > existing *roff docs.
> 
> I suspect it could be made to.
> 
> TeX is general-purpose enough that it wouldn't be very hard to make it
> generate text docs, basically a DVI backend that is to TeX what nroff
> is to troff.  And, while I'm not aware of any, it is general-purpose
> enough that a macro package could probably be written to handle at
> least mandoc.  Making it handle the full generality of nroff would,
> even if possible, probably be far more work than it's worth.
> (Actually, TeX is general-purpose enough that it is probably possible,
> maybe excepting running into various limits.)

I plan to tackle the task (the problem is: when? But it took me 10 years
of sighing after the state of TeX before finally building kerTeX...).

But if I do, I will provide the mean to convert the existing man
pages and doc to TeX (perhaps even on the fly) assuming that the
macros are "frozen" and this part will not be updated. It will not
be a general purpose translation but a translation of what is needed
by the OS documentation. So that it is at least a "rule"---there
may be a couple of exceptions; but the huge majority will be
automatically translated without ado.

> 
> Assuming a TeX mandoc macro package were to somehow magically exist,
> would TeX be a suitable replacement?  Maybe.  It is unlikely to be as
> fast as a specialized tool, so, for manpages, I see no benefit to it
> over mandoc.  Over groff, I would call TeX a win on arcanity and
> licensing grounds.  (Not that TeX language is trivial.  But my (only
> partially informed) opinion is that it's less arcane than *roff.)

TeX is really fast, without making any optimization---the optimizations
are in the D.E. Knuth's carefully chosen data structures. KerTeX
for example runs 2 or 4 times faster than the equivalent programs
in TeXlive (a user even sent me higher numbers; I base my numbers
on a comparison made on JSLinux).

> 
> But, of course, that's predicated on someone going to the trouble to
> (a) build a DVI-to-text backend (not hard, if it doesn't yet exist,
> certainly no harder than pdftotext -layout) and (b) build a macro
> package to teach it to handle mandoc language (difficulty unsure; my
> TeX memories are too rusty for me to more than guess, but my guess is
> about a week, for me, after convincing TeX to run on my machines and
> relearning it - not that I have even a week to dedicate to that).

The someone has a name: me. But the problem is to find the time. It will
be eventually done because I want it even if I'm the only user.

There is so much that could be done in this area that I'm puzzled
nothing has ever been done by students during GSOC. If it's a problem of
license: it is solved. If it is the problem of the needle and the hay:
it is solved (simply: I burnt the hay).
-- 
        Thierry Laronde <tlaronde +AT+ polynum +dot+ com>
                     http://www.kergis.com/
                    http://kertex.kergis.com/
                       http://www.sbfa.fr/
Key fingerprint = 0FF7 E906 FBAF FE95 FD89  250D 52B1 AE95 6006 F40C