HTML man pages (was Re: bin/7249)

[Alistair G. Crooks]

Just to put a spanner in this particular works - a hypertext-like
viewer for man and info pages is in pkgsrc/x11/tkman - please check
it out. It uses the standard man pages as input, and uses a program
called Rosetta man, or rman (pkgsrc/textproc/rman) to preprocess
its input.

Regards,
Alistair

[Tino Wildenhain]

Hi,

only to put 0.02 into the discussion:

HTML was invented for simple documentation, focused
on physics, back in 1992 when it was brougt up.

The key behind structurized documentation is metainformation.
Without metainformation, documentation is only an monolitic
block of text. Such a block of text, like READMEs or some
manpages are hard to work with, even if you are used to do.

Its not easy to jump to the interesting parts (its much more
easy with well formated man-pages then with REAMEs though)

Pretty printing with READMEs is also no-no.

Ok, XML cant provide a solution to all matters, its only a
language to build a document standard on.

I'm sure there is a DTD for technical documentation. If not,
we could commit to one main standard here, which would be
easyly extendable.

Then, who likes man output (s)he can it get from xml2man or such,
or can have normal man files generated.
Who likes HTML, can get it thru her/his favourite useragend vi XSL
or after transformation (ApacheXML and friends for the onliners)

etc. etc.

As far as I know, man files aren't written in the format of the
man program itself. So there it not to expect a hard change for
the authors.

Regards
Tino Wildenhain

(Dont forget about the ability to catalogize a well structured
dataformat)

[Paul A Vixie]

i agree. XML would be the right way to go if it had a champion here.

[Christopher Reid Palmer]

On Wed, 19 Jul 2000, Tino Wildenhain wrote:

> I'm sure there is a DTD for technical documentation. If not,
> we could commit to one main standard here, which would be
> easyly extendable.
>
> Then, who likes man output (s)he can it get from xml2man or such,

[...]

I could not agree more. Furthermore, I will volunteer to work on the
project of getting the NetBSD docs into the new format, if the Powers that
Be(tm) give the idea the thumbs-up.

In one of my more addle-brained moments, I schemed to build a Linux
distribution (I hear your groans) that did precisely this, although I was
vacillating between DocBook and LaTeX (I still love LaTeX best). I began
work on the distro but ceased for a number of reasons. There is no
particular reason I did not consider XML; I regard it as a viable choice.

Here is a (possibly incomplete) list of tasks for which I am volunteering
myself (and anyone else who is interested):

1. Decide on a document format
LaTeX
DocBook
Some pre-existing XML DTD
Some new XML DTD

2. Find and/or develop software
For converting from (1) to online and printable docs, either
interactively (xml2man, a CGI script, et c.), as a batch job, or
both. This might entail programs like man(1) becoming
wrappers/front-ends to the translator(s)

3. QA/Testing
How bad does it suck? In what ways could it be made to suck less?
Find willing testers

4. Refine per (3)

5. Repeat (2-4) until happy

5. Ship
Commit to CVS
..

Thoughts?

--
Chris
www.innerfireworks.com

[Tino Wildenhain]

Hi,

Christopher Reid Palmer wrote:
>
*snip*

>
> Here is a (possibly incomplete) list of tasks for which I am volunteering
> myself (and anyone else who is interested):
>
> 1. Decide on a document format
> LaTeX
> DocBook
> Some pre-existing XML DTD
> Some new XML DTD

I can help here, if you want.

>
> 2. Find and/or develop software
> For converting from (1) to online and printable docs, either
> interactively (xml2man, a CGI script, et c.), as a batch job, or
> both. This might entail programs like man(1) becoming
> wrappers/front-ends to the translator(s)

Some of them are already available. There are many parsers and
libraries around, SAX as example (not only in java, if someone
is afraid ;)

> 3. QA/Testing
> How bad does it suck? In what ways could it be made to suck less?
> Find willing testers
>
> 4. Refine per (3)
>
> 5. Repeat (2-4) until happy
>
> 5. Ship
> Commit to CVS
> ..
>
> Thoughts?

I feel we should move this discussion/project somewhere else, since
it is not tech-kern related furthermore.

Regards
Tino Wildenhain

[Mike Cheponis]

I, too, think XML would be fine. -Mike

[Hubert Feyrer]

On Wed, 19 Jul 2000, Christopher Reid Palmer wrote:
> 1. Decide on a document format
> LaTeX
> DocBook
> Some pre-existing XML DTD
> Some new XML DTD

It's already been decided to be DocBook. If this thread would appear on a
"proper" list, someone would probably have told you earlier. ;)

> 2. Find and/or develop software
> For converting from (1) to online and printable docs, either
> interactively (xml2man, a CGI script, et c.), as a batch job, or
> both. This might entail programs like man(1) becoming
> wrappers/front-ends to the translator(s)

pkgsrc/meta-pkgs/netbsd-doc and .../netbsd-doc-print is what you'll need
to convert DocBook->HTML and PS/PDF.

I haven't followed this thread so far, but if someone wants to further
discuss things, I'd suggest we move this to a more appropriate location
(either tech-userlevel or netbsd-advocacy?).

- Hubert

--
NetBSD - because Unix isn't just #include <linux.h>, i386, ILP32, ELF, ...!