Re: man2html

I would like to add my 2 cents here

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.

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.

Moreover, the man format is _very_ legacy, coming from the early 
1970-ties (?). (So the GNU project decided to invent something better, 
and wrote man pages just as stubs, essentially pointing to the texinfo 
docx.)


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...). 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?

> A manpage for the binaries is not developer documentation,
> it's user documentation. A description of the API is developer
> documentation, adn I  get it rght, that's currently built
> with Doxygen, not related the the man2html problem (right?).

Right. (It is also likely identical upstreams and downstreams.) So lets 
leave out the API docx from the discussion.


>> Would it be a big project to make all the developer docs
>> (including the html versions of the man pages) optional?
> 
> I believe it would be beneficial to have a default variant
> that does not install the API docs and the html manual
> (and whuch does not need doxygen and man and perhaps other stuff),
> and a 'doc' variant (is there a prefferred name for such variants?)
> taht would also install the API docs and the html manual.
> 
> (But that's a MacPorts question of course,
> not relaed to LIRC itself).

The question makes sense also "upstreams". It is basically a question of 
implementing it. I am sure the maintainer would be happy for pull 
requests and will merge all that are sensible. (BTW, make targets are 
better than configuration options.)


Greetz,

Bengt

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