manpages on website and as appendix in manuals

[Joost van Baal]

On Sun, May 27, 2001 at 12:17:53PM +0200, Egon Willighagen wrote:
> On Sunday 27 May 2001 12:11, Egon Willighagen wrote:
> > Now that the documentation is in DocBook XML 4.1 format, maybe
> > we could move the manpages to this format as well... (at least for the
> > non-POD based instances...)
> >
> > It would solve/make possible:
> > - problems with placing man pages on website

There was an idea of using debian's dwww for this.  You can see it at
http://mdcc.cx/dwww/man/ and at
http://mdcc.cx/cgi-bin/dwww?type=man&location=/usr/share/man/man1/lr_log2report.1.gz

On http://mdcc.cx/doc/HTML/system/index.html and http://mdcc.cx/dwww/menu.html
you can see the Lire User Manual and the LogReport Developers Manual.  This
is achieved by installing the lire .deb on a debian box, and installing dwww.

> > - inclusion in manual (as appendix)
> > - linking between manpages

linking is solved by dwww, as can be seen by above url's.

> > Conversion to "normal" manpages is done with docbook-to-man, which
> > is in the Debian package with the same name...
> 
> Two examples of DocBook based man pages can be found at:
> 
>   http://docbook.org/tdg/html/refentry.html
> 
> Docbook-to-man can be found at:
> 
>   http://www.oasis-open.org/docbook/tools/dtm/
> 
> (For non-Debian users...)

If we go for docbook as the format for manpages, I'd prefer to ship both
the docbook sources as well as the troff formatted pages in our lire
tarball, similar to as we do with the Lire User Manual now.

Another example is in debian debhelper's
/usr/share/debhelper/dh_make/debian/manpage.sgml.ex .

Sticking with perl's pod format, and using dwww to convert to html,
has another drawback: dwww by default is not accesssible from the internet.
The dwww part of the webserver is restricted to accesses from localhost
only, since everybody can see which - possible vulnerable - versions of
software the webserver has got installed.

What do you say?

Bye,

Joost


-- 
To UNSUBSCRIBE, email to development-request at logreport.org with a subject of 
"unsubscribe". Trouble? Send an email with subject "help" to 
development-request at logreport.org