Commit 94d11505 authored by Jacob Boerema's avatar Jacob Boerema
Browse files

Improve HACKING a bit

- Change maximum line length to 80
- Remove 3.3 since we handle languages separately in po files
- Small textual changes
parent 5fb3e1ea
Pipeline #289330 passed with stage
in 4 minutes and 2 seconds
......@@ -4,14 +4,14 @@
1. Introduction
The GIMP documentation project is mainly working with 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 being well formatted.
Additionally there are a couple of technical reasons (diff, cvs) that
suggest a general style guide for the xml files. This is a recommendation
for such a style guide. Its mainly based on the styles that can be found
in xml files that build the current documentation, as well as on the
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
......@@ -23,33 +23,31 @@
§1.2. All docbook files use UTF-8 character encoding.
§2. Length of lines
§2.1. The length of line should not exceed 78 characters. Exceptions
§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
(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 lowercase completely
§3.2. All tags (opening and closing) are starting a new line. For
exceptions see §3.3
§3.3. Elements listed in Appendix I (inline elements) do not have the
opening and closing tags on new lines, as long as their content does not
exceed 78 characters.
§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 completely lowercase
§4.2. Element attributes values are enclosed in double quotes ( " )
§4.3. The languages encoded in the lang attributes appear in alphabetical
order of the language codes
§4.1. Element attributes are written all lowercase.
§4.2. Element attributes values are enclosed in double quotes ( " ).
§5. Indentation
§5.1. Space or tab characters can be used for indentation, but it is highly
recommended not to mix space and tab character usage in one single xml
file.
§5.2. Indentation width is two spaces (0x20). One tab (0x09) is equivalent
to 8 spaces (0x20).
§5.3. Indentation is done for the content of all tags that start a new line
§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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment