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
|
Rules for Open GL man pages:
* Describe commands that differ only by a suffix on the same
page. Do this regardless of whether the commands take the
same or different arguments. For example, all 24 Vertex
commands are described on one page.
Issue - current tools like to separate v and non-v commands.
* Describe commands that operate in obvious pairs on the same
page. For example, Begin and End, or PushMatrix and PopMatrix.
* Use the _header(desc) macro to begin a manpage. Write the
1-line command description "desc" using the imperative tense.
For example:
_header(Operate on the accumulation buffer)
not
_header(Operates on the accumulation buffer)
* The order of the entries on a manpage is
header
PARAMETERS (unless the command takes no parameters)
DESCRIPTION
EXAMPLE (optional)
ERRORS (optional)
SEE ALSO
BUGS (optional)
NOTES (optional)
* Use the _phead(param) macro to describe each parameter or
group of parameters.
* Begin the description of in-only parameters with the phrase
"Specifies".
* Begin the description of out-only parameters with the phrase
"Returns".
* Begin the description of in-and-out parameters with the
phrase "Specifies and returns". If there is a difference
between what is specified and what is returned, use two
paragraphs for the description, the first beginning with
"Specifies" and the second beginning with "Returns".
* Group like parameters into a single description. For example
"x,y Specify the x and y coordinates ...", or
"r,g,b Return the red, green, and blue color values ..."
Possible tools issue.
* Include the default value in the description of parameters
that directly specify GL state.
* Refer to parameters using the _param# macro, never explicitly
by name. Note that this rules out clever English tricks that
count on the macro evaluating to a particular string. For
example, one cannot say "The second parameter is a floating
point _param2", where it is expected that _param2 will evaluate
to the string "value".
* Use _cmnd to refer to the command being described.
* Use _cmnd(basename) to refer to another command. Note that
basename does not include any prefix, it is added automatically
by the _cmnd() macro.
* Use _const(basename) to refer to a constant. Note that
basename does not include any prefix, it is added automatically
by the _const() macro.
* Use _hex(value) to refer to a hexidecimal value.
(This should not be required very often in the Open GL.)
* List commands in the see also section in alphabetical order.
Include commands that return all the state that is set by
the command being documented.
Limitations of the alpha release:
* The header, command syntax, parameter descriptions, and see
also sections will be complete.
* The command description may not be complete, but it will at
least exist.
* The example section may not exist.
|
