Hi Paul On 9/12/07, Paul Reinheimer <[EMAIL PROTECTED]> wrote: > the framework shows > <title><function>functionname</function> example</title> > <programlisting role="php"> > simplexml shows > <title>Include file example.php with XML string</title> > <programlisting role="php" xml:id="simplexml.examples.movie"> > > > Which one should I be using, there are two questions here, the function tags > surrounding the function name, and the xml:id bit.
If you have a good idea for a more descriptive title, use it. If the best you can find is "Example of functionname usage" I would, for consistency, use "functionname example". The tags surrounding functionname is just markup, the more markup, the better. In this case the <function /> will be converted into the xhtml tag <strong /> because this manpage is the manpage for functionname. <function>someOtherFunctionName</function> would however create a bold link to that particoular function. The xml:id bit is just good practice, not 'a must'. If you add xml:id to the example anchors will be created with that name in the html so you can easily refer to that particular example with "http://php.net/functionname#the-xml-id"; rather than relying on the generated id which will be something like "id235exampl2345235" (and will change if another example will be added somewhere before that example in the manual). The general advantage by throwing xml:id here and there is also the possibility to link to it within the manual (as in, you can add; "see the <link linkend="the-xml-id">is_int example</link> for more examples on what is an integer" or "see <xref linkend="the-xml-id" /> for more examples on what is an integer" > also, please comment on patch attached. One question I ran into while > working > on it, was wether I should be using var_dump() to illustrate the function, > or some > sort of an if structure. var_dump() makes the most sense to me, but it has > the > requirement of understanding what it is.... You have a good point here, but is there an easier way to show the results? is_int() is such a basic function so the example cannot be to "complicated" for the newbies... I don't know.. I would probably have committed var_dump() example without thinking about it, but now that you mention it.. -Hannes
