Re: [Groff] Back to the future]

[Deri James]

On 06/03/14 16:35, Eric S. Raymond wrote:
> No, what I want is for all Unix documentation to be properly wenbbed 
and 
> crosslinked.

I find it difficult to understand why groff needs a .hygiene, maybe it's 
because I'm a dirty rascal! It seems to be a switch which is designed to 
stop naughty man pages from working, in the hope this will prompt the 
man page authors into changing them. But these are only "naughty" 
because they don't play nicely with Eric's tool set, not that there is 
anything wrong with them from the groff typesetting perspective.

So we are pondering whether to create this work for an unknown number 
of man page authors. The reason for doing this should be defensible, but I 
wonder whether it is?

The stated reason for this is the desire to make the man pages 
browseable, which requires semantic markup of the document in order to 
produce decent html. However, there are other routes to this goal, which 
do not require the participation of recalcitrant man page authors, nor 
patches to documents.

All browsers will happily display pdf documents, and since groff can easily 
produce pdf documents which include embedded URLs, is there any 
reason why they should not be the medium for having browseable man 
pages. A little bit of work today has got me to a working solution.

First you need a protocol for man pages. My linux already has the protocol 
"man:/" (which is tied into use some form of "man2html" which produces 
less than beatiful results), so I hijacked that protocol by changing it to call 
a program (pdfmansec) which takes the URL "man:/section/name" and calls 
"man -t -S section name". Meanwhile, the man config file is changed to use 
the pipeline "pdfman | groff -T pdf -mandoc | okular -". The program pdfman 
simply adds the required calls to pdfhref etc. The results of this are in can 
be seen here:-

<http://chuzzlewit.co.uk/pdfman-examples.tgz>

It contains a few random pdf man pages, as examples, the two programs I 
added to my system, and the kde protocol file. The links to other man 
pages in the pdf examples will not work unless you have configured the 
"man:/" protocol for your system, but any links to the web will work. It even 
worked in the url bar for firefox, when it asks for what to use for this 
protocol enter 'pdfmansec'. Or you can still use 'man -t cmd' from the 
console to get the clickable pdf.

It is still in need of some work and if you explore your man pages using the 
clickable links, I'm absolutely sure you will find some which break the pdf, 
but I've only spent a day and a half so far. Any comments or suggestions 
gratefully received.

When my wife enquired "What have you been up to in the office?" and my 
reply was "Playing with my man pages.", I don't think she quite understood 
what I meant.

Deri