[Doc-SIG] Evolution of library documentation
Tony J Ibbs (Tibs)
tony@lsl.co.uk
Wed, 14 Mar 2001 10:57:11 -0000
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.)