Re: [naviserver-devel] Doc with doctools

[Stephen D. <sd...@gm...>]

On 7/30/05, Zoran Vasiljevic <zv...@ar...> wrote:
>=20
> 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?
>=20
> I will first have to examine the TOC and index parts before I can
> say something about that.
>=20
> Tcl commands are already handled by doctools with ease (doctools
> was designed arround documenting Tcl commands primarily).


Yeah, I was looking at your thread docs:

[call [cmd thread::create] [opt -joinable] [opt -preserved] [opt script]]

Same deal as with the ccall, all the [opt] stuff seems redundant.  For
documenting Tcl cmds, it would seem possible to use *exactly* the same
syntax as one would to define a proc:

call name -opt -- arg {arg2 def} args


> >
> > 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 ?
>=20
> 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.
>=20
> >
> > 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?
>=20
> 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).
>=20
> For the other, dunno. We'll have to see...
>=20
> >
> > 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...
> >
>=20
> 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.


Agree.  Would be best to get any changes accepted upstream.

Also, no need to go nuts up front, we can add things later.

I just wonder if the system is too simple.  In your example man page
you followed each ccall definition with a description.  In the Tcl man
pages the definitions are grouped at the top, then the args are
described, then there's some prose text describing the functions.

If the source looked like:

ccall int FooFunc {{int arg}} {
    p { description... }
    p { more... }
}

I could see how a tree was being built up, and how formatting
functions could walk it and output in any order, and use the data to
synthesize lists and tables etc.  But with the simple macros embedded
in literal text, it looks like the formatters will be limited to the
order in which things are presented in the source man page.  Or am I
way off here..?