Am 30.07.2005 um 12:34 schrieb Stephen Deasey:
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.
This kind of layout is also possible to achieve, but I deliberately
avoided it because I find it extemely difficult to follow if you
have about 20 calls decribed in one page.
We can emit arg definitions a'la Tcl-man in the SYNOPSIS section,
this is no big deal.
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..?
You are not, but getting this done this way would mean even more
chages in the way how text is parsed. The doctools maintain some
state between passes and you have to fiddle with this, which I
really wanted to avoid. I already had to make changes to this state
by introducing the ccall formatter... Less changes = better.
I believe with some tweaks on the ccall systax we can get what
we want and avoid too much modifications. I will take some of the
ideas from here and give it another round. Lets see if that'll
be more appealing.
Zoran
