Re: [naviserver-devel] Doc with doctools

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

On 7/27/05, Zoran Vasiljevic <zv...@ar...> wrote:
> Hi,
>=20
> Before I spend more time, just want to give you some
> idea about it. Please download those:
>=20
>     http://www.archiware.com/www/downloads/Ns_ConnHeaders.man


The following two have the same contents:


>     http://www.archiware.com/www/downloads/Ns_ConnHeaders.3
>     http://www.archiware.com/www/downloads/man.macros
>=20
> and use:
>=20
>     nroff -man Ns_ConnHeaders.3 | more
>=20
> to look at it.
>=20
> The ".man" is the source file I used. Out of this file
> we can make wiki, html, nroff etc pp formats with doctools.
>=20
> I have patched the doctools to include new formatting
> command "ccall" which stands for "C-call" and is a
> companion to "call" which formats Tcl ccommands.
>=20
> I did the nroff formatter first. Once we settle on this
> one, I will update the rest of formatters, eventually
> producting a private version of doctools for our needs.
> We can post changes to tcllib folks so they can include
> this in the standard distro if they like.
>=20
> While doing those changes, I now have much better insight
> how doctools are working and I can produce now just about
> any layout you'd like.
>=20
> Lets hear your feedback.
>=20
> Zoran


[ccall [type int] Ns_ConnLocationAppend [type Ns_Conn] [arg *connPtr]
[type Ns_DString] [arg dest]]

A C-call always has a name, always returns something (even if it's
just void), all args are typed and named, etc., and a lot of that can
be inferred from position and so on.  But in the above,  the doc
writer must redundantly specify [type Ns_Conn] [arg *connPtr].

Couldn't the macro ccall just handle a lot of this transparently?=20
Something like:

[ccall int Ns_ConnLocationAppend {
    {Ns_Conn *connPtr}
    {Ns_DString *dest}
} {
    Describe me here...
}]