This is the mail archive of the
guile@sourceware.cygnus.com
mailing list for the Guile project.
Re: Doc Tasks (was RE: docstrings in Guile!)
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