This is the mail archive of the guile@sourceware.cygnus.com mailing list for the Guile project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

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


> The only issue I can see is with having parenthesis (for those of us
> always putting in little parentical comments like this one), but I
> think I could live with having to escape parenthesis \(might break me
> of the habit, tho I doubt it ;)\). It should be fairly simply to turn
> those into a form that either docbook or texinfo could use, and we
> don't have to deal with the much more difficult task of translating
> one full markup language to another.

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:

| 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.

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?

	- Tel



Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]