[Doc-SIG] Evolution of library documentation

[Tony J Ibbs (Tibs)]

Edward D. Loper wrote:
> > (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).
>
> I don't see why it has to be a difficult issue, but hopefully someone
> will explain it to me. :)  But I disagree that the "true ST" approach
> is to say "borderline case - punt it."  I think that's the approach
> of most *current implementations* of ST, not of ST itself.  If ST is
> to become accepted and useful, we *do* need to define
> borderline cases,
> or at least make them explicitly undefined.  It really sucks to try
> to use a language/markup that keeps changing under your feet, and is
> inconsistant between tools. :)

I *think* we're talking at slightly different angles, and actually
agreeing. By "punt it" I mean "defer providing *any way at all* of doing
this thing (that is, specifically, making a single quote character
literal, which *is* the problem), on the grounds that *in practice* it
may be that noone actually needs it". And that is a very ST way of doing
it.

> But I do agree that ST is complex enough.  (btw, why do we need
> 3 different unordered list bullets?  That seemed like enormous
> overkill to me, and getting rid of 'o' as a bullet would solve
> some problems with foreign languages..  Any chance that we could
> just standardize on *either* '*' or '-'?  I guess the STNG people
> won't like that though...)

Two reasons, I expect. First, it is useful for people reading the ST
text itself to be able to use multiple bullets::

	* first item
	  - second item

may be easier to read than::

	* first item
	  * second item

particularly when lists get complex. This is certainly something that
most document presentation tools will do for you. And secondly (less
importantly) the bullet style *might* be used as a hint to the
renderer/formatter of what the user wants to see. But the first is the
"real" reason, I think.

(just keep remembering that ST<whatever> is meant to be read "bare", as
well as post-processed and formatted.)

> I think of arguments as values you give a function, and parameters
> as the slots to receive them.  But I mainly chose "parameters" to
> be consistant with javadoc etc.  Doesn't really matter to me what
> we call it.

Ah - "Arguments" was suggested some while back, that's all - otherwise I
don't much care either.

> > >   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.
>
> As I argued in a previous email, I really think it should be
> description
> list items, but I'll wait for you to argue your case.. :)

I did a bit elsewhere, but it's mostly in the archives, I'm afraid, and
it wasn't actually my case at all. But there was a consensus that this
worked well with a colon, and that it made sense as a way of introducing
"XML" structures.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Well we're safe now....thank God we're in a bowling alley.
- Big Bob (J.T. Walsh) in "Pleasantville"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)