#241 allow <xref> and <linkend> in <type>

v5.1
closed-works-for-me
nobody
None
5
2007-11-07
2007-08-21
No

Hi,
documenting C++ functions it's very nice to be able to provide a link to the parameter types of a <methodsynopsis>; e.g. for function

int test(myClass instance)

it would be nice to write in docbook:

<methodsynopsis language="cpp">
<type>int</type>
<methodname>test</methodname>
<methodparam>
<type>
<link linkend="myClass">myClass</link>
</type>
<parameter>myClass</parameter>
</methodparam>
</methodsynopsis>

but currently one is forced, if he really wants to create the link, to write:

<methodsynopsis language="cpp">
<type>int</type>
<methodname>test</methodname>
<methodparam>
<type>
<replaceable>
<link linkend="myClass">myClass</link>
</replaceable>
</type>
<parameter>myClass</parameter>
</methodparam>
</methodsynopsis>

i.e. wrap the <link> inside <replaceable>.

Linking parameter types incredibly helps readbility of reference documentation; example (test) page:

http://mathdev.sourceforge.net/wxDocTests/html/wxstring.html#wxstring.empty

Discussion

  • Norman Walsh

    Norman Walsh - 2007-08-29

    Logged In: YES
    user_id=81663
    Originator: NO

    In DocBook V5, you simply write:

    <type linkend="myClass">myClass</type>

    Or, perhaps better still, adjust your stylesheets so that they automatically make links out of types (and warn you if there's a type that doesn't have a link).

    In any event, I believe this issue has been addressed in DocBook V5.

     
  • Norman Walsh

    Norman Walsh - 2007-09-27
    • milestone: --> v5.1
     
  • Norman Walsh

    Norman Walsh - 2007-11-07
    • status: open --> open-works-for-me
     
  • Norman Walsh

    Norman Walsh - 2007-11-07
    • status: open-works-for-me --> closed-works-for-me
     

Log in to post a comment.