Commit 406c5fe2 authored by Daniel Egger's avatar Daniel Egger Committed by Daniel Egger
Browse files

Added hacking styleguide by Axel Wernicke <axel.wernicke@gmx.de>. Thanks

2005-05-13  Daniel Egger  <de@axiros.com>

	* HACKING: Added hacking styleguide by Axel Wernicke
	<axel.wernicke@gmx.de>. Thanks Axel.
	* AUTHORS: Mention Axel.
parent bc482d5f
......@@ -40,6 +40,7 @@ buildsystem, technical contributors:
* Daniel Egger :: Makefile stuff and initial project setup.
* Thomas Schraitle :: Technical consultancy.
* Chris Hbsch :: Technical consultancy.
* Axel Wernike :: Formatting styleguide.
proof reading:
--------------
......
2005-05-13 Daniel Egger <de@axiros.com>
* HACKING: Added hacking styleguide by Axel Wernicke
<axel.wernicke@gmx.de>. Thanks Axel.
* AUTHORS: Mention Axel.
2005-05-13 Jakub Friedl <jfriedl@suse.cz>
* src/dialogs/path-dialog.xml: small fixes in cs and en
......
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 formated.
Additionally there are a couple of technical reasons (diff, cvs) that
suggest a general styleguide for the xml files. This is a recommendation
for such a styleguide. Its mainly based on the styles that can be found
in xml files that build the current documentation, as well as on the
discussion on the gimp-doc mailing list.
2. XML styleguide 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 78 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 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.
§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
§5. Indention
§5.1. As character used to create indention space or tab characters can
be used, but it is higly recommended not to mix space and tab character
usage in one single xml file.
§5.2. Indention width is two spaces (0x20). One tab (0x09) is equivalent
to 8 spaces (0x20).
§5.3. Indention is done for the content of all tags that start a new line
2 XML styleguide 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. Indention
// 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>
<replacable>
<returnvalue>
<shortcut>
<structfield>
<structname>
<subsrcipt>
<superscript>
<symbol>
<systemitem>
<token>
<trademark>
<type>
<ulink>
<userinput>
<varname>
<wordasword>
<xref>
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