bugGNU roff - Bugs: bug #30043, [mdoc] nested lists rendered...

 
 

bug #30043: [mdoc] nested lists rendered incorrectly in HTML

Submitter:  Christopher Yeleighton <yecril71pl>
Submitted:  Thu 03 Jun 2010 04:04:19 PM UTC
Votes: 1
 
Category:  Macro mdoc Severity:  3 - Normal
Item Group:  Incorrect behaviour Status:  Confirmed
Privacy:  Public Assigned to:  wl
Open/Closed:  Open Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Sun 21 Aug 2022 02:08:14 PM UTC, comment #6: 

This problem appears to be specific to the mdoc macro package.

I created a much smaller reproducer, rewrote it in man(7), and tested with groff Git HEAD.

Observe the attachments.

(file #53593, file #53594, file #53595, file #53596)

G. Branden Robinson <gbranden>
Group administrator
Sat 29 Jan 2011 03:44:20 PM UTC, comment #5: 

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

Gaius Mulley <gaius>
Group Member
Sat 29 Jan 2011 01:04:13 PM UTC, comment #4: 

Please note that I don't recommend `man2html'.  I only wanted to say that easy parsing was one of the reasons for developing -mdoc, intended eventually as a replacement for the -man macros.
Today we know that this hasn't become reality.

Regarding your concerns about grohtml: I think you have a wrong image of what I want to suggest.  You are completely right that grohtml tries to `reconstruct' high-level features which have been lost during the processing.  But this is just one side.  With proper tagging, grohtml can emit high-level HTML exactly the way you want to have it (notwithstanding bugs).  It's a matter of fact that users tend to add low-level stuff even to man pages in -mdoc format, stuff which fails with any non-groff postprocessor. But grohtml can handle this automatically.  Together with proper tagging added to -mdoc, it should be possible to get a good synthesis between these two approaches.

Please don't forget that together with Gaius I have developed the main ideas how grohtml can work at all.  Thus I know the involved ideas very well (but my knowledge of the implementation details is rather weak).

I've already CCed Gaius; maybe he has time to comment.

BTW, I've forgotten to add the link for [2] in your last comment.  Here it is:

  https://bugs.kde.org/show_bug.cgi?id=244894#c5


    Werner

Werner LEMBERG <wl>
Group administrator
Sat 29 Jan 2011 12:52:52 PM UTC, comment #3: 

[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

Werner LEMBERG <wl>
Group administrator
Thu 27 Jan 2011 04:51:17 AM UTC, comment #2: 

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.

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

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.

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.

Werner LEMBERG <wl>
Group administrator
Thu 03 Jun 2010 04:53:44 PM UTC, comment #1: 

== 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)

Christopher Yeleighton <yecril71pl>
Thu 03 Jun 2010 04:04:19 PM UTC, original submission:  

groff -mandoc -Thtml pftp.1
produces output that is valid but visibly broken and unreadable.

Christopher Yeleighton <yecril71pl>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

Attached Files
file #53593:  30043.mdoc added by gbranden (802B - application/octet-stream)
file #53594:  30043mdoc.html added by gbranden (2KiB - text/html)
file #53595:  30043.man added by gbranden (743B - application/x-troff-man)
file #53596:  30043man.html added by gbranden (2KiB - text/html)
file #20685:  solution.tar.gz added by yecril71pl (19KiB - application/x-gzip - solution package as described)
file #20683:  pftp.tar.gz added by yecril71pl (25KiB - application/x-gzip - source file and output file)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by gbranden (Updated the item)
  • -email is unavailable- added by schwarze (Updated the item)
  • -email is unavailable- added by gaius (Posted a comment)
  • -email is unavailable- added by wl
  • -email is unavailable- added by wl (Posted a comment)
  • -email is unavailable- added by yecril71pl (Voted in favor of this item)
  • -email is unavailable- added by yecril71pl (Submitted the item)
  •  

    There is 1 vote so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 14 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2022-08-21 gbranden Attached File- Added 30043.mdoc, #53593
        Attached File- Added 30043mdoc.html, #53594
        Attached File- Added 30043.man, #53595
        Attached File- Added 30043man.html, #53596
        CategoryDriver grohtml Macro mdoc
        Summaryhtml mode: nested lists rendered incorrectly [mdoc] nested lists rendered incorrectly in HTML
    2018-02-16 schwarze CategoryNone Driver grohtml
        Item GroupNone Incorrect behaviour
    2011-01-27 wl Carbon-Copy- Added gaius
    2011-01-27 wl StatusNone Confirmed
        Assigned toNone wl
    2010-06-03 yecril71pl Attached File- Added solution.tar.gz, #20685
        Carbon-Copy- Added yecril71pl
    2010-06-03 yecril71pl Attached File- Added pftp.tar.gz, #20683

    Back to the top

    Powered by Savane 3.13-3230.
    Corresponding source code