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
-- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
