M Bianchi <[EMAIL PROTECTED]>:
> 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.
There, there. Nobody is going to try to pry your groff away from your
cold dead fingers. :-)
> 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)
I think you'll see from my previous reply to Ted Harding that
I agree with this.
> 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.
Well, of course what we want is "clear, cogent and accurate documentation".
But I can't solve *that* problem. What I can do, and have been doing more
or less by stealth since 2001, is lining up all the technical ducks in a
row so we can address the format and infrastructure problems.
> 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.
A worthy goal, but really independent of the underlying formatting engine.
groff vs. browser makes little difference here.
> Again: the goal should be making the documentation something people
> passionately care about, so remain stay living documents forever.
I think, at least, that I may be helping ensure that the good old
stuff doesn't get lost in the transition to the big Webbed world.
> 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
Well, no, actually. DocBook -> man is easy -- you're throwing away
structure when you do that. man -> DocBook is *hard*, because you have
to deduce semantic structure from presentation-level cliches.
In fact, consensus among the world's DocBook mavens was that this was
impossible to pull off -- before I, er, did it. It required an unusual
combination of advanced compiler-jockery, familiarity with certain AI
techniques, and sheer bloody-minded persistence.
> Could the wikipedia markup be (close to) adequate? Something
> similar? Standing firmly on an existing popular standard could be
> important to achieving wide acceptance.
And that's why, in the grand master plan, XML-DocBook has a central
role. Nobody wants to read it directly -- you render to HTML or
Postscript with a stylesheet to do that. But it makes a dandy
format for masters and searchable archives. Wiki markups doesn't
quite have the structural richness needed.
But the world I'm trying to get us to looks something like this:
+-------------+ +--------------------+
| man pages |-----+ +--->| HTML on browsers |
+-------------+ | / +--------------------+
| /
+-------------+ | +-------------+/
| Texinfo |-----+-------->| XML-DocBook |
+-------------+ | +-------------+\
| \
+-------------+ | \ +------------------------+
| other |-----+ +--->| PostScript on printers |
+-------------+ +------------------------+
Multiple composition formats (including man markup) but all feeding to
one richly-structured exchange format, which is then rendered to
different media by stylesheets.
--
<a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>
_______________________________________________
Groff mailing list
Groff@gnu.org
http://lists.gnu.org/mailman/listinfo/groff
