1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
|
<?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><sect></sgmltag> tag. For example:
</para>
<para>
<markup><sect1 id="gedit-intro"></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><article></sgmltag> tag in a help
manual, that is:
</para>
<para>
<markup><article id="index" lang="en"></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>
|
