Re: [Groff] tbl like structures

[Jonas Jermann]

On Tue, Sep 03, 2002 at 11:14:36PM +0100, Ralph Corderoy wrote:
> As no-one else has answer yet, I'll have a go but I'm not sure how much
> I can help.
thx :)
 
> > I don't want to use tbl.
> 
> Could you tell us why not?

I already wrote 2 mails before. In short: I decided to 
restructure the man page to solve certain problems. This 
includes:

    - A way to specify big suboption description without the 
      need to manually structure them (e.g. line brake at a
      certain position, add spaces to fit position, etc)
    - Produce nice groff -Thtml -m man output
    - Produce nice uniform and easy man page format

I tried tables but first: they need to be preprocessed (bad 
IMHO), 2nd: the html output of the table differs from the rest (I 
more like a uniform stlye) and 3rd: The syntax is not as easy as 
one might think. To produce good results I somehow ended up in a 
mess.

> > What possibilities exist to create one of the following things (using
> > standard man page commands)?
> > 
> >     1) .TP/.IP without newline before them
> >        = _no newline_, place first at start position, newline,
> >          place 2nd,... at position given by .TP/.IP argument
> >        = (?) some way to create table like structures without 
> >          paragraphs
> > 
> >     2) The same without line brake after title
> >        = no newline, place title (first) at start position,
> >          _no newline if there is enough space_, place 2nd at
> >      position given by .TP/.IP argument, same as above...
> > 
> >     3) (already asked) generally redefine the indentation of
> >        .TP/.IP
> 
> I'm not quite sure what you mean.  You could write your own versions of
> these macros changed to behave the way you want.  Include their
> definitions at the start of your man page and they'd then be available
> to you.  But that would really be using `standard man page commands'
> since you'd be creating some new ones.  Look at an-old.tmac for some
> definitions to base yours on.
> 
> > PLEASE, just tell me if this is a RTFM (where?) if solution 'xxx' was
> > better anyway or anything else.
 
> It does sound like you're fighting against the man macros.  Can you tell
> us *why* they need to be different.  If it's author preference over how
> something is laid out then that isn't particularly what the man macros
> are aimed at.  They're meant to present documentation in a uniform,
> standard, way.

hmm, I agree 100%. My problem is: I have no idea how it is 
supposed to be used. It can't be the attempts I tried as their 
results just look ugly, so my first attempt was to change the 
options to get a better output.
 
> > I spent a lot of time in it without any success and IMHO all the
> > groff/man page documentation is a mess. What I could need was a good
> > example man page or guide (related to my problem).
> 
> You haven't told us what the problem is.  Just what the symptoms are
> regarding .TP/.IP.

Ok, I'll try (again) to describe it: Basically all I need are ideas 
how to get a easy structure, with nice html and man page output.
The basic ideas are already written above. You'll find the _old_ 
man page on http://www.mplayerhq.hu/DOCS/mplayer.1 (It should be
replaced with a better "design")

Some specific comments:

    - Note: RSs is ".RS \ni+3" (i is 7)
      If I got it right, .RS somehow always starts from the 
      beginning (not from .TP indentation)
    
    - The man page is full of suboptions, the way I did it till 
      now is as followed:

      ......
      .TP
      .B -opt1
      main description
      .RSs
      .IP suboption1
      sub descr1
      .IP suboption2
      sub descr2
      [...]
      .RE
      .TP
      ......
      
      I donno, but IMHO it looks way better with a lower indentation
      off .IP (around 3). I don't know how to change it generally.
      (I always used .TP for main and .IP for subopts)
    
    - The man page is full of examples, I tried to do the same 
      for it but then the output loks this way (IMHO very ugly, 
      note the newlines around EXAMPLE, with more than one example
      it adds a newline after every -> even worse):

      ......
      description
      
      EXAMPLE:
      
         -alang hu,en
                foo bar blablakjsdfkjsdfksdlfks dj fadsjkf 
                ldhfkjasdfhskdj

      ......
         xxxxxxx <- IMHO this indentation is too much for a suboption
         (for an option it seems to be standard and acceptable)...

      If this is really the normal way, I'll leave it of course, 
      but I somehow got the fealing that I missed the idea...

    - Therefore I added a new style for examples and similar 
      small descriptions:
      .de RSss
      .PD 0
      .RS \ni+3
      ..
      and
      .de REss
      .RE
      .PD 1
      ..
    
    - Same problem as above: IMHO a low indentation of .IP looks 
      much better. 
  
    - Some line brakes got somehow lost in the html output.

    - The html output creates paragraphes around the option 
      which are surrounded by newlines (at least by all browsers 
      I tested). It looks ugly IMHO, the description should be 
      nearer (no newline IMHO) by its option than by the next.

    - All newlines one after another (over 1) are ignored -> 
      just one newline (not big problem).

    - Surely more...

I appended a my test man page (see -vc EXAMPLES and -cdda 
suboptions). The rest stayed more or less the same way (till 
now). Remember: It's a test version ;)

Sorry the mail is getting big, that's why I tried to reduce it 
to concrete questions, I failed. A general advice/hint would 
help much more :)
I apologize for asking such questions/etc but it was the only 
place for hope I found.


Best Regards and thanks in advance
    Jonas Jermann