Tk Library Source Code

The library seems to be designed for documenting 
packages, but is missing something for doing man pages 
of individual commands. Or maybe I don't quite 
understand how it works. Specifically, it appears that 
the only way to get something into the automatically 
generated SYNOPSIS section is to first put it in a 
[call] statement inside a definition list. Anyone know 
if that is a true statement?

When I tried using the package to write a man page for 
a single command, I found this undesireable. I want a 
SYNOPSIS section, but I don't want to have to put the 
synopsis as an element in a definition list -- that 
just doesn't fit the way I want to document the 
command. The document would end up with the synopsis 
twice -- once wherever I put it and once in the 
SYNOPSIS section. 

What I propose is a new command, [usage], which lets 
one define a usage statement. The difference between 
this and [call] is that [usage] wouldn't cause 
anything to be generated as a direct result of the 
command. Instead, it just stores the string for the 
SYNOPSIS section. Thus, it could appear anywhere in 
the source, though typically it would appear at the 
top.

I've attached a patch file that adds this new command. 
Use at your own risk. This adds a "usage" command to 
each of the formats (fmt.html, fmt.tmml, etc) and 
updates mpexpand to know about the new command. I 
haven't verified that the latex and tmml versions 
generate correct output, but they should. The commands 
are clones of the call proc, but return an empty 
string rather than a formatted string.

FWIW, here's how I'm using it in my man page right now:

[manpage_begin fontdialog n 1.0]
[moddesc   {Dialogs}]
[titledesc {A dialog for defining a font 
specification}]
[usage [cmd "package require Tk 8.2"]]
[usage [cmd "package require ::dialog::fontdialog"]]
[usage [cmd ::dialog::fontdialog::fontdialog] \
       [opt "-applycommand [arg script]"] \
       [opt "-fixed [arg boolean]"] \
       [opt "-font [arg fontDescription]"] \
       [opt "-sizes [arg list]"] \
       [opt "-title [arg string]"] \
       [opt "-variable [arg boolean]"] \
]
[description]
...

Logged In: YES 
user_id=75003

Patch committed.

Logged In: YES 
user_id=75003

Note that
    [usage [cmd "package require Tk 8.2"]]
is better written as
    [require Tk 8.2]

Otherwise the patch accepted, and extended
to cover the formats TMML ad NULL as well.

File Added - 19065: doctools.patch