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

[Telford Tendys <telford at eng dot uts dot edu dot au>]

> > > http://www.oasis-open.org/docbook/documentation/reference/html
> > > /docbook.html;
> > > but you should buy a copy so Norm gets money!)
> > 
> > That's a non-free documentation owned by a publishing 
> > company. It is exactly
> > the sort of thing that the GNU project does not need. I hate 
> 
> What's wrong with this picture?  A non-profit, international consortium of
> many vendors puts together a sophisticated DTD for technical documentation,
> it becomes widely adopted and easily available via the net, a couple of
> people thoroughly document it, a publisher widely known for supporting free
> stuff publishes not only a paper version but a freely available html
> version.
> 
> Now, how exactly is that non-free?

[1] freedom to distribute copies

The html documentation is not free because I cannot legally put a copy of it on my
web page, nor can I distribute a copy of it with my work. At any future time
it may be removed from the WWW and my only freely available documentation is gone.

[2] freedom to modify

What's more, the html documentation (and book too presumably) claim the be the
official and authoritative description of the DocBook standard. Thus, this
publishing company claim to have control over what is and is not allowable in
documentation that uses DocBook. I personally don't much like their standard
because I see it as overly complex and far too heavy for the things I need to
document, doubly so for embedded documentation. However, I don't have the freedom
to modify this thing to suit my own uses.

> > to be rude but
> > the texinfo format has some nice things about it, one of 
> > which is that you
> > can learn it in an hour using only free-software tools and 
> > free-software
> > documentation. OK, it doesn't support a lot of fancy features 
> > but what it does
> > it does well, and it does enough for my documentation needs.
> > 
> 
> It's not really a question of whether texinfo is nice or not.  I happen to
> like using the emacs help system, so I want the doc to end up in that form,
> but the original should be maintained in the format most conducive to
> freedom.  Look at the world: it's already full of tools designed
> specifically to manipulate XML, many of which are free, many of which are
> easy to use, and many more are on the way.  How many tools are available
> specifically designed to handle texinfo?  XML, for these purely practical
> reasons, liberates the data from its format; texinfo, today, must be
> considered a limiting form.

Hmmm, I find this questionable. I haven't chased down every texinfo tool
but I know there are a bunch of them. The XML tools are still pretty new and
mostly fall into the category of ``many more on the way''. If the argument
comes to what has proven support right now then texinfo wins easily. If we
are guessing what will have more support a year or two from now then maybe
XML will have more tools, it is hard to say.

Aynway, the issue of how many tools are available is kind of irrelevant
because what really matters is whether there are ENOUGH tools available to
do the job (and what is the qality of those tools). Having more than enough
to do the job at hand is actually worse than having just enough.

> > >  and I'll bet it wouldn't be
> > > too hard to use docbook tags in docstrings in such a way 
> > that they could be
> > > easily transformed to texinfo syntax.
> > 
> > I bet it wouldn't be too hard to transfer backwards too <shrug>.
> 
> Depends on how extensively marked up the doc is.  If we force people to use
> texinfo, we limit the freedom they have to add intelligence to the markup.

You will have to explain this to me in more detail, I don't understand
``add intelligence'' to the markup.

Texinfo supports the basic tree of sections and subsections. It supports most
simple ways of laying out text: paragraphs, lists, points, simple tables.
It knows about keywords and indexes and navigation (including forwards,
backwards, up, down, cross-reference). It also knows a few classes of text
such as for keywords, headings, etc. so that the printed manual is more readable.

I'll agree that there are a lot of other things you COULD do, like complex
nested tables, diagrams, animations, special fonts, flow-around paragraphs,
shaped paragraphs, lettering that follows a curved baseline, pages that look
folded or torn in one corner, use your imagination here... Some of these things
may even be useful, a lot of them probably never will be used, none of them
are actually necessary and all of them are complex to learn and potentially
confusing to anyone who comes along later to make a quick fix.

> That's a real contribution that should not be treated lightly.  You never
> know when somebody non-technical will be smitten by Guile and decide to
> fancy-up the documentation *semantically*.

Can you give an example of this?

>  Actually, the same goes for the
> stylesheet - with a standard free data format, anybody can come along and
> contribute a new, more powerful or beautiful stylesheet.

They can in texinfo too since none of its markup explicitly defines what
the output must look like. They may have to fiddle the texinfo source,
or possibly just tweak the TeX macro definitions that it uses. However,
what usually happens is that people get bored tweaking the fonts and the
line spacing so they figure it is more exciting to introduce more tags.
Then you get documentation peppered with alien tags that only work on just
the right reader (or in the XML case, they only work with just the right
stylesheet).

This sort of process is OK, and in some ways quite natural since it allows
the standard to evolve. However, the history of TeX, latex, and texinfo has
already been through a bit of this and what's there is pretty good for most
jobs. You will never get something that suites everybody, nor should you
try to do so.

> Right, my point was simply that documentation can be placed anywhere in the
> file.  And no, it's not that hard to document source code in Docbook -
> that's what it was designed for.

Same with texinfo, I just happen to think that the texinfo design was better
and more elegant than the DocBook design. You don't use @ very much when coding
either scheme or C (yes I know, in scheme you can use it all the time if you
like but no one does) while you do use < and > quite a lot in both languages.

	- Tel