This is the mail archive of the guile@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: generating a manual from annotations in source code


>     Marko> If we are talking about a reference manual describing the
>     Marko> way the implementation works, as I think we are, I suggest
>     Marko> to borrow from Haskells literate style.
> 
> We are not describing how the implementation works.  We are describing 
> the various APIs and how the programmer should use them.

Well, be careful --- this discussion has drifted.

We started out discussing how to do docstrings right.

We then started talking about generating real manuals from docstrings.

Then there's also a thread about documenting Guile itself, and the
Guile manual.  Which, by the way, I have no interest in generating
from docstrings, but I don't think that means that the idea is not
useful or worth implementing in Guile for other programs to use.

I think they're all possibly helpful discussions, but posters should
be clear about which one they're trying to participate in.