PHP Documentation - [PHP-DOC] What's the difference in these tags?

Author

[PHP-DOC] What's the difference in these tags?

Richard A. Quadling

2006-10-18, 7:57 am

Hi.

In trying to resolve a bug with aliases
(http://bugs.php.net/bug.php?id=37143), I've come across this
difference.

The XML for ocicancel is ...

<refentry id="function.ocicancel">
<refnamediv>
<refname>ocicancel</refname>
<refpurpose>&Alias; <function>oci_cancel</function></refpurpose>
</refnamediv>

<refsect1 role="description">
&reftitle.description;
<simpara>
&info.function.alias;
<function>oci_cancel</function>.
</simpara>
</refsect1>
</refentry>

The XML for ocicloselob is ...

<refentry id="function.ocicloselob">
<refnamediv>
<refname>ocicloselob</refname>
<refpurpose>&Alias; <xref linkend="function.oci-lob-close"
/></refpurpose>
</refnamediv>

<refsect1 role="description">
&reftitle.description;
<simpara>
&info.function.alias;
<xref linkend="function.oci-lob-close" />.
</simpara>
</refsect1>
</refentry>

The main difference is <function> vs <xref>

If you take a look at http://www.php.net/manual/en/ref.oci8.php you will
see that the display types for these two aliases are different ...

ocicancel -- Alias of oci_cancel() (This is in bold)
ocicloselob -- Alias of OCI-Lob->close (This is not in bold).

In the standard CHM Manual (and I had to download one to make sure that
my own compilation wasn't the problem ...) this is shown correctly.

In the Extended CHM Manual (and again, I downloaded one), this is NOT
shown correctly.

Instead, it is shown as ...

ocicancel - Alias of oci_cancel
ocicloselob - Alias of

No bold and a missing method. I tried the different skins too. Just in
case THAT was the issue.

I can say that the build for the Extended CHM Help File is not dealing
with these correctly.

I found

<refpurpose>&Alias; <xref linkend="function.

in only 15 files. They are all in the OCI section (Oracle Functions).

I changed the <xref> to <function> and build my own manual and it all
seems OK so far (passed make test and make test_xml and is building
right now!)

(Twiddle thumbs).

Ah. Just checked the output of make chm_xsl and the two files are
different ...

<a href="function.oci-cancel.html">oci_cancel()</a>

And

function.oci-lob-close()

No anchor for the one that is an alias of a method.

Any ideas?

I've attached the patch. I'd like to fix this, but I don't really know
what is going on to get from .XML to .HTML with chm_xsl.

Regards,

Richard Quadling

Philip Olson

2006-10-18, 6:58 pm

Hello Richard!

You always have the most thorough emails! ;-)

Use <function>, and feel free to (a) get a php.net account and (b)
commit the patch :)

Regards,
Philip

http://doc.php.net/php/dochowto/

On Oct 18, 2006, at 4:25 AM, Richard A. Quadling wrote:

> Hi.
>
> In trying to resolve a bug with aliases
> (http://bugs.php.net/bug.php?id=37143), I've come across this
> difference.
>
> The XML for ocicancel is ...
>
> <refentry id="function.ocicancel">
> <refnamediv>
> <refname>ocicancel</refname>
> <refpurpose>&Alias; <function>oci_cancel</function></refpurpose>
> </refnamediv>
>
> <refsect1 role="description">
> &reftitle.description;
> <simpara>
> &info.function.alias;
> <function>oci_cancel</function>.
> </simpara>
> </refsect1>
> </refentry>
>
> The XML for ocicloselob is ...
>
> <refentry id="function.ocicloselob">
> <refnamediv>
> <refname>ocicloselob</refname>
> <refpurpose>&Alias; <xref linkend="function.oci-lob-close"
> /></refpurpose>
> </refnamediv>
>
> <refsect1 role="description">
> &reftitle.description;
> <simpara>
> &info.function.alias;
> <xref linkend="function.oci-lob-close" />.
> </simpara>
> </refsect1>
> </refentry>
>
> The main difference is <function> vs <xref>
>
> If you take a look at http://www.php.net/manual/en/ref.oci8.php you
> will
> see that the display types for these two aliases are different ...
>
> ocicancel -- Alias of oci_cancel() (This is in bold)
> ocicloselob -- Alias of OCI-Lob->close (This is not in bold).
>
> In the standard CHM Manual (and I had to download one to make sure
> that
> my own compilation wasn't the problem ...) this is shown correctly.
>
> In the Extended CHM Manual (and again, I downloaded one), this is NOT
> shown correctly.
>
> Instead, it is shown as ...
>
> ocicancel - Alias of oci_cancel
> ocicloselob - Alias of
>
> No bold and a missing method. I tried the different skins too. Just in
> case THAT was the issue.
>
> I can say that the build for the Extended CHM Help File is not dealing
> with these correctly.
>
>
> I found
>
> <refpurpose>&Alias; <xref linkend="function.
>
> in only 15 files. They are all in the OCI section (Oracle Functions).
>
> I changed the <xref> to <function> and build my own manual and it all
> seems OK so far (passed make test and make test_xml and is building
> right now!)
>
> (Twiddle thumbs).
>
> Ah. Just checked the output of make chm_xsl and the two files are
> different ...
>
> <a href="function.oci-cancel.html"> class="function">oci_cancel()</a>
>
> And
>
> function.oci-lob-close()
>
> No anchor for the one that is an alias of a method.
>
>
> Any ideas?
>
> I've attached the patch. I'd like to fix this, but I don't really know
> what is going on to get from .XML to .HTML with chm_xsl.
>
> Regards,
>
> Richard Quadling
>
> <oci8.diff.txt>

Richard A. Quadling

2006-10-19, 3:59 am

Hi.

It actually didn't work.

I used make chm_xsl and examined the .html files before they are
processed from phpdoc/htmlhelp/html into phpdoc/htmlhelp/htmlout.

So this suggests that one of the xsl files is not right OR there reading
of the function list is in some way wrong.

The function is wrapped in ... but not <a>. This suggests that
the function cannot be found to link to and only the fact that the XML
file says it is a function gets the bold wrapper. Something I'm not sure
about is the case sensitivity of the xsl:value-of function.

I'm going to try that as it SEEMS that the only aliases missing have a
different case, but only when using the Extended CHM and not the normal
CHM. Argh!

So, this is still a fix in progress.

And I don't even use the OCI, but I reported the bug so I should at
least try and fix it!

And thank you for your support on getting an account. I probably will
now.

And thank you for your comments on my emails.

I'm just as wordy IRL.

Richard.

> -----Original Message-----
> From: Philip Olson [mailto:philip@roshambo.org]=20
> Sent: 18 October 2006 16:31
> To: Richard A. Quadling
> Subject: Re: [PHP-DOC] What's the difference in these tags?
>=20
>=20
> You always have the most thorough emails... ;-)
>=20
> Use <function>, feel free to (a) get a php.net account and=20
> (b) commit the patch :)
>=20
> Regards,
> Philip
>=20
> http://doc.php.net/php/dochowto/
>=20
>=20
> On Oct 18, 2006, at 4:25 AM, Richard A. Quadling wrote:
>=20
> this is NOT=20
> too. Just in=20
> not dealing=20
> Functions).
> and it all=20
> really know=20
>=20
>=20

Richard A. Quadling

2006-10-19, 3:59 am

Aha!

The file-entities.ent has the function names in mixed case. I'm trying
the build with the alias' xml files having the same case in the
<function> tag as in the file-entities.ent.

Watch this space!

Richard.=20

> -----Original Message-----
> From: Richard A. Quadling [mailto:RichardQ@bandvulc.co.uk]=20
> Sent: 19 October 2006 08:35
> To: Philip Olson; phpdoc@lists.php.net
> Subject: RE: [PHP-DOC] What's the difference in these tags?
>=20
> Hi.
>=20
> It actually didn't work.
>=20
> I used make chm_xsl and examined the .html files before they=20
> are processed from phpdoc/htmlhelp/html into phpdoc/htmlhelp/htmlout.
>=20
> So this suggests that one of the xsl files is not right OR=20
> there reading of the function list is in some way wrong.
>=20
> The function is wrapped in ... but not <a>. This=20
> suggests that the function cannot be found to link to and=20
> only the fact that the XML file says it is a function gets=20
> the bold wrapper. Something I'm not sure about is the case=20
> sensitivity of the xsl:value-of function.
>=20
> I'm going to try that as it SEEMS that the only aliases=20
> missing have a different case, but only when using the=20
> Extended CHM and not the normal CHM. Argh!
>=20
>=20
> So, this is still a fix in progress.
>=20
> And I don't even use the OCI, but I reported the bug so I=20
> should at least try and fix it!
>=20
>=20
> And thank you for your support on getting an account. I=20
> probably will now.
>=20
>=20
> And thank you for your comments on my emails.
>=20
> I'm just as wordy IRL.
>=20
> Richard.
>=20
>=20
> http://www.php.net/manual/en/ref.oci8.php you=20
> different=20
> ocicloselob --=20
> make sure=20
> is building=20
>=20

Sponsored Links