<?xml version="1.0"?>
<!DOCTYPE sect2 PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
  <sect2 id="guidelines-sectids">
	<title>Section IDs</title>
	<para>
	  Section IDs are unique identifiers that you assign to each
	  section of an XML file. You can use the section IDs to
	  cross-reference sections.  
	</para>
	<para>
	  The following sections contain suggestions as to how to write
	  section IDs in XML files. The only real requirement for writing
	  section IDs is that the IDs must be unique within a document.
	</para>
	
	<sect3 id="guidelines-markupids">
	  <title>How to Tag a Section ID in XML</title>
	  <para>
		Use the <markup>id</markup> attribute with the
		<sgmltag>&lt;sect&gt;</sgmltag> tag. For example:
	  </para>
	  <para>
		<markup>&lt;sect1 id=&quot;gedit-intro&quot;&gt;</markup>.
	  </para>
	</sect3>
	
	<sect3 id="guidelines-structids">
	  <title>How to Structure Section IDs in Online Help</title>
	  <note>
		<para>
		  These guidelines do not apply to the top-level ID associated
		  with the <sgmltag>&lt;article&gt;</sgmltag> tag in a help
		  manual, that is:
		</para>
		<para>
		  <markup>&lt;article id=&quot;index&quot; lang=&quot;en&quot;&gt;</markup>
		</para> 
	  </note>  
	  <para>
		Use the following guidelines to write consistent section IDs
		in documentation:
	  </para>
	  <orderedlist>
		<listitem>
		  <para>Form the first part of each ID using the filename of
			the XML file for the documentation. For example, if the
			filename of the XML book file is
			<filename>gedit.xml</filename>, the first part of each
			section ID is <quote>gedit</quote>. Likewise, if the name
			of the XML file is
			<filename>gnome-dictionary.xml</filename>, the first part
			of the section ID is <quote>gnome-dictionary</quote>.
		  </para>
			</listitem>
		<listitem>
		  <para>
			Follow the first part of the ID with a hyphen. For
			example: 
		  </para> 
		  <para>gedit-</para>
		  <para>gnome-dictionary-</para>
		</listitem>
		<listitem>
		  <para>If the section ID is a table section ID, follow the 
			first part of the ID with <quote>TBL-</quote>:
		  </para>
		  <para>gedit-TBL-</para>
		</listitem>
		<listitem>
		  <para>
			If the section ID is a figure section ID, follow the 
			first part of the ID with <quote>FIG-</quote>:
		  </para>
		  <para>gedit-FIG-</para>
		</listitem>
		<listitem>
		  <para>Form the remainder of the ID using an abbreviated form of 
			the section title. Here are some examples:
		  </para>
		  <itemizedlist>
			<listitem>
			  <para>If the title of the section is
				<quote>Introduction</quote>, use
				<quote>gedit-intro</quote>.
			  </para> 
			</listitem>
			<listitem>
			  <para>
				If the title of the section is <quote>Preferences</quote>, use 
				<quote>gedit-prefs</quote>.
			  </para>
			</listitem>  
			<listitem>
			  <para>
				If the title of the section is <quote>Save Tabbed
				Section</quote>, which is a subsection of
				<quote>Preferences</quote>, you can use
				<quote>gedit-prefs-save</quote>.
			  </para>
			</listitem>  
			<listitem>
			  <para>
				If the title of the section is <quote>To Save a
				File</quote>, use an ID similar to
				<quote>gedit-save-file</quote>.
			  </para>
			</listitem>
			<listitem>
			  <para>
				If the title of a figure is <quote>gedit Main
				Window</quote>, use an ID similar to
				<quote>gedit-FIG-main-window</quote>.
			  </para>
			</listitem>
		  </itemizedlist>
		  <para>
			The important thing is that all section IDs are unique within 
			each XML file.
		  </para>
		</listitem>
	  </orderedlist>   
	</sect3>

	<sect3 id="guidelines-changeids">
	  <title>When to Change Section IDs for Online Help</title>
	  <para>
		If you receive a request from the developer of an application or applet
		to change the name of the XML file for a manual, you
		should also change the section IDs in your document to match the new
		filename. For example, if the Fish Applet is renamed the Wanda Applet 
		and the filename changes from <filename>fish.xml</filename> to 
		<filename>wanda.xml</filename>, you should change the first part of 
		each section ID from <quote>fish-</quote> to <quote>wanda-</quote>. 
	  </para>
	  <note>
		<para>
		  Do not change the XML filename or section IDs without the approval 
		  of the developer as this impacts the help calls from the application 
		  to the online help manuals.
		</para>
	  </note>  
	</sect3>

	<sect3 id="guidelines-structbookids">
	  <title>How to Structure Section IDs in a Book</title>
	  <para>
		Use the following guidelines to write consistent section IDs in a book:
	  </para>
	  <orderedlist>
		<listitem>
		  <para>
			Form the first part of every ID using the name of the XML
			file that the ID is located in. For example, for a file
			called <filename>windows.xml</filename>, use
			<quote>windows</quote>.
		  </para>
		</listitem>
		<listitem>
		  <para>Follow the first part of the ID with a hyphen:</para>
		  <para>windows-</para>
		</listitem>
		<listitem>
		  <para>
			If the section ID is a table section ID, follow the 
			first part of the ID with <quote>TBL-</quote>:
		  </para>
		  <para>windows-TBL-</para>
		</listitem>
		<listitem>
		  <para>
			If the section ID is a figure section ID, follow the 
			first part of the ID with <quote>FIG-</quote>:
		  </para>
		  <para>windows-FIG-</para>
		</listitem>
		<listitem>
		  <para>
			Complete the section ID with a number that uniquely 
			identifies the section ID:
		  </para>
		  <para>windows-123</para>
		  <para>windows-TBL-456</para>
		  <para>windows-FIG-789</para>
		</listitem>
	  </orderedlist>
	  <para>
		It is important that all section IDs are unique within  
		all the XML files in the book.
	  </para>  
	</sect3>

	<sect3 id="guidelines-changebookids">
	  <title>When to Change Section IDs in a Book</title>
	  <para>
		If you change the name of a book file, you should change the
		section IDs to match the new filename. For example, if the
		<filename>windows.xml</filename> file is renamed
		<filename>dialogs.xml</filename>, you should change the first
		part of the section IDs to <quote>dialogs-</quote>.
	  </para>
	  <note>
		<para> 
		  Changing section IDs in a book might affect online help
		  calls.  Contact the developer responsible for the help calls
		  before you change any section IDs. If there are negative
		  implications associated with changing the section IDs, you
		  should not change the IDs to match the filename.
		</para>
	  </note>
	</sect3>
  
  </sect2> 
