Re: [Groff] Mission statement

[Deri James]

On Fri 14 Mar 2014 23:26:46 Eric S. Raymond wrote:
> > Manpages
> >
> > 
> >
> > - improve the semantic usefulness of manpage markup; groff currently
> >
> >   formats manpages for TTYs and PostScript from largely
> >   presentational markup, however increased use of browsers
> >   necessitates parsing source files for semantic markup in order to
> >   simplify their conversion to presentationally-indifferent xml
> 
> I think we can be a little more specific here:
> 
> - Increased use of browsers shifts the commonest use cases for man 
pages
>   in a direction that rewards structural rather than presentational
> markup.   The future direction for the man macros is to (a) decouple 
them
> as much as possible from low-level troff requests and (b) semantically
> enrich the markup, while (c) maintaining backwards compatibility of the
> macro set.
> 
> I think that lays out a good direction (parallel to where mdoc(7) has
> gone, but simpler) without committing us to anything grandiose that we
> can't deliver on.

The problem with this is (a) because it seems that Eric's way to this goal is 
to make low level troff calls fail when used in man pages (see discussion 
on the .hygiene requestion). So, in the quest for semantics, presentation 
could suffer.

What is more important for the reader of a man page? I would think that it 
is that the information is presented in an easy to understand way, and, if 
the man page author resorts to using some low level troff commands, it 
may be to improve the presentation and readability of the information. Do 
we have to lose this?

The stated goal for this is to enable doclifter to be able to work better, so 
that manual pages are on the web, can be browsed and navigated by 
clicking on links. Does it require doclifter to achieve this? What if we come 
from the other direction and ask "How can we make groff produce output 
with these desirables". I know Eric's opinion on the PDF standard, but it is 
the best form of output, with web type navigation, to faithfully maintain the 
output as the author intended.

As an example, compare these two pages in a browser:-

http://manpages.ubuntu.com/manpages/trusty/man7/groff_mdoc.7.html
http://chuzzlewit.co.uk:8080/cgi-bin/WebManPDF.pl/man:/groff_mdoc

The first is from an Ubuntu site which has used doclifter to produce some 
nice html versions of man pages (not sure if it using the latest version of 
doclifter so this may not be fair). The second is just using groff to produce 
pdf pages. You will see small errors in both, but I'd be interested to hear if 
either is easier to read/understand. I know most will say "I prefer my 
terminal output" but this is just an experiment where the requirement is to 
produce documents for the web.

You will probably notice a speed difference because the doclifter version is 
using stored copies of the doclifted material, whereas groff is doing its job 
"on the fly".


Cheers 

Deri