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

[Greg Harvey <Greg dot Harvey at thezone dot net>]

Telford Tendys <telford@eng.uts.edu.au> writes:
> 
> There are quite a few cases where parens turn up in documentation.
> Remeber that we are documenting C too so you get typecasts and such
> being explained. Then there are the  parentical comments you mention
> above and there is also the chance that someone would actually like
> to mention a scheme expression in their comment.
> 
> There is one major advantage of parens which is that all the cases
> I can think of would involve BALANCED pairs of parenthesis. For example:

Yep; a better convention would probably be either the @foo{...}, or
possibly {foo ...}, which isn't so odd; a lot of guile's source files
already separate sections implementing different things using {} (I'm
guessing that if an editor balances (), it'll balance {}, too). Those
are quite rare in most writing, but could be seen to be too
texinfo-ish if we're trying to be neutral ;)

> | The only issue I can see is with having parenthesis (comment: for
> | those of us always putting in little parentical comments like
> | this one), but I think I could live with ...
> 
> You might also want to explain that sometimes an item of type
> SCM might reference a smob using (C-exp: ( table_T *)SCM_CDR( x ))
> which requires a typecast to a suitable pointer. Also notice that
> C insists on balanced parens so any valid C expression can be quoted
> in this manner (comment: might need smarts for strings but it is possible).
> 
> (list:
>    (item: Firstly, this type of markup would be easy for schemers
>           to read and work with.)
>    (item: Secondly, a C programmer would come to grips with it within
>           a short space of time, providing the number of tags was minimal.)
>    (item: Unfortunately, the third point is that we have no tools to cope
>           with this so it would require new tools build from scratch.
>           This is a big setback (comment: even though the complexity of such tools
>           would not be too great).))
> 
> Even so, I still like the simplicity of texinfo.

Yep, but I can see the argument for wanting to have a fuller markup
language for a full manual (though I personally wouldn't choose
docbook; I was very nearly physically ill when I saw the sheer volume
of tags that go into a typical docbook document).

> Escapes are pretty horrible, I really don't like escapes at all.
> Note that the quote above is wrong because the smilee is not escaped,
> I presume this was a deliberate error in order to point out a
> non-balanced use of parenthesis. Putting a ``no smilee'' rule on
> docstrings doesn't sound too fierce does it?

No, that's a good idea :). Smilies are a very informal; the docs
should at least be semi-formal (i.e. `blows goats' not used all that
often; punctuation).
-- 
gregh: just messing with my sig for the sheer hell of it