inline {@id}

Used to control XML tutorial ids in refsects

Gregory Beaver

Tag Documentation written by cellog@php.net

(phpDocumentor 1.2+)

{@id sectionname }

Description

The {@id} inline tag is used only in tutorials/extended documentation. It is very simply designed to solve the problem of identifying sections for hyperlinking. For instance, in the DocBook Converter, id's are in the format package.packagename[.subpackagename].file[.sectionname], where file is either the classname, function/method name, or summary. In the other Converters, the id is not nearly as restrictive, but this inline tag allows for the potential of future converters that are equally exacting. Use

<refsect1 id="{@id idname}">

in the tutorial (tutorialname.pkg/tutorialname.cls/tutorialname.proc) to do this.

The {@id} tag is context-sensitive, and will pre-pend the id of the current refsect1, refsect2, or refsect3 to any {@id}, allowing further error control.

The sectionname may only consist of lower-case letters, numbers, and hyphens "-." No other characters are allowed

Here is an example of how {@id} must be used

<refentry id="{@id}">
<refnamediv>
<refname>Main Title</refname>
<refpurpose>Description of tutorial</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<author>
Gregory Beaver
</author>
</refsynopsisdivinfo>
</refsynopsisdiv>
<refsect1 id="{@id section}">
<title>First Section Title</title>
<para>
Note that the id parameter must be within quotes
and there must be no whitespace on either side.
id=" {@id section}" will break the id parsing
</para>
<para>
This section's name is
"packagesubpackagetutorial.ext.section" by default.
The HTML/CHM converters name it "section," the XML
converter names it "package.subpackage.tutorial-ext.section"
</para>
<refsect2 id="{@id subsection}">
<title>Subsection Title</title>
<para>
This section inherit's the refsect1's id, and is named
"packagesubpackagetutorial.ext.section.subsection" or
"section.subsection" for HTML/CHM, and
"package.subpackage.tutorial-ext.section.subsection" in XML
</para>
</refsect2>
</refsect1>
</refentry>