Re: man2html

On Jan 02 21:11:03, [email protected] wrote:
> The idea of portable, single-source documentation (source of the
> documentation in a content-oriented format, then processors producing
> different target formats) is modern, well established practice, not only in
> Linux community. For example, already the Gnu project decided on such a
> system (texinfo). This is a very good and clean approach. Among other
> things, we can achieve a separation between form and content.

A manpage is a single-source documentation,
and groff's (or heirloom's or mandoc's ...) rendering of it
via -man -T(ascii|html|ps|pdf) are the different target formats.
What other formats are there to be desired?

Also, being a GNU decision does not mean to be "well-established".

(BTW, ESR and RMS agree to move from texinfo to asciidoc
or whichaver GNU attrocity du jour.)

> This is not to say that the present system is perfect, or even good.
> The fact that there are minor problems with one of the post-processors
> (man2html) is not justification to throw out the principle of portable
> documentation.

A single manpage is portable documentation. It has been for decades.
Relying on a particular tool to transpose it in a particular way is not.

> Moreover, the man format is _very_ legacy, coming from the early 1970-ties.

Yes, just like UNIX.

Proper manpages are written in the mdoc(7) language, not man(7).
The *BSDs have made the switch years ago, MacOS more recently.

> (So the GNU project decided to invent something better, and wrote man
> pages just as stubs, essentially pointing to the texinfo docx.)

That's one of the GNU attrocities: "manpages are stubs".
They are not - they are the ultimate documentation.

> On 01/02/18 20:09, Jan Stary wrote:
> > > Just using man2html from the man package
> > > fixes things sufficiently for my purposes.
> > 
> > Yes it does - in MacPorts, which now uses this particular man2html.
> > There are many other man2html's out there (all as shit as this one),
> > so it's entirely possible this same thing is broken on other systems.
> 
> I see you point (although I would prefer a less fecal language...).

Have you seen its output, even in the case when it works?

> So the
> only really portable solution would be to pack some portable implementation
> (for example in Python3) in the package; should not be too hard. Wanna help?

My motivation here is to get rid of man2html in the MacPorts,
which is what got me here, realizing the are about ten "man2html"s.
Creating a Python3 translator from man to html
is quite the opposite of where I come from.

Also, having just the manpages and not their html transalations,
that would be totally portable.

	Jan


------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot