Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
2 | <html> | |
3 | <head> | |
4 | <link rel="STYLESHEET" href="doc.css" type='text/css' /> | |
5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> | |
6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> | |
7 | <link rel="first" href="doc.html" title='Documenting Python' /> | |
8 | <link rel='contents' href='contents.html' title="Contents" /> | |
9 | <link rel='last' href='about.html' title='About this document...' /> | |
10 | <link rel='help' href='about.html' title='About this document...' /> | |
11 | <link rel="next" href="grammar-displays.html" /> | |
12 | <link rel="prev" href="references.html" /> | |
13 | <link rel="parent" href="special-constructs.html" /> | |
14 | <link rel="next" href="grammar-displays.html" /> | |
15 | <meta name='aesop' content='information' /> | |
16 | <title>6.11 Index-generating Markup </title> | |
17 | </head> | |
18 | <body> | |
19 | <DIV CLASS="navigation"> | |
20 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> | |
21 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
22 | <tr> | |
23 | <td class='online-navigation'><a rel="prev" title="6.10 Reference List Markup" | |
24 | href="references.html"><img src='../icons/previous.png' | |
25 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
26 | <td class='online-navigation'><a rel="parent" title="6 Special Markup Constructs" | |
27 | href="special-constructs.html"><img src='../icons/up.png' | |
28 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
29 | <td class='online-navigation'><a rel="next" title="6.12 Grammar Production Displays" | |
30 | href="grammar-displays.html"><img src='../icons/next.png' | |
31 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
32 | <td align="center" width="100%">Documenting Python</td> | |
33 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
34 | href="contents.html"><img src='../icons/contents.png' | |
35 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
36 | <td class='online-navigation'><img src='../icons/blank.png' | |
37 | border='0' height='32' alt='' width='32' /></td> | |
38 | <td class='online-navigation'><img src='../icons/blank.png' | |
39 | border='0' height='32' alt='' width='32' /></td> | |
40 | </tr></table> | |
41 | <div class='online-navigation'> | |
42 | <b class="navlabel">Previous:</b> | |
43 | <a class="sectref" rel="prev" href="references.html">6.10 Reference List Markup</A> | |
44 | <b class="navlabel">Up:</b> | |
45 | <a class="sectref" rel="parent" href="special-constructs.html">6 Special Markup Constructs</A> | |
46 | <b class="navlabel">Next:</b> | |
47 | <a class="sectref" rel="next" href="grammar-displays.html">6.12 Grammar Production Displays</A> | |
48 | </div> | |
49 | <hr /></div> | |
50 | </DIV> | |
51 | <!--End of Navigation Panel--> | |
52 | ||
53 | <H2><A NAME="SECTION0007110000000000000000"></A><A NAME="indexing"></A> | |
54 | <BR> | |
55 | 6.11 Index-generating Markup | |
56 | </H2> | |
57 | ||
58 | <P> | |
59 | Effective index generation for technical documents can be very | |
60 | difficult, especially for someone familiar with the topic but not | |
61 | the creation of indexes. Much of the difficulty arises in the | |
62 | area of terminology: including the terms an expert would use for a | |
63 | concept is not sufficient. Coming up with the terms that a novice | |
64 | would look up is fairly difficult for an author who, typically, is | |
65 | an expert in the area she is writing on. | |
66 | ||
67 | <P> | |
68 | The truly difficult aspects of index generation are not areas with | |
69 | which the documentation tools can help. However, ease | |
70 | of producing the index once content decisions are made is within | |
71 | the scope of the tools. Markup is provided which the processing | |
72 | software is able to use to generate a variety of kinds of index | |
73 | entry with minimal effort. Additionally, many of the environments | |
74 | described in section <A href="info-units.html#info-units">6.3</A>, ``Information Units,'' will | |
75 | generate appropriate entries into the general and module indexes. | |
76 | ||
77 | <P> | |
78 | The following macro can be used to control the generation of index | |
79 | data, and should be used in the document preamble: | |
80 | ||
81 | <P> | |
82 | ||
83 | <dl class='macrodesc'> | |
84 | <dt><b><tt class='macro'>\makemodindex</tt></b> | |
85 | </dt> | |
86 | <dd> | |
87 | This should be used in the document preamble if a ``Module | |
88 | Index'' is desired for a document containing reference material | |
89 | on many modules. This causes a data file | |
90 | <code>lib<var>jobname</var>.idx</code> to be created from the | |
91 | <tt class='macro'>\declaremodule</tt> macros. This file can be processed by the | |
92 | <b class="program">makeindex</b> program to generate a file which can be | |
93 | <tt class='macro'>\input</tt> into the document at the desired location of the | |
94 | module index. | |
95 | </dd></dl> | |
96 | ||
97 | <P> | |
98 | There are a number of macros that are useful for adding index | |
99 | entries for particular concepts, many of which are specific to | |
100 | programming languages or even Python. | |
101 | ||
102 | <P> | |
103 | ||
104 | <dl class='macrodesc'> | |
105 | <dt><b><tt class='macro'>\bifuncindex</tt></b> | |
106 | <tt>{</tt><var>name</var><tt>}</tt></dt> | |
107 | <dd> | |
108 | Add an index entry referring to a built-in function named | |
109 | <var>name</var>; parentheses should not be included after | |
110 | <var>name</var>. | |
111 | </dd></dl> | |
112 | ||
113 | <P> | |
114 | ||
115 | <dl class='macrodesc'> | |
116 | <dt><b><tt class='macro'>\exindex</tt></b> | |
117 | <tt>{</tt><var>exception</var><tt>}</tt></dt> | |
118 | <dd> | |
119 | Add a reference to an exception named <var>exception</var>. The | |
120 | exception should be class-based. | |
121 | </dd></dl> | |
122 | ||
123 | <P> | |
124 | ||
125 | <dl class='macrodesc'> | |
126 | <dt><b><tt class='macro'>\kwindex</tt></b> | |
127 | <tt>{</tt><var>keyword</var><tt>}</tt></dt> | |
128 | <dd> | |
129 | Add a reference to a language keyword (not a keyword parameter | |
130 | in a function or method call). | |
131 | </dd></dl> | |
132 | ||
133 | <P> | |
134 | ||
135 | <dl class='macrodesc'> | |
136 | <dt><b><tt class='macro'>\obindex</tt></b> | |
137 | <tt>{</tt><var>object type</var><tt>}</tt></dt> | |
138 | <dd> | |
139 | Add an index entry for a built-in object type. | |
140 | </dd></dl> | |
141 | ||
142 | <P> | |
143 | ||
144 | <dl class='macrodesc'> | |
145 | <dt><b><tt class='macro'>\opindex</tt></b> | |
146 | <tt>{</tt><var>operator</var><tt>}</tt></dt> | |
147 | <dd> | |
148 | Add a reference to an operator, such as "<tt class="samp">+</tt>". | |
149 | </dd></dl> | |
150 | ||
151 | <P> | |
152 | ||
153 | <dl class='macrodesc'> | |
154 | <dt><b><tt class='macro'>\refmodindex</tt></b> | |
155 | <tt>[</tt><var>key</var><tt>]</tt><tt>{</tt><var>module</var><tt>}</tt></dt> | |
156 | <dd> | |
157 | Add an index entry for module <var>module</var>; if <var>module</var> | |
158 | contains an underscore, the optional parameter <var>key</var> should | |
159 | be provided as the same string with underscores removed. An | |
160 | index entry ``<var>module</var> (module)'' will be generated. This | |
161 | is intended for use with non-standard modules implemented in | |
162 | Python. | |
163 | </dd></dl> | |
164 | ||
165 | <P> | |
166 | ||
167 | <dl class='macrodesc'> | |
168 | <dt><b><tt class='macro'>\refexmodindex</tt></b> | |
169 | <tt>[</tt><var>key</var><tt>]</tt><tt>{</tt><var>module</var><tt>}</tt></dt> | |
170 | <dd> | |
171 | As for <tt class='macro'>\refmodindex</tt>, but the index entry will be | |
172 | ``<var>module</var> (extension module).'' This is intended for use | |
173 | with non-standard modules not implemented in Python. | |
174 | </dd></dl> | |
175 | ||
176 | <P> | |
177 | ||
178 | <dl class='macrodesc'> | |
179 | <dt><b><tt class='macro'>\refbimodindex</tt></b> | |
180 | <tt>[</tt><var>key</var><tt>]</tt><tt>{</tt><var>module</var><tt>}</tt></dt> | |
181 | <dd> | |
182 | As for <tt class='macro'>\refmodindex</tt>, but the index entry will be | |
183 | ``<var>module</var> (built-in module).'' This is intended for use | |
184 | with standard modules not implemented in Python. | |
185 | </dd></dl> | |
186 | ||
187 | <P> | |
188 | ||
189 | <dl class='macrodesc'> | |
190 | <dt><b><tt class='macro'>\refstmodindex</tt></b> | |
191 | <tt>[</tt><var>key</var><tt>]</tt><tt>{</tt><var>module</var><tt>}</tt></dt> | |
192 | <dd> | |
193 | As for <tt class='macro'>\refmodindex</tt>, but the index entry will be | |
194 | ``<var>module</var> (standard module).'' This is intended for use | |
195 | with standard modules implemented in Python. | |
196 | </dd></dl> | |
197 | ||
198 | <P> | |
199 | ||
200 | <dl class='macrodesc'> | |
201 | <dt><b><tt class='macro'>\stindex</tt></b> | |
202 | <tt>{</tt><var>statement</var><tt>}</tt></dt> | |
203 | <dd> | |
204 | Add an index entry for a statement type, such as <tt class="keyword">print</tt> | |
205 | or <tt class="keyword">try</tt>/<tt class="keyword">finally</tt>. | |
206 | ||
207 | <P> | |
208 | XXX Need better examples of difference from <tt class='macro'>\kwindex</tt>. | |
209 | </dd></dl> | |
210 | ||
211 | <P> | |
212 | Additional macros are provided which are useful for conveniently | |
213 | creating general index entries which should appear at many places | |
214 | in the index by rotating a list of words. These are simple macros | |
215 | that simply use <tt class='macro'>\index</tt> to build some number of index | |
216 | entries. Index entries build using these macros contain both | |
217 | primary and secondary text. | |
218 | ||
219 | <P> | |
220 | ||
221 | <dl class='macrodesc'> | |
222 | <dt><b><tt class='macro'>\indexii</tt></b> | |
223 | <tt>{</tt><var>word1</var><tt>}</tt><tt>{</tt><var>word2</var><tt>}</tt></dt> | |
224 | <dd> | |
225 | Build two index entries. This is exactly equivalent to using | |
226 | <code>\index{<var>word1</var>!<var>word2</var>}</code> and | |
227 | <code>\index{<var>word2</var>!<var>word1</var>}</code>. | |
228 | </dd></dl> | |
229 | ||
230 | <P> | |
231 | ||
232 | <dl class='macrodesc'> | |
233 | <dt><b><tt class='macro'>\indexiii</tt></b> | |
234 | <tt>{</tt><var>word1</var><tt>}</tt><tt>{</tt><var>word2</var><tt>}</tt><tt>{</tt><var>word3</var><tt>}</tt></dt> | |
235 | <dd> | |
236 | Build three index entries. This is exactly equivalent to using | |
237 | <code>\index{<var>word1</var>!<var>word2</var> <var>word3</var>}</code>, | |
238 | <code>\index{<var>word2</var>!<var>word3</var>, <var>word1</var>}</code>, and | |
239 | <code>\index{<var>word3</var>!<var>word1</var> <var>word2</var>}</code>. | |
240 | </dd></dl> | |
241 | ||
242 | <P> | |
243 | ||
244 | <dl class='macrodesc'> | |
245 | <dt><b><tt class='macro'>\indexiv</tt></b> | |
246 | <tt>{</tt><var>word1</var><tt>}</tt><tt>{</tt><var>word2</var><tt>}</tt><tt>{</tt><var>word3</var><tt>}</tt><tt>{</tt><var>word4</var><tt>}</tt></dt> | |
247 | <dd> | |
248 | Build four index entries. This is exactly equivalent to using | |
249 | <code>\index{<var>word1</var>!<var>word2</var> <var>word3</var> <var>word4</var>}</code>, | |
250 | <code>\index{<var>word2</var>!<var>word3</var> <var>word4</var>, <var>word1</var>}</code>, | |
251 | <code>\index{<var>word3</var>!<var>word4</var>, <var>word1</var> <var>word2</var>}</code>, | |
252 | and | |
253 | <code>\index{<var>word4</var>!<var>word1</var> <var>word2</var> <var>word3</var>}</code>. | |
254 | </dd></dl> | |
255 | ||
256 | <P> | |
257 | ||
258 | <DIV CLASS="navigation"> | |
259 | <div class='online-navigation'> | |
260 | <p></p><hr /> | |
261 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
262 | <tr> | |
263 | <td class='online-navigation'><a rel="prev" title="6.10 Reference List Markup" | |
264 | href="references.html"><img src='../icons/previous.png' | |
265 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
266 | <td class='online-navigation'><a rel="parent" title="6 Special Markup Constructs" | |
267 | href="special-constructs.html"><img src='../icons/up.png' | |
268 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
269 | <td class='online-navigation'><a rel="next" title="6.12 Grammar Production Displays" | |
270 | href="grammar-displays.html"><img src='../icons/next.png' | |
271 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
272 | <td align="center" width="100%">Documenting Python</td> | |
273 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
274 | href="contents.html"><img src='../icons/contents.png' | |
275 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
276 | <td class='online-navigation'><img src='../icons/blank.png' | |
277 | border='0' height='32' alt='' width='32' /></td> | |
278 | <td class='online-navigation'><img src='../icons/blank.png' | |
279 | border='0' height='32' alt='' width='32' /></td> | |
280 | </tr></table> | |
281 | <div class='online-navigation'> | |
282 | <b class="navlabel">Previous:</b> | |
283 | <a class="sectref" rel="prev" href="references.html">6.10 Reference List Markup</A> | |
284 | <b class="navlabel">Up:</b> | |
285 | <a class="sectref" rel="parent" href="special-constructs.html">6 Special Markup Constructs</A> | |
286 | <b class="navlabel">Next:</b> | |
287 | <a class="sectref" rel="next" href="grammar-displays.html">6.12 Grammar Production Displays</A> | |
288 | </div> | |
289 | </div> | |
290 | <hr /> | |
291 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
292 | </DIV> | |
293 | <!--End of Navigation Panel--> | |
294 | <ADDRESS> | |
295 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
296 | </ADDRESS> | |
297 | </BODY> | |
298 | </HTML> |