[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: <OK> [Groff] Simplifying groff documentation
From: |
M Bianchi |
Subject: |
Re: <OK> [Groff] Simplifying groff documentation |
Date: |
Fri, 22 Dec 2006 20:00:10 -0500 |
On Fri, Dec 22, 2006 at 06:19:15PM -0500, Eric S. Raymond wrote:
> :
> But I hear you asking "Why fix what ain't broken?".
> :
> 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?
> :
Don't take my groff away! (Yes, I see you did _not_ propose that.)
I have documents from the late 1970s that I can still format and maintain.
And programs that write groff to create well formatted information. For me,
groff _is_ my _primary_ format. (and no I don't think others must follow me,
but there are other people who discover the value of computing your documents
and find groff as suitable.
> :
> 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.
Oh, I don't want to jump into this one, but I'm going to ...
The value of man pages is not the markup language.
The value is (when done right):
structured, standardized presentation
NAME, SYNOPSIS, DESCRIPTION, OPTIONS, SEE ALSO, BUGS
standardized nomenclature
e.g. standard output, standard error output, ...
language, reviewed and refined over time, that aims at clarity of
thought and expression
a focus on economy of expression; man pages are reference documents not
"a good read". Brief accuracy is valued over methodic instruction.
avoidance of novel-like plot development and language, cute and clever
phraseology, snide comments about the competition, etc.
relevant cross references (aka SEE ALSO)
What is broken with man pages _is_ the fact that nroff/troff/groff is no-longer
lingua-franca of developers. But then neither is the info format.
HTML is not an answer because it is not widely understood among developers and
is as much an assembly language as *roff and latex.
A standardized CSS style and XML _might_ work but ...
To me, having "fully-hypertexted, Web-centric documentation" is the wrong goal.
Having clear, cogent and accurate documentation is. If ESR's proposal creates
that outcome, yippeee! If not, boooo.
An input format for man page _information_ that provided the structure,
guidance, and mechanisms to guide people into creating clear, cogent and
accurate information, is something I would applaud.
> (And brace yourselves for the *real* political bunfight, which
> is when I try to kill off GNU info...)
To my mind info fails because it, almost by design, lacks some of the things
that make the good and classic man pages work.
It also fails because it _insists_ on interactive navigation and there is no
way (that I am aware of) to print out a definitive reference. Some of my most
valued documents are info documents turned into a single, flat text file.
E.g. make . I can drop into an editor and go anywhere with a single regexp.
It also works as a book.
Again: the goal should be making the documentation something people
passionately care about, so remain stay living documents forever.
I believe that if the effort was done properly, then the content could be
mechanically translated into any of the formats, including long, flat text
files. man -> docBook would imply docBook -> man
Could the wikipedia markup be (close to) adequate? Something similar?
Standing firmly on an existing popular standard could be important to achieving
wide acceptance.
--
Mike Bianchi
Foveal Systems
973 822-2085 call to arrange Fax
address@hidden
http://www.AutoAuditorium.com
http://www.FovealMounts.com
- [Groff] Re: Simplifying groff documentation, (continued)
Re: [Groff] RE: Simplifying groff documentation, Peter Schaffter, 2006/12/23
- Re: [Groff] RE: Simplifying groff documentation, Eric S. Raymond, 2006/12/23
- Re: [Groff] Simplifying groff documentation, Ralph Corderoy, 2006/12/31
- Re: [Groff] Simplifying groff documentation, Eric S. Raymond, 2006/12/31
- Re: [Groff] Simplifying groff documentation, Gunnar Ritter, 2006/12/31
- Re: [Groff] Simplifying groff documentation, Eric S. Raymond, 2006/12/31
Re: [Groff] RE: Simplifying groff documentation, Ted Harding, 2006/12/23
Re: [Groff] RE: Simplifying groff documentation, Eric S. Raymond, 2006/12/23
Re: <OK> [Groff] Simplifying groff documentation,
M Bianchi <=
- Re: <OK> [Groff] Simplifying groff documentation, Eric S. Raymond, 2006/12/23
- Re: <OK> [Groff] Simplifying groff documentation, M Bianchi, 2006/12/23
- Re: <OK> [Groff] Simplifying groff documentation, Eric S. Raymond, 2006/12/23
- Re: <OK> [Groff] Simplifying groff documentation, Gunnar Ritter, 2006/12/24
- Re: <OK> [Groff] Simplifying groff documentation, Eric S. Raymond, 2006/12/24
- Re: <OK> [Groff] Simplifying groff documentation, mhobgood, 2006/12/24
- Re: <OK> [Groff] Simplifying groff documentation, Eric S. Raymond, 2006/12/24
Re: <OK> [Groff] Simplifying groff documentation, Werner LEMBERG, 2006/12/23
Re: <OK> [Groff] Simplifying groff documentation, Eric S. Raymond, 2006/12/23
Re: <OK> [Groff] Simplifying groff documentation, Werner LEMBERG, 2006/12/23