This is the mail archive of the guile@sourceware.cygnus.com mailing list for the Guile project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Re: Doc Tasks (was RE: docstrings in Guile!)


Tom Emerson wrote:
> 
> Greg Badros wrote:
> >> As a side note, DocBook has special elements only for the C
> >> language. TeXinfo has special elements for Typed and Untyped
> >> languages, a @lisp environment, etc.
> >
> >I'll agree that DocBook is a bit too C-centric.
> 
> True enough. However, it is easy(*) enough to extend and enhance the DocBook
> DTD and its style-sheets for other language constructs.

But I'd emphasize the "bit" in "a bit too C-centric."  It's pretty
neutral, semantically.  Funcsynopsis, for example, which is where the
C-ness is most evident, is actually C-ish in syntax, not really in
semantics.  You got your function name, your params, and your return
type.  The stylesheets may turn this into a C function prototype, but
one could just as easily generate a Scheme-style layout.

> It seems to me (from the peanut gallery) that this entire argument is
> accomplishing nothing. The Guile community does not need a pissing contest
> over whose documentation system is better. Maciej should pick the one he is
> most comfortable working with, and we should move on. 

Amen.

> Or pole those people

Hey, let's keep it clean!  ;)  (For a second there I though you meant
"poleaxe".)

> who have signed up to write significant documentation to see what they are
> most comfortable writing.

And this is the acid test.  I can tell you I don't plan to do much
texinfo markup.  Those with a low *ML tolerance can write plaintext doc
where they need to and otherwise spend time writing code; but please
don't whine about the real or imagined shortcomings of Docbook.  It
reminds me of nothing so much as the "too many parentheses" whining from
Scheme-haters.

At the same time, I take it as a requirement that the documentation be
viewable using info/emacs help.  HTML is a done deal already, but I and
no doubt many others prefer the emacs help facility.  So, obviously, if
we use docbook somebody's going to have to write the stylesheet the map
to texinfo.

It also needs to be printed "appropriately" - I'm personally much more
flexible w/r/t printed format.  The standard GNU style works fine for
me, but I quite like the idea of experimenting with other designs. 
Standard Docbook style is only one option; I think it would be
interesting to try some Knuth-style formatting as well.

> I am willing to expand the DTD and style-sheets needed by the "Guile
> Documentation Project" in whatever way is necessary.

I played around with this a bit yesterday.  Later today I'll post some
stuff on a webpage to solicit feedback.  Basically I started out
thinking "ok, where should Docbook be extended?" and progressed to "ok,
what's the semantic structure of the information here, and how should it
be modeled in XML?"  Which, doh! is of course the Right Way to Go in the
first place.  Having setteled on a good candidate grammar, comparing it
to Docbook will reveal where to snarf and where to extend.  I'll start a
new thread to toss out some ideas.

And keep in mind that Docbook is also designed for reducability as well
as extensibility; one could define a smaller simpler Docbook Jr., maybe
to avoid confusion among a large number of contributors, and not lose
the benefits of Docbook compliance (DTD verification, stylesheets, etc.)

> FWIW, the Linux community is moving towards DocBook for their documentation
> (see http://www.linuxdoc.org). In the Gwydion Dylan Group
> (http://www.gwydiondylan.org) we are also converting our documentation to
> DocBook. I am a big fan of semantic markup, and would prefer to see DocBook
> used for the documentation.

And we're really only at the beginning.  Encoding text in *ML will pay
multiple dividends down the line when sophisticated hyperlinking and
other *ML technologies become more widely available.

Those on the list who regard *ML with fear and suspicion would do well
to take a stroll through Robin Cover's wonderful and awe-inspiring
SGML/XML Webpage at http://www.oasis-open.org/cover/.  There is an
astounding wealth of resources available for *ML technologies, with
many, many more on the way.  Also take a look at IBM's Alphaworks pages
- they've made some very powerful XML stuff freely available. 
http://www.alphaworks.ibm.com/.  If the letters 'I', 'B', and 'M' scare
you away, try http://www.apache.org.

But remember, it's the data format that counts - *ML gives us freedom. 
XML should be the poster child of the free software movement.  Dozens of
large business organizations are now designing and implementing
XML-related software, and giving it away.  Nobody cites the FSF when
they do this, but they should; personally I thank rms and the fsf for
this bounty.  It would be an irony too wierd to contemplate if a major
GNU project were to turn its back on its own offspring.

A few more datapoints:  Docbook is under active *funded* development,
and 
"Future versions of Docbook may provide additional environments for
describing the syntax summaries of functions in other programming
languages."  (from the duck book, p 239, doh!, I just realized that was
a visual pun, way to go, O'Reilly.)  Not to mention, the co-author of
the duck book happens to be the guy (Norm Walsh) who wrote and maintains
the DSSSL docbook stylesheets (DSSSL = Scheme).  It's safe to say he
would be happy to find somebody making docbook more friendly to Scheme. 
Why don't we do that?

That's pretty much my $0.02 on that.  I would ask that those who wish to
pursue any kind of "texinfo v. docbook" or "xml sucks" topics please use
appropriate subject lines so I can avoid reading it.  Or post to the
xml-dev list, where you may well find somebody whose done xml<->texinfo
stuff.

cheers,

-gregg

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]