1<refentry id="{@id}"> 2 <refnamediv> 3 <refname>inline {@}id}</refname> 4 <refpurpose>Used to control XML tutorial ids in refsects</refpurpose> 5 </refnamediv> 6 <refsynopsisdiv> 7 <refsynopsisdivinfo> 8 <author> 9 Gregory Beaver 10 <authorblurb>Tag Documentation written by {@link mailto:cellog@php.net cellog@php.net}</authorblurb> 11 </author> 12 <copyright>Copyright 2002, Gregory Beaver</copyright> 13 <releaseinfo>phpDocumentor 1.2+</releaseinfo> 14 </refsynopsisdivinfo> 15 <cmdsynopsis> 16 <command>{@}id</command> 17 <arg choice="opt"><option>sectionname</option> 18 </arg> 19 <command>}</command> 20 </cmdsynopsis> 21 </refsynopsisdiv> 22 <refsect1 id="{@id description}"> 23 <title>Description</title> 24 <para>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 <![CDATA[<refsect1 id="{@}id idname}">]]> in the tutorial (tutorialname.pkg/tutorialname.cls/tutorialname.proc) to do this.</para> 25 <para>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.</para> 26 <caution>The sectionname may only consist of <emphasis>lower-case</emphasis> letters, numbers, and hyphens "-." No other characters are allowed</caution> 27 </refsect1> 28 <refsect1 id="{@id example}"> 29 <para>Here is an example of how {@}id} must be used</para> 30 <para> 31 <programlisting role="tutorial"> 32 <![CDATA[ 33<refentry id="{@}id}"> 34 <refnamediv> 35 <refname>Main Title</refname> 36 <refpurpose>Description of tutorial</refpurpose> 37 </refnamediv> 38 <refsynopsisdiv> 39 <refsynopsisdivinfo> 40 <author> 41 Gregory Beaver 42 </author> 43 <copyright>Copyright 2002, Gregory Beaver</copyright> 44 </refsynopsisdivinfo> 45 </refsynopsisdiv> 46 <refsect1 id="{@}id section}"> 47 <title>First Section Title</title> 48 <para> 49 Note that the id parameter must be within quotes 50 and there must be no whitespace on either side. 51 id=" {@}id section}" will break the id parsing 52 </para> 53 <para> 54 This section's name is 55 "packagesubpackagetutorial.ext.section" by default. 56 The HTML/CHM converters name it "section," the XML 57 converter names it "package.subpackage.tutorial-ext.section" 58 </para> 59 <refsect2 id="{@}id subsection}"> 60 <title>Subsection Title</title> 61 <para> 62 This section inherit's the refsect1's id, and is named 63 "packagesubpackagetutorial.ext.section.subsection" or 64 "section.subsection" for HTML/CHM, and 65 "package.subpackage.tutorial-ext.section.subsection" in XML 66 </para> 67 </refsect2> 68 </refsect1> 69</refentry> 70 ]]> 71 </programlisting> 72 73 </para> 74 </refsect1> 75</refentry>