[Doc-SIG] Evolution of library documentation

[Tony J Ibbs (Tibs)]

Edward D. Loper wrote:
> I think that for the most part, I tend to side with Tibbs on this..

although I think you may have expressed it better...

> Note that that is generally exactly the type of documentation you
> want in a reference manual.  I think that the idea of building
> the reference manuals from docstrings makes a lot of sense.  I do
> *not* think that including tutorials, howtos, big examples with
> explanations, etc. belong in the docstrings.

Well, a reference manual is sometimes at a higher level than what I put
in docstrings. But maybe I should be prefixing more methods with '_'.

> This is pretty much completely a digression, but I figured I'd chime
> in.  Regardless of how easy it is to download CVS or LaTeX, it is
> much easier to learn how to *use* CVS than to learn how to use
> LaTeX.  Given a knowledgable teacher, you can learn everything you
> need to know about CVS in an hour.  I'm not sure anyone ever learns
> everything they need to know about LaTeX. :)

Well, point taken, although *not* given a knowledgable teacher, I found
getting started with CVS to be a non-starter, whereas I got up to speed
with TeX and LaTeX rather fast without any help 15 or 18 years ago (when
it was a lot more difficult).

Maybe it depends on one's mind and interests...

(and I shan't pretend that one ever learns all one needs to know about
LaTeX until one implements bits of it, which *I* certainly haven't
done - personally I prefer to use TeX neat if I want to do my own stuff)

> I think that we should leave the organization of "grander scope"
> documentation to a different project..  (Of course, it's still
> an important project.)

Yes, yes, yes (indeed, I thought that's what was already being done,
quietly in the background, by our Mr Drake)

> I think it might make sense to reserve one character, or maybe 2, for
> advanced markup.  (We would also want to be able to backquote it
> somehow, but we'll leave discussion that for later..).  So,
> for example,
> we could say that '@' is reserved for advanced markup, and then it
> can be used by people who:
>   1. want more advanced features
>   2. are willing to use a "real" markup, which is more "obtrusive"
>      and difficult to read/write.

I'm willing to reserve '@' for later use (the whole issue of how one
quotes things in ST is a difficult one, single quote itself is enough of
a problem. The "true ST" approach, I think, is to say "borderline case -
punt it - we're not that complex", which *may* well be the correct
answer).

BUT whilst I don't mind reserving it, I'll probably oppose using it!
(but allowing you to reserve it postpone the argument, which is a Very
Good Thing, and it gives us a *marker* for having postponed the
argument)

> I think that we should limit how much more complex "basic" ST gets,
> as much as possible..

STpy is almost as complex as I want it to get already - I want to add in
[references] and then feature freeze. Which would have become clear in
the alpha (he whines)

> I agree that it doesn't make sense to make up our own markup
> langauge..
> So maybe reserve (non-backslashed) '<' and '>' and use XML for
> advanced markup?

I don't want to reserce '<' and '>'. If you want to placemark that in
your head, then place hold it as "I'll propose, some time in the
indefinite future, that we markup an XML style entity using something
like, for instance, just an idea::

	@fred ... @/fred

being equivalent to::

	<fred>...</fred>

an we'll sort it our later on". This leaves the heated arguments about
whether we *really* want XML, or DocBook, or what, and whether those
spaces matter, and whether it should *actually* be '@<fred>', until the
future, where they belong. Keeping a marker for them (so we don't forget
to discuss them in the future) is a good thing. Worrying about them now
isn't. (and also, lots of things "fall out in the wash" from things like
ST - one sometimes finds that, later on, one already *has* what one
wanted, anyway).

> Of course, depending on what we decide we need, we may be able to get
> away with much less.  For example, define things like::
>
>   Parameters:
>      p1 -- foo
>      p2 -- bar
>
> To have special meaning in the context of docstrings.

Well, actually it's "Arguments". And the special meaning isn't
*enforced* in the current implementation or documentation, but it may be
in the future (so much to do, so little whatever).

> Any standard
> (STpy-like) ST will just render them as a heading with a list.
> You can also define special forms like::
>
>   author -- Edward Loper
>   version -- 2.71828

That's::

	Author: Edward Loper
	Version: 2.71828

and it doesn't work yet (because '<keyword>:' doesn't yet start a
paragraph) - it may or may not work in the alpha release.

> That takes care of most of the structural-type markup, and still looks
> ok if you just read it, or parse it with non-docstring-specific ST
> tools..

Strangely enough, this was David Ascher's reason for coming up with the
idea. Look in the doc-sig archives around November/December 1999 for
talk about these issues.

> Then you just have to worry about syntax for inline markup.  I don't
> have any great ideas there, other than having a whole class of
> "advanced inline markup" tags like @somethingorother(...)

Given the '@' reserved, we can leave that...

Tibs

(two more to go)


--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)