-
Notifications
You must be signed in to change notification settings - Fork 1
/
docbook_markup.txt
469 lines (422 loc) · 15.3 KB
/
docbook_markup.txt
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
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
This document contains:
+ Synopsis markup in SGML
- examples for command markup
- examples for function markup
+ Common LSB usages
- notes on man page text development
- tags to be phased into general use prior to LSB v2.0
- corrections to tags now in general use
- often-used spec phrases
This document:
+ is based on DocBook 4.2 markup principles and examples as illustrated
in official DocBook documentation:
- "DocBook - The Definitive Guide" by N.Walsh & L.Muellner (O'Reilly)
- http://docbook.org/tdg/en/html/docbook.html
+ is the start of a formal style guide for LSB content contributors
+ will be used for updates to existing specification texts
+ may be used for development of new content
+ is a work-in-progress and will be updated as needed to reflect
current text development goals
Some of the document is aimed at being legal for DocBook-XML. If
we decide to do this more consistently, the following are all issues:
* quotes around attributes, e.g. <arg choice="plain"> not <arg choice=plain>
* all element, attribute, and entity names must be in lowercase
* Trailing slashes for empty elements, for example <xref /> not <xref>
(See Chapter 2 of the DocBook book; Appendix B also might help but isn't
as clear on the case sensitivity point).
NOTE --- the current docbook utils do not correctly handle <xref />, so
don't use it!
Question: what does the <DATE> tag mean (in <REFSYNOPSISDIVINFO>,
<REFSECT1INFO>, and so on)? Is it the date that particular page was
last modified (in which case we have a lot of habits to change if we
want this to get done manually)? Do we really want these <DATE> tags
(I suspect not)?
General comment on what is marked up and why:
---------------------------------------------
In addition to the obvious, like displaying italics/typewriter/etc
with some sort of usefulness, markup is intended for being used in an
index (most obviously, things like <command> and <function>).
The following sections give specifics on things which are marked up.
Some things which treated as ordinary text (that is, not marked up or
spelled differently from customary English usage) are:
* Names of characters (e.g. space, colon, etc).
* Zero, one and other really common numbers. More obscure data values
(such as +131071 in adjtimex) can optionally be marked up as
<literal> for indexing.
SYNOPSIS MARKUP IN SGML
=======================
The following <CMDSYNOPSIS> and <FUNCSYNOPSIS> tag structures
*replace* the <SYNOPSIS> structures in current LSB specifications.
SYNOPSIS EXAMPLE - command (fictional) requiring:
+ standard argument
+ argument with input
+ nested arguments
+ mutually exclusive arguments
+ required bracketed argument
+ required unbracketed argument
+ required unbracketed repeating argument
======= Desired effect =======
abc [-d] [-e file] [month [year]] [-f | -g] {directory} group file...
--[where file & directory & group & file... are italicized]
=========== Syntax ===========
<CMDSYNOPSIS>
<COMMAND>abc</COMMAND>
<ARG>-d</ARG>
<ARG>-e <REPLACEABLE>file</REPLACEABLE></ARG>
<ARG>month <ARG>year</ARG></ARG>
<GROUP>
<ARG>-f</ARG>
<ARG>-g</ARG>
</GROUP>
<ARG CHOICE=REQ><REPLACEABLE>directory</REPLACEABLE></ARG>
<ARG CHOICE=PLAIN><REPLACEABLE>group</REPLACEABLE></ARG>
<ARG REP=REPEAT CHOICE=PLAIN><REPLACEABLE>file</REPLACEABLE></ARG>
</CMDSYNOPSIS>
=========== Notes ============
==============================
SYNOPSIS EXAMPLE - Function requiring header file
======= Desired effect =======
#include <xyz.h>
int abc(int arg1);
--[where arg1 is italicized]
=========== Syntax ===========
<FUNCSYNOPSIS>
<FUNCSYNOPSISINFO>
#include <xyz.h>
</FUNCSYNOPSISINFO>
<FUNCPROTOTYPE>
<FUNCDEF>int
<FUNCTION>abc</FUNCTION></FUNCDEF>
<PARAMDEF>int
<PARAMETER><REPLACEABLE>arg1</REPLACEABLE></PARAMETER></PARAMDEF>
</FUNCPROTOTYPE>
</FUNCSYNOPSIS>
=========== Notes ============
- The target of this illustration is in the text:
#include <xyz.h>
==============================
SYNOPSIS EXAMPLE - Function requiring absolute arguments only
======= Desired effect =======
int abc(int arg1, int arg2);
--[where arg1 & arg2 are italicized]
=========== Syntax ===========
<FUNCSYNOPSIS>
<FUNCPROTOTYPE>
<FUNCDEF>int
<FUNCTION>abc</FUNCTION></FUNCDEF>
<PARAMDEF>int
<PARAMETER><REPLACEABLE>arg1</REPLACEABLE></PARAMETER></PARAMDEF>
<PARAMDEF>int
<PARAMETER><REPLACEABLE>arg2</REPLACEABLE></PARAMETER></PARAMDEF>
</FUNCPROTOTYPE>
</FUNCSYNOPSIS>
=========== Notes ============
- The target of this illustration is in the text: int arg1, int arg2
- The definition clause for this type may be done using funcsynopsis or
synopsis syntax, depending upon requirements of the document.
==============================
SYNOPSIS EXAMPLE - Function requiring variable arguments only
======= Desired effect =======
int abc(...);
=========== Syntax ===========
<FUNCSYNOPSIS>
<FUNCPROTOTYPE>
<FUNCDEF>int
<FUNCTION>abc</FUNCTION></FUNCDEF>
<VARARGS>
</FUNCPROTOTYPE>
</FUNCSYNOPSIS>
=========== Notes ============
- The target of this illustration is in the text: ...
- The varargs markup requires no closing tag and generates any necessary
function-based punctuation.
- The varargs markup is used to specify variable arguments only when the
function contains no absolute arguments. (See "Function requiring both
absolute and variable arguments" for alternate specification of variable
arguments.)
==============================
SYNOPSIS EXAMPLE - Function requiring both absolute and variable arguments
======= Desired effect =======
int abc(char *arg1, ...);
--[where *arg1 is italicized]
=========== Syntax ===========
<FUNCSYNOPSIS>
<FUNCPROTOTYPE>
<FUNCDEF>int
<FUNCTION>abc</FUNCTION></FUNCDEF>
<PARAMDEF>char *
<PARAMETER><REPLACEABLE>arg1</REPLACEABLE></PARAMETER></PARAMDEF>
<PARAMDEF><PARAMETER>...</PARAMETER></PARAMDEF>
</FUNCPROTOTYPE>
</FUNCSYNOPSIS>
=========== Notes ============
- The target of this illustration is in the text: char *arg1, ...
- Ellipses are used to specify variable arguments only when the function
also contains absolute arguments. (See "Function requiring variable
arguments only" for alternate specification of variable arguments.)
+++++++SPECIAL LSB EXTENSION NOTE++++++++++++++++
- If the top level file (e.g. LSB-generic.sgml) contains the following
extensions to the Docbook DTD, then <VARARGS> tags work even in this
mixed case.
<!DOCTYPE BOOK PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
<!ENTITY % funcprototype.element "IGNORE">
<!ELEMENT FuncPrototype - O (FuncDef, (Void | (ParamDef*, VarArgs?)))>
With this in place, you can better specify the above as
<FUNCSYNOPSIS>
<FUNCPROTOTYPE>
<FUNCDEF>int
<FUNCTION>abc</FUNCTION></FUNCDEF>
<PARAMDEF>char *
<PARAMETER><REPLACEABLE>arg1</REPLACEABLE></PARAMETER></PARAMDEF>
<VARARGS>
</FUNCPROTOTYPE>
</FUNCSYNOPSIS>
==============================
SYNOPSIS EXAMPLE - Function requiring zero arguments
======= Desired effect =======
int abc(void);
=========== Syntax ===========
<FUNCSYNOPSIS>
<FUNCPROTOTYPE>
<FUNCDEF>int
<FUNCTION>abc</FUNCTION></FUNCDEF>
<VOID>
</FUNCPROTOTYPE>
</FUNCSYNOPSIS>
=========== Notes ============
- The target of this illustration is in the text: void
- The void markup requires no closing tag and generates any necessary
function-based punctuation.
==============================
SYNOPSIS EXAMPLE - Function that is defined as a structure
======= Desired effect =======
struct hostent *abc(const char arg1);
--[where arg1 is italicized]
=========== Syntax ===========
<FUNCSYNOPSIS>
<FUNCPROTOTYPE>
<FUNCDEF>struct
<FUNCTION>
<STRUCTNAME>hostent</STRUCTNAME> *abc</FUNCTION></FUNCDEF>
<PARAMDEF>const char
<PARAMETER><REPLACEABLE>arg1</REPLACEABLE></PARAMETER></PARAMDEF>
</FUNCPROTOTYPE>
</FUNCSYNOPSIS>
=========== Notes ============
- The target of this illustration is in the text:
struct hostent *abc
==============================
SYNOPSIS EXAMPLE - Function that uses a structure as a parameter
======= Desired effect =======
int abc(const char * restrict arg1, struct hostent * restrict
arg2);
--[where arg1 & arg2 are italicized]
=========== Syntax ===========
<FUNCSYNOPSIS>
<FUNCPROTOTYPE>
<FUNCDEF>int
<FUNCTION>abc</FUNCTION></FUNCDEF>
<PARAMDEF>const char * restrict
<PARAMETER><REPLACEABLE>arg1</REPLACEABLE></PARAMETER></PARAMDEF>
<PARAMDEF>struct hostent * restrict
<PARAMETER>arg2</PARAMETER></PARAMDEF>
</FUNCPROTOTYPE>
</FUNCSYNOPSIS>
=========== Notes ============
- The target of this illustration is in the text:
struct hostent * restrict arg2
==============================
SYNOPSIS EXAMPLE - Function that uses a function as a parameter
======= Desired effect =======
int abc(int def, int (*ghi) (const char *, int));
--[where def is italicized]
=========== Syntax ===========
<FUNCSYNOPSIS>
<FUNCPROTOTYPE>
<FUNCDEF>int
<FUNCTION>abc</FUNCTION></FUNCDEF>
<PARAMDEF>int
<PARAMETER><REPLACEABLE>def</REPLACEABLE></PARAMETER></PARAMDEF>
<PARAMDEF>int
<FUNCPARAMS>*ghi</FUNCPARAMS>
<FUNCPARAMS>const char *, int</FUNCPARAMS></PARAMDEF>
</FUNCPROTOTYPE>
</FUNCSYNOPSIS>
=========== Notes ============
- The target of this illustration is in the text:
int (*ghi) (const char *, int)
==============================
SYNOPSIS EXAMPLE - Structure with preceding name
======= Desired effect =======
struct abc_status
{
const char *abc_field1;
void *abc_field2;
};
=========== Syntax ===========
<SYNOPSIS>
struct <STRUCTNAME>abc_status</STRUCTNAME>
{
const char <STRUCTFIELD>*abc_field1</STRUCTFIELD>;
void <STRUCTFIELD>*abc_field2</STRUCTFIELD>;
};
</SYNOPSIS>
=========== Notes ============
- The definition clause for this type requires synopsis syntax.
==============================
SYNOPSIS EXAMPLE - Structure with trailing name
======= Desired effect =======
#include <sys/xyz.h>
typedef struct
{
const char *abc_field1;
void *abc_field2;
const char *abc_field3;
void *abc_field4;
} abc_info;
=========== Syntax ===========
<SYNOPSIS>
#include <sys/xyz.h>
typedef struct
{
const char <STRUCTFIELD>*abc_field1</STRUCTFIELD>;
void <STRUCTFIELD>*abc_field2</STRUCTFIELD>;
const char <STRUCTFIELD>*abc_field3</STRUCTFIELD>;
void <STRUCTFIELD>*abc_field4</STRUCTFIELD>;
} <STRUCTNAME>abc_info</STRUCTNAME>;
</SYNOPSIS>
=========== Notes ============
- For consistency, the LSB will use the funcsynopsis syntax to
specify any required include or define clauses.
- The definition clause for this type requires synopsis syntax.
==============================
SYNOPSIS EXAMPLE - Single variable
======= Desired effect =======
#include <xyz.h>
int __xyz;
=========== Syntax ===========
<FUNCSYNOPSIS>
<FUNCSYNOPSISINFO>
#include <xyz.h>
</FUNCSYNOPSISINFO>
</FUNCSYNOPSIS>
<SYNOPSIS>
int <VARNAME>__xyz</VARNAME>;
</SYNOPSIS>
=========== Notes ============
- The target of this illustration is in the text: int __xyz
- For consistency, the LSB will use the funcsynopsis syntax to
specify any required include or define clauses.
- The definition clause for this type requires synopsis syntax.
==============================
NOTES ON MAN PAGE TEXT DEVELOPMENT
==================================
+ External to the Synopsis, references to function names will appear
sans "()".
+ Function prototypes should not include any "extern" storage qualifier
+ __const and __restrict should be written as const and restrict; the
underbar versions of these names are transitional while some versions
of some compilers might not understand these ISO C 99 qualifiers.
However, since we depend on SUSv4, which in turn depends on ISO C99,
it is reasonable to ue the full C99 terms everywhere.
+ Leading underbars in names should be restricted to where they are required
in the binary file only; for example in the name of a function.
Arguments need never use leading underbars.
+ Command or function elements identified in the synopsis (name,
parameter) will not be type-labeled in subsequent text. Example: the
phrase "the getopt function" will appear simply as "getopt".
+ On exception, type-labels will be used in these cases:
- to avoid misidentification of similarly-named command or function
elements.
- to qualify names of functions/elements that are not specified in
the Synopsis.
+ Where possible, Description text will begin with the name of the
entity (command, function) described, followed by an action.
Examples: "memmem finds the start ...", "newgrp changes the current
group ..."
+ The use of pronouns ("It", "This") to begin the first sentences of
Description paragraphs will be avoided.
TAGS TO BE PHASED INTO GENERAL USE PRIOR TO LSB V2.0
====================================================
<ACRONYM>
<ACTION>
<APPLICATION>
<CONSTANT>
<ERRORCODE>, <ERRORNAME> and <ERRORTYPE>
<EXAMPLE>
<FILENAME>
<IMPORTANT>
<INTERFACENAME>
<LITERAL>
<OPTION>
<QUOTE> and <BLOCKQUOTE>
<RETURNVALUE>
<STRUCTNAME> and <STRUCTFIELD>
<SYMBOL>
<TOKEN>
<VARNAME>
CORRECTIONS TO TAGS NOW IN GENERAL USE
======================================
<EMPHASIS> will be replaced whenever a more appropriate tag is
required.
<REPLACEABLE> will be replaced whenever a more appropriate tag is
required; used only to indicate user-specified text.
<LITERAL> used only to indicate a literal data value, a generic
bit of data (the same data would be represented in
volume text by <COMPUTEROUTPUT> or <USERINPUT>).
OFTEN-USED SPEC PHRASES
=======================
<PARA>
On success, <RETURNVALUE>0</RETURNVALUE> is returned.
On error, <RETURNVALUE>-1</RETURNVALUE> is returned and
the global variable <VARNAME>errno</VARNAME> is set appropriately.
</PARA>
<PARA>
<FUNCTION>__daylight</FUNCTION> is as specified in the
<CITETITLE PUBWORK="BOOK">Single UNIX Specification</CITETITLE>,
but with differences as listed below.
</PARA>
<PARA>
<FUNCTION>__daylight</FUNCTION> is as specified in the
<CITETITLE PUBWORK="BOOK">Single UNIX Specification,
Version 3</CITETITLE>.
</PARA>
<PARA>
<FUNCTION>__getpagesize</FUNCTION> is not in the source standard;
it is only in the binary standard.
</PARA>
<PARA>
<FUNCTION>__getpagesize</FUNCTION> has the same specification as
<FUNCTION>getpagesize</FUNCTION>.
</PARA>
<PARA>
<FUNCTION>__getpagesize</FUNCTION> is an alias for
<FUNCTION>getpagesize</FUNCTION> - get current page size.
</PARA>
VARIABLES, ARRAY ITEMS
======================
For these types, <VARNAME> is used in the same context as <FUNCTION>
for functions and interfaces. Example:
<PARA>
<VARNAME>__environ</VARNAME> is an alias for <VARNAME>environ</VARNAME>
- user environment.
</PARA>
DEPRECATION SAMPLES
===================
<REFNAMEDIV>
<REFNAME>fstatfs
</REFNAME>
<REFPURPOSE>(deprecated)
</REFPURPOSE>
</REFNAMEDIV>
<PARA>
<FUNCTION>__dcgettext</FUNCTION> has been deprecated from the
<ACRONYM>LSB</ACRONYM> because it is no longer used by
<FUNCTION>dcgettext</FUNCTION>. Originally, it was intended
only for the binary standard.
</PARA>
<PARA>
<FUNCTION>fstatfs</FUNCTION> is expected to disappear from a future
version of the <ACRONYM>LSB</ACRONYM>; applications should call the
<FUNCTION>fstatvfs</FUNCTION> interface.
</PARA>