[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Groff] tbl like structures
From: |
Jonas Jermann |
Subject: |
Re: [Groff] tbl like structures |
Date: |
Wed, 4 Sep 2002 01:15:15 +0200 |
User-agent: |
Mutt/1.4i |
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