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
|
===============
Hacking Guide
===============
1. Introduction
The GIMP documentation project uses docbook xml files to create the GIMP
manual / online help. Since there are different approaches how to create
and edit such files as well as different tools involved, there is a strong
need for the xml files to be well formatted.
Additionally there are a couple of technical reasons (diff, git) that
suggest a general style guide for the xml files. This is a recommendation
for such a style guide. It is mainly based on the styles that can be found
in the xml files that build the current documentation, as well as on the
discussion on the gimp-doc mailing list.
2. XML style guide by rules
§1. General
§1.1. All docbook files for the documentation need to be well formed and
have to comply validation against
http://www.docbook.org/xml/4.3/docbookx.dtd.
§1.2. All docbook files use UTF-8 character encoding.
§2. Length of lines
§2.1. The length of line should not exceed 80 characters. Exceptions
might be made for text that is technically not able to be wrapped
(Chinese text does rarely contain space characters, so it can't be
wrapped without introducing unwanted whitespaces) and attributes of
elements.
§3. Elements and new lines
§3.1. Element tagnames are written all lowercase.
§3.2. All tags (opening and closing) start on a new line. For
exceptions see §3.3.
§3.3. Elements listed in Appendix I (inline elements) do not need to
start their opening and closing tags on a new line, as long as their
content does not exceed 80 characters.
§4. Element attributes
§4.1. Element attributes are written all lowercase.
§4.2. Element attributes values are enclosed in double quotes ( " ).
§5. Indentation
§5.1. Use only Space characters for indentation. Tab characters should not
be used.
§5.2. Indentation width is two spaces.
§5.3. Indentation is done for the content of all tags that start a new line.
§5.4. Indentation should be increased if an element is a child of the
previous element.
3 XML style guide by example
Example for §1 General
Following the rules in §1 each xml file of the GIMP manual starts with:
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE abcd
PUBLIC '-//OASIS//DTD DocBook XML V4.3//EN'
'http://www.docbook.org/xml/4.3/docbookx.dtd'>
where abcd is the root element of the file (usually book, sect1 of sect2).
Example for §2. Length of lines
// to be done
Example for §3. Elements and new lines
// to be done
Example for §4. Element attributes
// to be done
Example for §5. Indentation
// to be done
Appendix I Inline elements
<abbrev>
<accel>
<acronym>
<action>
<anchor>
<application>
<citation>
<citerefentry>
<citetitle>
<classname>
<command>
<computeroutput>
<constant>
<database>
<email>
<emphasis>
<envar>
<errorcode>
<errorname>
<filename>
<firstterm>
<footnote>
<forignphrase>
<function>
<guibutton>
<guiicon>
<guilabel>
<guimenu>
<guimenuitem>
<guisubmenu>
<glossterm>
<hardware>
<inlineequation>
<inlinemediaobject>
<interface>
<interfacedefinition>
<keycap>
<keycode>
<keycombo>
<keysym>
<link>
<literal>
<markup>
<medialabel>
<menuchoice>
<mousebutton>
<msgtext>
<olink>
<option>
<optional>
<parameter>
<phrase>
<prompt>
<property>
<quote>
<replaceable>
<returnvalue>
<shortcut>
<structfield>
<structname>
<subsrcipt>
<superscript>
<symbol>
<systemitem>
<token>
<trademark>
<type>
<ulink>
<userinput>
<varname>
<wordasword>
<xref>
|
