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

>>>>> "Perry" == Perry E Metzger <perry@piermont.com> writes:

    Perry> It also seems equally clear that a human organized manual
    Perry> must exist that points people at how to figure out how the
    Perry> parts fit together -- such a manual is either the
    Perry> "programmers guide" or "tutorial" or something similar, but
    Perry> it is not the reference manual. Hopefully, hyperlinks exist
    Perry> from the one to the other (in the online version) to assure
    Perry> that you can find out the exact definition of a function or
    Perry> where it fits in to the wider scheme of things.

 The person writing the docstring will need to remember to put markup
 around things that should become hyperlinks in the viewing tool later
 on.

/*DOX-MARK
 blah blah blah
 See also: @referto{condition-case}
*/

 ... or could that display tool markup be automagicly generated from
 an index?

 See also: for

 Might become: <html> See also: <a href="someplaceelse">for</a> ...

 ... But then:

 <html> I said <a href="someplaceelse">for</a> the third time, don't
 rewrite the factorial function yet again.

 ... and you'd still have to define the point it always links to; I
 guess a glossary.

 I wonder how they made the HyperSpec?