groff
[Top][All Lists]
Advanced

[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




reply via email to

[Prev in Thread] Current Thread [Next in Thread]