I think that with the addition of new list tags would solve the list problem.
Currently these don't exist and grohtml  www.tmac is kludging a list
by attempting to shut down a previous paragraph before emitting a
tag directly.  Much better to bite the bullet and make the backend of grohtml
understand these tags.  It shouldn't be much work and would solve the
problem.

I propose to do this  - and I also would like to introduce div/span tags.
It would also be sensible to allow some configuration of
macro set and css relationship - which could really aid appearance.
Footnotes, boxed text would also be rendered well with this approach.
Ultimately table tags should be added which would allow html tables
to be rendered.  But for now it is best probably to tackle the easier
problems first - the including of list tags.

regards,
Gaius

[This is from Christopher]

> Sorry for answering that late; this bug report has been completely
> below my
> radar.
>
> mdoc has been specifically constructed to be easily parseable by other
> programs also (especially having HTML in mind, I think), thus a
> solution like
> yours is a natural extension.

I did not try to parse mandoc on my own; I use the groff engine to do
it.  The alternative approach you recommend, called man2html, is a
miserable failure and not worth maintaining IMHO.

>
> My knowledge of XML is very limited – is there any disadvantage to
> target
> HTML output directly?  Why the XML intermediate step?

I wanted to change mandoc as little as possible without rewriting any
non-extension code and without adding any logic of my own.  Therefore
I get, for example:

  <li >a <li >b <li >c <li >d </li ></li ></li ></li >

from mandoc, to be pulled up to

 <li >a </li ><li >b </li ><li >c </li ><li >d </li >

by the post-processor.  This transformation is rather unnatural for
XSLT and XSLT was not optimised for it, so there is room to improve by
using another transformation engine; I picked this one because I tend
to be familiar with it :-) What is important is the idea of embedding
device-independent structural information in ditroff output.

>
> On the other hand: Why not improving grohtml to make it output better
> HTML?
> It should be straightforward to add more grohtml tags to the mdoc
> sources if
> necessary.  The `more readable HTML' argument is of no importance
> IMHO.
>

If you read the principles of grohtml, you will learn that it is an
archaeologist trying to put broken pieces of pottery together.  It may
sometimes work, and there is nothing better to do against an unknown
and unsupported macro package, but a slight modification of the macro
package can make the whole process much more robust by including the
metainformation as directives.  (Grohtml does it in a limited way but
it is guesswork based on screen scraping; the only way to a
predictable result is to reproduce the semantic information conveyed
by document structure macros in XML directives.)

The 'more readable HTML' means also that it is more readable to
machines; it can be correctly indexed by crawlers styled to one’s wish
without modifying the code and read aloud to blind people according to
the authors’ intention.

Add to this the potential advantage of producing equations in proper
HTML or MathML.

> IMHO, working on grohtml is the better approach (at least from my
> point of
> view as the groff maintainer).  What you have created would be a good
> template
> and guidance how grohtml output should (or could) look like.

It would be awesome if the maintainer of grohtml could offer a
comment.  IMHO, the grohtml way cannot be significantly improved.

I have taken the liberty to summarise the present support for legacy
manual pages on X11 displays [2].  The picture is very disappointing
and I can see no way I could advise a non-technical person who is not
fluent in English to install and use free software under these
circumstances.

Thank you for your consideration,
Chris

== A proposed solution ==

I think it would be possible to modify existing mdoc sources to produce semantic HTML directly via write or preferably via device-specific output instructions.
groff has no way to predict the font metrics in the browser that displays the result so the output must be high-level to be predictable.  A construct-by-construct transformation to XML would a valuable intermediate step: construct-by-construct is easy and XML-to-HTML is easy.

== Packing list ==

1. A patch for mdoc to include device-specific instructions of the form \X'x:<TAG>';
2. A script to process raw gtroff output in the following sequence: .n > groff -Z > .roff > sed > .xml > xsltproc > .html
3. The intermediate and final result of applying the script to the source file.

Please note that this work is preliminary and for demonstration purposes only.  However, I am willing to develop this approach if you can see a method and possibility to integrate it with groff.

== Advantages ==

• it actually uses groff, whereas doclifter does not,
• it produces semantic HTML and a more readable rendering than grohtml

== Disadvantages ==

• It is less general than grohtml in that it applies only to -mandoc.
• The last step depends on libxslt, which is part of GNOME.

== Questions to the maintainer ==

• Do you see a possibility to integrate this approach with groff?
• If so, can you offer guidance to that effect?

(file #20685)