HACKING 3.59 KB
Newer Older
1
2
3
4
===============
 Hacking Guide
===============

5
1. Introduction
6

Jacob Boerema's avatar
Jacob Boerema committed
7
8
9
10
11
12
13
14
  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
15
16
  discussion on the gimp-doc mailing list.

luzpaz's avatar
luzpaz committed
17
18
2. XML style guide by rules

19
20
21
22
23
24
25
  §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
Jacob Boerema's avatar
Jacob Boerema committed
26
  §2.1. The length of line should not exceed 80 characters. Exceptions
27
    might be made for text that is technically not able to be wrapped
Jacob Boerema's avatar
Jacob Boerema committed
28
    (Chinese text does rarely contain space characters, so it can't be
29
30
31
32
    wrapped without introducing unwanted whitespaces) and attributes of
    elements.

  §3. Elements and new lines
Jacob Boerema's avatar
Jacob Boerema committed
33
34
35
36
37
38
  §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.
39
40

  §4. Element attributes
Jacob Boerema's avatar
Jacob Boerema committed
41
42
  §4.1. Element attributes are written all lowercase.
  §4.2. Element attributes values are enclosed in double quotes ( " ).
43

luzpaz's avatar
luzpaz committed
44
  §5. Indentation
Jacob Boerema's avatar
Jacob Boerema committed
45
46
47
48
49
50
  §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.
luzpaz's avatar
luzpaz committed
51
52

3 XML style guide by example
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

  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

luzpaz's avatar
luzpaz committed
73
  Example for §5. Indentation
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
  // 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>
  <inlinegraphic>
  <interface>
  <interfacedefinition>
  <keycap>
  <keycode>
  <keycombo>
  <keysym>
  <link>
  <literal>
  <markup>
  <medialabel>
  <menuchoice>
  <mousebutton>
  <msgtext>
  <olink>
  <option>
  <optional>
  <parameter>
  <phrase>
  <prompt>
  <property>
  <quote>
luz.paz's avatar
luz.paz committed
132
  <replaceable>
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
  <returnvalue>
  <shortcut>
  <structfield>
  <structname>
  <subsrcipt>
  <superscript>
  <symbol>
  <systemitem>
  <token>
  <trademark>
  <type>
  <ulink>
  <userinput>
  <varname>
  <wordasword>
  <xref>