Adding our own things to docbook is not a good idea, as it will need more modifications to our stylesheets. Also, it will make it less flexible in cases like:
<para>
See also: <functiono>foo</function> for an example and <function>foo2</function> for more information on blah.
</para>
I think we just should set a standard if we;'re going to add a : or not (I don't really care, as long as it is consistent).
As I emphasized before, PHP-GTK docs uses a modified version of docbook without problems. Adding customizations to the XSL sheets is not a problem. As I have written in the agenda, I think that if we can move to "manageable" output generation methods [eg. XSLT or livedocs] then we can make this move.
Why our own tag for see also would be better?
- 98% [approx] of see alsos are not that exoticaly worded, as you
have done in your example
- with our own tags, no translation would be needed for this part
- there will be an ability to automatically recognize see also parts,
which can seriously help in presentation, and automatic discovery
[eg. we can check what parts are better connected in the manual,
and what needs more attention]
OK I admit that the automatic discovery is a weak point, as our own see alsos are not that big plus for this...
An example:
<seelist>
<function>mysql_close</function>
<function>mysql_fetch_array</function>
<function>mysql_fetch_row</function>
<function>mysql_fetch_assoc</function>
</seelist>
That would render:
| See also mysql_close, mysql_fetch_array, mysql_fetch_row,
| and mysql_fetch_assoc.
Note, that "See also", the commas and the "and" is autogenerated.
This without translation will become:
| Lásd még mysql_close, mysql_fetch_array, mysql_fetch_row
| és mysql_fetch_assoc.
For Hungarian. Note that we don't use a comma before the last "and".
That still enables you to use a <para> with more explanation if you want to, instead of adding a <seelist>. Additionaly this will be very good for several output formats. CHM for example can place the see also links on top of the page in a dropdown menu, as it is in most windows programming help manuals.
Note that I used the <seelist> tag example, because <seealso> is used in DocBook, just for a completely different purpose.
Goba