[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Groff] Re: Simplifying groff documentation
From: |
Werner LEMBERG |
Subject: |
[Groff] Re: Simplifying groff documentation |
Date: |
Sun, 24 Dec 2006 08:19:21 +0100 (CET) |
> > The markup used within those man pages is not bad since it tries
> > to separate content from layout. What do you think about a few
> > comment lines in the header to `help' doclifter, something like
> >
> > .\" doclifter: .File_name (<foo>) == ...preferred doclifter command...
> > .\" doclifter: .Opt_[--] == "[--]"
> >
> > etc., etc. Such an interface could be generic, to be used with
> > texinfo macros also.
>
> I see. You're proposing a sort of macro facility that DocBook
> interprets itself, overriding the groff macros.
Not really a macro facility, rather regular expressions.
> 1) It would address the issue by adding complexity to the markup and
> the interpretation path, rather than subtracting it.
Not necessarily. Currently, you are applying doclifter's heuristic
engine to guess a high-level structure of a man page (cf. the example
w.r.t. embedded C code snippets you've given in another mail). The
markup in some groff man pages is already doing this -- it implements
macros which gives you those high-level markup! With other words, a
regexp solution would provide a direct translation instead of reduced
markup followed by educated guessing.
> 2) It won't solve the problem someone else in this thread pointed
> out, which is that the nonstandard macros break other viewers,
> including older *roff versions.
This, admittedly, is a valid argument. But it leads to nowhere IMHO.
It's the same as with HTML -- I'm sure there are still browsers which
can't display HTML 4 correctly...
A man page for groff probably should demonstrate the features it
provides. On the other hand, I could protect them with
.if !\n(.g \
. ab This man page can be displayed with GNU troff only!
which should `solve' the problem immediately :-) Honestly, I won't
mind to do
.ie !\n(.g \{\
Minimal stuff explaining what it is, where to look at,
how to process, etc.
.\}
.el \{\
Full groff man page.
.\}
> 3) It won't solve the actual problem with the simplified markup,
> which is the command synopsis not looking as nice.
Well, this is something different, I agree. What's your suggestion to
improve this? Is it possible at all to write troff code (not
necessarily man markup) so that doclifter can display something nicer?
> > Well, you can start your training with handling groff.texinfo...
>
> Sorry, I don't understand that.
I've misunderstood you. Apparently, you don't plan to write a
`lifting' engine by yourself to handle texinfo, right? Otherwise, you
could try groff.texinfo for testing purposes since it uses texinfo to
its extremes -- you might look up the many bug reports I've sent to
bug-texinfo within the last years.
Werner
- Re: [Groff] Simplifying groff documentation, (continued)
- Re: [Groff] Simplifying groff documentation, Zvezdan Petkovic, 2006/12/28
- Re: [Groff] Simplifying groff documentation, Eric S. Raymond, 2006/12/28
- Re: [Groff] Simplifying groff documentation, Werner LEMBERG, 2006/12/27
- Re: [Groff] Simplifying groff documentation, Eric S. Raymond, 2006/12/27
- Re: [Groff] Simplifying groff documentation, Werner LEMBERG, 2006/12/27
[Groff] Re: Simplifying groff documentation, Werner LEMBERG, 2006/12/23
- [Groff] Re: Simplifying groff documentation, Eric S. Raymond, 2006/12/24
- [Groff] Re: Simplifying groff documentation,
Werner LEMBERG <=
- [Groff] Re: Simplifying groff documentation, Eric S. Raymond, 2006/12/24
- [Groff] Re: Simplifying groff documentation, Werner LEMBERG, 2006/12/26
- [Groff] Re: Simplifying groff documentation, Eric S. Raymond, 2006/12/26
- [Groff] Re: Simplifying groff documentation, Werner LEMBERG, 2006/12/27
- [Groff] Re: Simplifying groff documentation, Eric S. Raymond, 2006/12/27
- Re: [Groff] Re: Simplifying groff documentation, Gunnar Ritter, 2006/12/27
- Re: [Groff] Re: Simplifying groff documentation, Eric S. Raymond, 2006/12/27
- Re: [Groff] Re: Simplifying groff documentation, Gunnar Ritter, 2006/12/27
- [Groff] The case against the case against .EX/.EE & .DS/.DE, Eric S. Raymond, 2006/12/27
- Re: [Groff] The case against the case against .EX/.EE & .DS/.DE, Werner LEMBERG, 2006/12/28