--- Jesper Harder <harder@ifa.au.dk> wrote:
> C Y <smustudent1@yahoo.com> writes:
>
> > What I had in mind (again this is just me waving my hands) is to
> > document each function/variable at a local level, generate chapters
> > from that, and then at the beginning write the bird's eye overview
> of
> > how the pieces fit together.
>
> OK. One way to do that would be to insert a magic comment in the
> manual,
> where you want a docstring to appear, and then pre-process the texi
> source to get the docstring inserted.
>
> E.g. you could write
>
> @c TEXI DOCSTRING MAGIC: context
>
> to get the docstring for 'context' wrapped up in proper Texinfo
> markup.
> Take a look at 'texi-docstring-magic.el' which does exactly this for
> Emacs Lisp:
>
>
<http://www.proofgeneral.org/ProofGeneral-latest/generic/texi-docstring-magic.el>;
That sounds very good.
> Sure. They can be as long as you like. In carefully documented code
> they can be quite long. Here's a random example:
>
> <http://www.norvig.com/java-lisp.html>;
Ah, I expressed myself badly. I didn't mean just a really long string,
I mean a statement with linebreaks in it which will be passed through
if the docstring is called. I.e.:
This is line one.
This is line two.
as opposed to
This is line one. This is line two.
> > As for chapter layout, my idea works something like the following:
> > define a local variable in each function/variable/etc. called topic
> > or chapter or something, and assign it a value like integration,
> > simplification, general, etc - something that makes sense.
>
> This means that we will have to do the classification one way or
> another. I think it's simpler to do it in the manual rather than in
> the source files.
That makes sense.
> Do you know the Mathematica manual? It has an appendix with a
> listing of all built-in Mathematica objects with a short explanation
> of each item. That could be a different way of using docstrings.
Um. How is that different from what we've been discussing?
CY
__________________________________________________
Do you Yahoo!?
Yahoo! Mail Plus - Powerful. Affordable. Sign up now.
http://mailplus.yahoo.com