Menu
▾
▴
#961 Documenting related commands on one man page
It's difficult to write a man page about multiple commands. Here's an example:
http://naviserver.sourceforge.net/n/naviserver/files/ns_memoize.html
http://naviserver.cvs.sourceforge.net/naviserver/naviserver/doc/src/mann/ns_memoize.man?view=markup
- Each command is given a numbered anchor, so to link to ns_memoize_flush the link is: .../ns_memoize.html#2. This will change if commands are added, removed or reordered.
- If you use the [cmd ...] markup, the name of the command becomes a link but only if it has the same name as the page current page.
In the example above, ns_memoize is a link to itself. However ns_memoize_flush is not a link at all. Neither is ns_cache_eval, which is documented on another page (named ns_cache).
What would be useful is if each mention of a command would link to it's definition, i.e. .../ns_cache.html#ns_cache_eval
- Some commands are in the form of subcommands, like Tcl's 'string'. It would be useful to be able to refer to a subcommand like: [cmd "string is"] and have it parse the space and link to the correct place.
Logged In: YES
user_id=75003
Originator: NO
Can you tell me which revision of doctools and html backend you are using ? In my version the code not only generates numbered <a name=""> anchors at the command locations, but proper <a href=""> links to them in the Synopsis too.
Or are you trying to link to specific commands from outside of the manpage, i.e. from other manpages in the same set ?
That is actually something we know we have trouble with in general. You can link to a complete manpage X from another page Y, by marking up the title of X in Y as a [term], however there is no support at all to directly link to deeper structures, like sections, let alone command definitions.
There are some extremely rough ideas floating around regarding a TeX like use of 'label' and 'reference' markup, nothing concrete however, and based on your description also not really what you are asking for with regards to commands.
The links you see are automatically generated purely based on strings ... We might be able to extend the set of terms which can be linked too so that the other commands also refer to the containing manpage ... I have to think about that a bit more ...
Logged In: YES
user_id=87254
Originator: YES
I'm using tcllib1.9 (from a couple months ago, IIRC), which I've installed on sourceforge here (directories are executable, should be browsable):
/home/users/s/sd/sdeasey/local
But yes, I'm trying to link to a specific command (1 of n) on one page, from another page.
If you use [cmd ...] it does actually create a link, you don't have to use [term ...]. So the linking machinery is there. The problem is that on the target page the HTML markup looks like this:
<dt><a name="1"><b class='cmd'>ns_sls set</b> <i class='arg'>key</i> <i class='arg'>value</i></a><dd>
(from: http://naviserver.sourceforge.net/n/naviserver/files/ns_sls.html )
The anchor name is "1". The anchor name should be "ns_sls".
Secondly, which commands are defined in which pages needs to be added to the .idx, .xref or .toc (whichever is most appropriate), as the documentation is being parsed, just like which keywords appear in which pages.
It seems like most of what's needed is already there. I don't think there needs to be an extra linking mechanism (label, reference), at least, not for this purpose.
I think it's also important to use the expected string names as anchors, rather than opaque numbers, to allow links to be created from external works, such as wikis. It seems unlikely that there would need to be multiple definitions of a single command on one page, and in such a case, the first one will be linked to.
I noticed that the linking seems to be case insensitive, at least for terms. This is a problem for commands and C library functions (which are case sensitive anyway). For example, naviserver has the Tcl command ns_log(n) and the library function Ns_Log(3). It would be nice to be able to refer to one from the other.