1. Jeroen Ruigrok van der Werven
  2. tendra

Commits

Jeroen Ruigrok van der Werven  committed 1bf9cdf

Change remaining <a> tags into <link> tags.
Fix up remaining validation errors.

  • Participants
  • Parent commits 21eb996
  • Branches default

Comments (0)

Files changed (1)

File doc/tspec/tspec.xml

View file
  • Ignore whitespace
 
     <corpauthor>The TenDRA Project</corpauthor>
 
-    <author>Jeroen Ruigrok van der Werven</author>
+    <author>
+      <firstname>Jeroen</firstname>
+      <surname>Ruigrok van der Werven</surname>
+    </author>
     <authorinitials>JRvdW</authorinitials>
     <pubdate>2004</pubdate>
 
   </bookinfo>
   
   <chapter>
+    <title>Introduction</title>
+
     <sect1 id="Intro">
       <title>Introduction</title>
   
   </chapter>
   
   <chapter>
+    <title>Overview</title>
+
     <sect1 id="Overview">
       <title>Overview of tspec</title>
   
           case names, for example:
       
           <itemizedlist>
-            <listitem><code>ansi</code> refers to ANSI C (X3.159),</listitem>
+            <listitem>
+              <para><code>ansi</code> refers to ANSI C (X3.159),</para>
+            </listitem>
         
-            <listitem><code>posix</code> refers to POSIX 1003.1,</listitem>
+            <listitem>
+              <para><code>posix</code> refers to POSIX 1003.1,</para>
+            </listitem>
         
-            <listitem><code>xpg3</code> refers to X/Open Portability Guide
-            3.</listitem>
+            <listitem>
+              <para><code>xpg3</code> refers to X/Open Portability Guide
+                3.</para>
+            </listitem>
           </itemizedlist>
         </para>
       
           variable <code>TSPEC_INPUT</code>. Directories may be added to the
           start of the path using the
           <option>-I</option><filename>dir</filename> command-line option (see
-          <a href="#Options">section 2.5</a> for a complete list of
+          <link linkend="Options">section 2.5</link> for a complete list of
           options). The current working directory is always added to the start
           of the path.</para>
       </sect2>
           the include output files, containing the <code>#pragma token</code>
           directives corresponding to the input API, and the source output
           files, which provide a rig for TDF library building (see
-          <a href="#Libraries">section 6.4</a>). These output files and
+          <link linkend="Libraries">section 6.4</link>). These output files and
           directories are built up under two standard output directories - the
           include output directory, <filename>incl_dir</filename> say, and the
           source output directory, <filename>src_dir</filename> say.
       
         <para>The default output file names can be overridden by means of the
           <code>INCLNAME</code> and <code>SOURCENAME</code> file properties
-          described in <a href="#Properties">section 5.4</a>.</para>
+          described in <link linkend="Properties">section 5.4</link>.</para>
       
         <para>By default, <code>tspec</code> only creates an output file if
           the date stamps on all the input files it depends on indicate that
           file if it is needed for TDF library building. If the corresponding
           include output file does not contain any token specifications then
           the source output file is suppressed (see
-          <a href="#Libraries">section 6.4</a>).</para>
+          <link linkend="Libraries">section 6.4</link>).</para>
       </sect2>
 
       <sect2 id="Copyright">
             <listitem>
               <para>The option <option>-C</option><filename>file</filename>
                 specifies the copyright message file (see
-                <a href="#Copyright">section 2.4</a>).</para>
+                <link linkend="Copyright">section 2.4</link>).</para>
             </listitem>
         
             <listitem>
               <para>The option <option>-I</option><filename>dir</filename>
                 adds a directory to the input directory search path (see
-                <a href="#Input">section 2.2</a>).</para>
+                <link linkend="Input">section 2.2</link>).</para>
             </listitem>
         
             <listitem>
               <para>The option <option>-O</option><filename>dir</filename>
                 specifies the include output directory (see
-                <a href="#Output">section 2.3</a>).</para>
+                <link linkend="Output">section 2.3</link>).</para>
             </listitem>
         
             <listitem>
               <para>The option <option>-S</option><filename>dir</filename>
                 specifies the source output directory (see
-                <a href="#Output">section 2.3</a>).</para>
+                <link linkend="Output">section 2.3</link>).</para>
             </listitem>
         
             <listitem>
             <listitem>
               <para>The <option>-i</option> option causes <code>tspec</code>
               to print an index of all the objects in the input files (see
-              <a href= "#Index">section 6.3</a>).</para>
+              <link linkend= "Index">section 6.3</link>).</para>
             </listitem>
         
             <listitem>
             <listitem>
               <para>The <option>-r</option> option causes <code>tspec</code>
               to only produce output for implemented objects, and not used
-              objects (see <a href="#Impl">section 3.2</a>).</para>
+              objects (see <link linkend="Impl">section 3.2</link>).</para>
             </listitem>
         
             <listitem>
             <listitem>
               <para>The <option>-u</option> option causes <code>tspec</code>
               to generate unique token names for the specified objects (see
-              <a href="#Names">section 4.1.1</a>).</para>
+              <link linkend="Names">section 4.1.1</link>).</para>
             </listitem>
         
             <listitem>
   </chapter>
   
   <chapter>
+    <title>Structure</title>
+
     <sect1 id="Structure">
       <title>Specifying API Structure</title>
   
       <para>The basic form of the <code>tspec</code> description of an API has
-        already been explained in <a href="#Input">section 2.2</a> - it is a
-        directory containing a set of files corresponding to the headers in
-        that API. Each file basically consists of a list of the objects
-        declared in that header. Each object specification is part of a
-        <code>tspec</code> construct. These constructs are identified by
+        already been explained in <link linkend="Input">section 2.2</link> -
+        it is a directory containing a set of files corresponding to the
+        headers in that API. Each file basically consists of a list of the
+        objects declared in that header. Each object specification is part of
+        a <code>tspec</code> construct. These constructs are identified by
         keywords. These keywords always begin with <code>+</code> to avoid
         conflict with C identifiers. Comments may be inserted at any point.
         These are prefixed by <code>#</code> and run to the end of the
           header.</para>
   
         <para>Subsets are intended to give a layer of resolution beyond that
-          of the entire header (see <a href="#Levels">section 2.1</a>).  Each
-          subset is mapped onto a separate pair of output files, so unwary use
-          of subsets is discouraged.</para>
+          of the entire header (see <link linkend="Levels">section
+          2.1</link>).  Each subset is mapped onto a separate pair of output
+          files, so unwary use of subsets is discouraged.</para>
       </sect2>
 
       <sect2 id="Impl">
   
         <para>Another use of <code>+IMPLEMENT</code> is in the
           <code>MASTER</code> file used to list the headers in an API (see
-          <a href="#Input">section 2.2</a>). This basically consists of a list
-          of <code>+IMPLEMENT</code> commands, one per header. For example,
-          with <code>ansi</code> it consists of:
+          <link linkend="Input">section 2.2</link>). This basically consists
+          of a list of <code>+IMPLEMENT</code> commands, one per header. For
+          example, with <code>ansi</code> it consists of:
           <programlisting>
           +IMPLEMENT "ansi", "assert.h" ;
           +IMPLEMENT "ansi", "ctype.h" ;
           restricts it to the implemented sets.</para>
   
         <para>For further information on the <code>+IMPLEMENT</code> and
-          <code>+USE</code> commands see <a href="#FineImpl">section
-          6.1</a>.</para>
+          <code>+USE</code> commands see
+          <link linkend="FineImpl">section 6.1</link>.</para>
       </sect2>
     </sect1>
   </chapter>
   
   <chapter>
+    <title>Objects</title>
+
     <sect1 id="Objects">
       <title>Specifying Objects</title>
   
             token names. The first, which is default, is to use the internal
             name as the external name (there is an exception to this simple
             rule, namely field selectors - see
-            <a href="#Field">section 4.9</a>). The second, which is preferred
+            <link linkend="Field">section 4.9</link>). The second, which is preferred
             for standard APIs, is to construct a "unique name" from the API
             name, the header and the internal name. For example, under the
             first strategy, the external name of the type <code>FILE</code>
             whereas under the second it would be <code>ansi.stdio.FILE</code>.
             The unique name strategy may be specified by passing the
             <option>-u</option> command-line option to <code>tspec</code> (see
-            <a href="#Options">section 2.5</a>) or by setting the
+            <link linkend="Options">section 2.5</link>) or by setting the
             <code>UNIQUE</code> property to 1 (see
-            <a href="#Properties">section 5.4</a>).</para>
+            <link linkend="Properties">section 5.4</link>).</para>
         
           <para>Both strategies involve flattening the several C namespaces
             into the single TDF token namespace, which can lead to clashes.
           means that <code>malloc</code> is a library function returning
           <code>void *</code> which is declared using an old style declaration
           with a single argument of type <code>size_t</code>.  (For an
-          alternative approach see <a href="#Typedef">section 4.8</a>.)</para>
+          alternative approach see
+          <link linkend="Typedef">section 4.8</link>.)</para>
       </sect2>
   
       <sect2 id="Exp">
           is identical in form to the C <code>typedef</code> construct. This
           construct can be used to define pointer, procedure and array types,
           but not compound structure and union types. For these see
-          <a href="#Field">section 4.9</a> below.</para>
+          <link linkend="Field">section 4.9</link> below.</para>
   
         <para>For example, in <code>xpg3:search.h</code> we have:
           <programlisting>
           promotion of <code>x</code>. <code>x</code> must have previously
           been declared as an integral type. This gives an alternative
           approach to the old style procedure declaration problem described in
-          <a href="#Func">section 4.2</a>. Recall that:
+          <link linkend="Func">section 4.2</link>. Recall that:
           <programlisting>
           void *malloc ( sz )
           size_t sz ;
           have these corresponding fields, but they need not be in the given
           order, nor do they have to comprise the whole structure.</para>
   
-        <para>As was mentioned above (in <a href="#Names">4.1.1</a>), field
-          selectors form a special case when <code>tspec</code> is making up
-          external token names. For example, in the case above, the token name
-          for the <code>tm_sec</code> field is either <code>tm.tm_sec</code>
-          or <code>ansi.time.tm.tm_sec</code>, depending on whether or not
-          unique token names are used.</para>
+        <para>As was mentioned above (in <link linkend="Names">4.1.1</link>),
+          field selectors form a special case when <code>tspec</code> is
+          making up external token names. For example, in the case above, the
+          token name for the <code>tm_sec</code> field is either
+          <code>tm.tm_sec</code> or <code>ansi.time.tm.tm_sec</code>,
+          depending on whether or not unique token names are used.</para>
   
         <para>It is possible to have several <code>+FIELD</code> constructs
           referring to the same structure or union. For example,
       <sect2 id="Nat">
         <title>4.10. +NAT</title>
   
-        <para>In the example given in <a href="#Field">section 4.9</a>,
+        <para>In the example given in
+          <link linkend="Field">section 4.9</link>,
           <code>posix:dirent.h</code> specifies that the <code>d_name</code>
           field of <code>struct dirent</code> is a fixed sized array of
           characters, but that the size of this array is implementation
           </programlisting>
           Note the use of a local variable to stand for a value, namely the
           array size, which is invisible to the user (see
-          <a href="#Identifiers">section 4.1.2</a>).</para>
+          <link linkend="Identifiers">section 4.1.2</link>).</para>
   
         <para>As another example, in <code>ansi:setjmp.h</code> we know that
           <code>jmp_buf</code> is an array type. We therefore introduce
       <sect2 id="Token">
         <title>4.12. +TOKEN</title>
   
-        <para>As was mentioned in <a href="#Intro">section 1</a>, the
+        <para>As was mentioned in <link linkend="Intro">section 1</link>, the
           <code>#pragma token</code> syntax is highly complex, and the token
           descriptions output by <code>tspec</code> form only a small subset
           of those possible. It is possible to directly access the full
   </chapter>
   
   <chapter>
+    <title>Others</title>
+
     <sect1 id="Others">
       <title>Other tspec Constructs</title>
   
           The macros in these constructs expand respectively to <code>
           __BUILDING_LIBS</code> which, by convention is defined if and only
           if TDF library building is taking place (see
-          <a href="#Libraries">section 6.4</a>), and the protection macro
-          <code>tspec</code> makes up to protect the file
+          <link linkend="Libraries">section 6.4</link>), and the protection
+          macro <code>tspec</code> makes up to protect the file
           <code>api:header</code> against multiple inclusion (see
-          <a href="#Protect">section 6.2</a>).</para>
+          <link linkend="Protect">section 6.2</link>).</para>
       </sect2>
 
       <sect2 id="Text">
             <listitem>
               <para><code>INCLNAME</code> is a string property which may be
                 used to set the name of the include output file in place of
-                the default name given in <a href="#Output">section 2.3</a>.
-                Setting the property to the empty string suppresses the output
-                of this file.</para>
+                the default name given in
+                <link linkend="Output">section 2.3</link>.  Setting the
+                property to the empty string suppresses the output of this
+                file.</para>
             </listitem>
         
             <listitem>
             <listitem>
               <para><code>METHOD</code> is a string property which may be used
                 to specify alternative construction methods for TDF library
-                building (see <a href="#Libraries">section 6.4</a>).</para>
+                building (see <link linkend="Libraries">section 6.4</link>).</para>
             </listitem>
         
             <listitem>
               <para><code>PREFIX</code> is a string property which may be used
                 as a prefix to unique token names in place of the API and
-                header names (see <a href="#Names">section 4.1.1</a>).</para>
+                header names (see <link linkend="Names">section 4.1.1</link>).</para>
             </listitem>
         
             <listitem>
               <para><code>PROTECT</code> is a string property which may be
                 used to set the macro used by <code>tspec</code> to protect
                 the include output file against multiple inclusions (see
-                <a href= "#Protect">section 6.2</a>). Setting the property to
+                <link linkend="Protect">section 6.2</link>). Setting the property to
                 the empty string suppresses this macro.</para>
             </listitem>
         
             <listitem>
               <para><code>SOURCENAME</code> is a string property which may be
                 used to set the name of the source output file in place of the
-                default name given in <a href="#Output">section 2.3</a>.
+                default name given in <link linkend="Output">section 2.3</link>.
                 Setting the property to the empty string suppresses the output
                 of this file.</para>
             </listitem>
             <listitem>
               <para><code>UNIQUE</code> is a numeric property which may be
                 used to switch the unique token name flag on and off (see
-                <a href="#Names">section 4.1.1</a>). For standard APIs it is
+                <link linkend="Names">section 4.1.1</link>). For standard APIs it is
                 recommended that this property is set to 1 in the API
                 <code>MASTER</code> file.</para>
             </listitem>
             <listitem>
               <para><code>VERBOSE</code> is a numeric property which may be
                 used to set the level of the verbose option (see
-                <a href="#Options">section 2.5</a>).</para>
+                <link linkend="Options">section 2.5</link>).</para>
             </listitem>
         
             <listitem>
   </chapter>
   
   <chapter>
+    <title>Miscellaneous</title>
+
     <sect1 id="S6">
       <title>Miscellaneous Topics</title>
   
         <title>6.1. Fine Control of Included Files</title>
   
         <para>The <code>+IMPLEMENT</code> and <code>+USE</code> commands
-          described in <a href="#Impl">section 3.2</a> are capable of further
+          described in <link linkend="Impl">section 3.2</link> are capable of further
           refinement. Normally each such command is translated into a
           corresponding inclusion command in both the include and source
           output files.  Occasionally this is not desirable - in particular
           to protect it against multiple inclusions. Normally
           <code>tspec</code> will generate the macro name, <code>MACRO</code>,
           but it can be set using the <code>PROTECT</code> file property (see
-          <a href="#Properties">section 5.4</a>). Setting <code>PROTECT</code>
+          <link linkend="Properties">section 5.4</link>). Setting <code>PROTECT</code>
           to the empty string suppresses the protection construct altogether.
-          (Also see <a href="#If">section 5.1</a>.)</para>
+          (Also see <link linkend="If">section 5.1</link>.)</para>
       </sect2>
 
       <sect2 id="Index">
           It is assumed to be defined if and only if library building is
           taking place. <code>tspec</code> descriptions can access this macro
           directly using <code>~building_libs</code> (see
-          <a href="#If">section 5.1</a>).</para>
+          <link linkend="If">section 5.1</link>).</para>
   
         <para>The actual library building process consists of compiling the
           <code>#pragma token</code> descriptions of the objects comprising
           together with a makefile to compile all these programs to token
           definitions and to combine these token definitions into a token
           library. In fact two makefiles are created in the source output
-          directory (see <a href="#Output">section 2.3</a>). The first is
+          directory (see <link linkend="Output">section 2.3</link>). The first is
           called <code>M_api</code> and is designed for stand-alone library
           construction. The second is called <code>Makefile</code> and is
           designed for use with the library building script
         <para>There are other methods whereby the source output file may be
           changed into a set of token definitions. For example, in
           <code>c:sys.h</code> the <code>METHOD</code> file property (see
-          <a href="#Properties">section 5.4</a>) is set to <code>TDP</code>,
+          <link linkend="Properties">section 5.4</link>) is set to <code>TDP</code>,
           causing the <code>tdp</code> program to be invoked to produce the
           definitions for the basic C tokens for the system. As another
           example consider:
   </chapter>
   
   <chapter>
+    <title>Changes</title>
+
     <sect1 id="S7">
       <title>Changes in tspec 2.0</title>
   
         <itemizedlist>
           <listitem>
             <para>The added specification level of named subsets of headers
-              has been introduced (see <a href="#Levels">section 2.1</a>).
+              has been introduced (see <link linkend="Levels">section 2.1</link>).
               This has been done by introducing the <code>+SUBSET</code>
               construct and extending the <code>+IMPLEMENT</code> and
               <code>+USE</code> constructs, as well as the command-line
           <listitem>
             <para>A number of new command-line options have been added, and
               some of the existing options have been modified slightly (see
-              <a href="#Options">section 2.5</a>).</para>
+              <link linkend="Options">section 2.5</link>).</para>
           </listitem>
       
           <listitem>
             <para>The suffix <code>.api</code> has been added to the output
-              directories (see <a href="#Output">section 2.3</a>) to avoid
+              directories (see <link linkend="Output">section 2.3</link>) to avoid
               possible confusion with other include file
               directories.</para>
           </listitem>
       
           <listitem>
             <para>The use of identifiers beginning with <code>~</code> as
-              local variables is new (see <a href="#Identifiers">section
-              4.1.2</a>).</para>
+              local variables is new (see <link linkend="Identifiers">section
+              4.1.2</link>).</para>
           </listitem>
       
           <listitem>
             <para>The <code>+STATEMENT</code> and <code>+DEFINE</code>
-              constructs (see <a href="#Statement">section 4.5</a> and
-              <a href="#Define">section 4.6</a>) are new.</para>
+              constructs (see <link linkend="Statement">section 4.5</link> and
+              <link linkend="Define">section 4.6</link>) are new.</para>
           </listitem>
       
           <listitem>
             <para>The <code>(extern)</code>, <code>(weak)</code> and
               <code>(const)</code> qualifiers for <code>+FUNC</code> and
-              <code>+EXP</code> (see <a href="#Func">section 4.2</a> and
-              <a href="#Exp">section 4.3</a>) are new.</para>
+              <code>+EXP</code> (see <link linkend="Func">section 4.2</link> and
+              <link linkend="Exp">section 4.3</link>) are new.</para>
           </listitem>
       
           <listitem>
             <para>The <code>(signed)</code> and <code>(unsigned)</code>
-              qualifiers for <code>+TYPE</code> (see <a href="#Type">section
-              4.7</a>) are new.</para>
+              qualifiers for <code>+TYPE</code> (see
+              <link linkend="Type">section 4.7</link>) are new.</para>
           </listitem>
       
           <listitem>
             <para>The <code>~special</code> type constructor (see
-              <a href="#Typedef">section 4.8</a>) is new.</para>
+              <link linkend="Typedef">section 4.8</link>) is new.</para>
           </listitem>
       
           <listitem>
       
           <listitem>
             <para>The <code>+BASE_API</code> command described in
-              <a href= "#FineImpl">section 6.1</a> is new.</para>
+              <link linkend="FineImpl">section 6.1</link> is new.</para>
           </listitem>
       
           <listitem>
-            <para>The indexing routines (see <a href="#Index">section 6.3</a>)
-              have been greatly improved.</para>
+            <para>The indexing routines (see
+              <link linkend="Index">section 6.3</link>) have been greatly
+              improved.</para>
           </listitem>
         </itemizedlist>
       </para>
   </chapter>
   
   <chapter>
+    <title>References</title>
+
     <sect1 id="S8">
       <title>References</title>