Re: [naviserver-devel] Doc with doctools

[Zoran V. <zv...@ar...>]

Am 30.07.2005 um 11:50 schrieb Stephen Deasey:
>
> Great.  Are the macros expanded recursively?  Can ccal output the type
> declarations for the benefit of indexes etc.?  Will we be able to
> document the Tcl cmds as easily?

I will first have to examine the TOC and index parts before I can
say something about that.

Tcl commands are already handled by doctools with ease (doctools
was designed arround documenting Tcl commands primarily).

>
> Oh, and can the index be categorized (used to live here:
> http://aolserver.com/40drafts/ do you remember?) rather than just fill
> the screen, as the Tcl API docs do:
> http://www.tcl.tk/man/tcl8.4/TclLib/contents.htm ?

Good question. Again, the TOC/Index parts I have not scratched
yet. But I assume we can make just about anything once we understand
the guts of it. I've made efforts to understand the formatting engine
first to be able to get an idea how we could expand it to document
C-calls nicely. Once this is done (and I believe we're very close to
it), I will take the rest under examination.

>
> Also, is it possible to do things like mark a function deprecated, and
> when, so that is doesn't show up in the normal doc index but an index
> of deprecated functions is created, grouped by version number.
>
> How do we specify CONST, and can we document args as in, out or inout?
>  How about NONNULL args, varargs and format strings?

Uhuhuhuhu... args in/out is already handled. You can group args  
definitions
more/less like Tcl is doing it in their docs (look "man  
Tcl_SetObjResult"
for example).

For the other, dunno. We'll have to see...

>
> I'm just wondering how flexible this thing is.  My mental model is
> that it just calls [subst] on the man page source, so things like
> literal text would seem hard to hide or move around...
>

It is pretty flexible, once you understand how it works. As it is
all in plain Tcl and in just couple of relatively short files, you
can pretty quickly get an idea how to change it, when needed.
What I want to minimize is the scope of changes and use the thing
more/less as-is in order to put a lower acceptance barrier on the
doctools maintainer(s). If we manage to get at least "ccall" in
and supprted *by them* it will be a great thing.

Zoran