[Groff] manpage and groff -mandoc -Thtml

[Jonas Jermann]

Hi

I'm working on a big manpage and we just decided to put it on 
the webpage (html). It's the manpage of MPlayer 
(http://www.mplayerhq.hu/DOCS/mplayer.1).

I tried groff -mandoc -Thtml and man2html.
I kinda liked the output of groff but it wasn't useable as the 
man page style got lost (I'll explain later). man2html didn't 
help much neither and I didn't like the output much.

The problem of groff's output was:
    - several newlines became one
    - several spaces became one (wouldn't help if it worked as 
      the font won't be sthg like courier)
    - some newlines in the man page view got somehow lost in 
      html view
    - some newlines were added due to the html paragraph <p>
      (it always adds a newline afterwards)
    - maybe more

This made it unreadable, so the first thought was to search a 
better man2html command but I soon realized that the mistake was 
probably a bad designed/formated manpage.

I tried to find out as much as I could about groff/man 
pages/etc (mini howto from www.tldp.org, man 7 groff, man 7 
man, man tbl). But it was still very confusing (a big mess for a 
newbie imho) and I don't have unlimited time. I therefore 
wondred if there was some good guide to my topic around. Or if 
someone on this list could give me some help or better a 
solution ;)

The main question for me is: How should an option description 
look like to produce a nice html output and to be as easy and 
transparent to new man page writers as possible. At the moment 
it looks this way (filled with " " not tab):

[...]
end of last option.
.TP
.B \-cdda <option1:option2:..>
This can be used to blablabla. Available options are:

    speed=<value>        set CD spin speed
    paranoia=<0-2>       set paranoia level
                           0  disable checking
                           1  overlap checking
                           2  full data correction
                              and verification
[...]
    generic-dev=<value>  use specified generic SCSI
                         device
.TP
.B \-chapter ...
[...]

Some other questions:
    - Where exactly are commented '-' needed and where not?
    - What's the (sense of the) .RB option (didn't find)?
    - How are newlines handled? (Is just enter enough)
      Fact is: html just contains one <br> for 2 and more in
      the man page and comments after '.I EXAMPLE:' are on the 
      next line in the manpage but not in the html output, e.g.:

.I EXAMPLE:
    blabla1  sdkflk
    foo      dkflskdf
    bar      deojfpj

      becomes sthg like this:

EXAMPLE: blabla1 sdkflk foo dkflskdf bar deojfpj

    - Therefore I asked myself how are newlines handled? Where 
      does someone has to put a .br to really get a newline and how
      should the page look like (internal) to produce a manpage 
      that is readable on all windows bigger than 80 (can be called 
      standard window, or not?)
    - Same question goes for the synopsis, it's currently really 
      long and hard to change (all is needed), what to do about such 
      a long synopsis?

The manpage is full of those examples, so a completely new style
(general, easy, logic, etc :) or a better man2html tool is
(urgently) needed. 

FYI: I tried tables (.TS etc) but they didn't help much or looked 
just too cryptic in the man page source. Also I don't like them
as more tools are needed and as the output differs from the rest
of the html...


I know it was much but I surely forgot tons of questions. Any 
help about this is highly appreciated. :)

Thanks in advance and Best Regards!
    Jonas