[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: |
Sat, 23 Dec 2006 16:22:35 +0100 (CET) |
> I want to drastically simplify the markup used in several pieces of
> groff documentation, eliminating a lot of the hairy custom macros
> they presently use.
Mhmm.
> groffer.1
> groff_out.5
> groff_tmac.5
> groff.7.gz
> groff_char.7
> groff_mdoc.7
> groff_trace.7
>
> Technically this won't be hard; I could make the required changes in a few
> hours. But I hear you asking "Why fix what ain't broken?".
Hehe. There's some truth in it.
> The immediate technical answer is "the macro hackery is getting in
> the way of lossless translation to a Web-ready format".
Simply replacing them with the `standard' man macros is not the
optimal solution. Instead, I would rather prefer some helper
instructions so that doclifter can do the translation without
problems.
> So this is the answer to "why fix it?". Because the groff pages
> presently do elaborate, bizarre things that doclifter can't cope
> with.
Bizarre? I don't think so. The results are satisfying. However, I
agree that the used macros are non-standard, causing headaches to
doclifter.
> I want to fix the groff documentation so that it's no longer in the
> way of automatic lifting of *everything* to HTML. (As a side
> benefit, the markup in the groff documentation will become easier to
> maintain.) The only downside might be a slight decrease in the
> visual quality of the printed versions -- in particular, command
> synopses might no longer look quite as pretty.
Indeed. The `only downside' is one of my main concerns. And the
`slight decrease in visual quality' is sometimes really terrible. I
really dislike the `unify everything, but in worse quality'. There
*must* be a solution which satisfies both you and me.
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.
> The philosophical issue this raises about groff's place in the world
> is simple: are we willing to accept that it's a legacy rather than a
> primary format?
I don't care, really. Personally, I dislike docbook as an input
format but this is just me.
> But I think it's time to move on. This little change will help us
> get to a fully-hypertexted, Web-centric documentation corpus. Let's
> do it.
Let's do it right.
> (And brace yourselves for the *real* political bunfight, which is
> when I try to kill off GNU info...)
Well, you can start your training with handling groff.texinfo...
Werner
- Re: [Groff] Simplifying groff documentation, (continued)
- Re: [Groff] Simplifying groff documentation, Eric S. Raymond, 2006/12/26
- Re: [Groff] Simplifying groff documentation, Gunnar Ritter, 2006/12/27
- Re: [Groff] Simplifying groff documentation, Eric S. Raymond, 2006/12/27
- Re: [Groff] Simplifying groff documentation, Gunnar Ritter, 2006/12/27
- Re: [Groff] Simplifying groff documentation, Eric S. Raymond, 2006/12/27
- 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 <=
- [Groff] Re: Simplifying groff documentation, Eric S. Raymond, 2006/12/24
- [Groff] Re: Simplifying groff documentation, Werner LEMBERG, 2006/12/24
- [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