HACKING

   1 ===============
   2  Hacking Guide
   3 ===============
   4
   5 1. Introduction
   6
   7   The GIMP documentation project is mainly working with docbook xml files
   8   to create the GIMP manual / online help.  Since there are different
   9   approaches how to create and edit such files as well as different tools
  10   involved, there is a strong need for the xml files being well formated.
  11   Additionally there are a couple of technical reasons (diff, cvs) that
  12   suggest a general styleguide for the xml files.  This is a recommendation
  13   for such a styleguide. Its mainly based on the styles that can be found
  14   in xml files that build the current documentation, as well as on the
  15   discussion on the gimp-doc mailing list.
  16
  17 2. XML styleguide by rules
  18   §1. General
  19   §1.1. All docbook files for the documentation need to be well formed and
  20     have to comply validation against
  21     http://www.docbook.org/xml/4.3/docbookx.dtd.
  22   §1.2. All docbook files use UTF-8 character encoding.
  23
  24   §2. Length of lines
  25   §2.1. The length of line should not exceed 78 characters. Exceptions
  26     might be made for text that is technically not able to be wrapped
  27     (chinese text does rarely contain space characters, so it can't be
  28     wrapped without introducing unwanted whitespaces) and attributes of
  29     elements.
  30
  31   §3. Elements and new lines
  32   §3.1. Element tagnames are written lowercase completely
  33   §3.2. All tags (opening and closing) are starting a new line. For
  34     exceptions see §3.3
  35   §3.3. Elements listed in Appendix I (inline elements) do not have the
  36     opening and closing tags on new lines, as long as their content does not
  37     exceed 78 characters.
  38
  39   §4. Element attributes
  40   §4.1. Element attributes are written completely lowercase
  41   §4.2. Element attributes values are enclosed in double quotes ( " )
  42   §4.3. The languages encoded in the lang attributes appear in alphabetical
  43     order of the language codes
  44
  45   §5. Indention
  46   §5.1. Space or tab characters can be used for indentation, but it is higly
  47     recommended not to mix space and tab character usage in one single xml
  48     file.
  49   §5.2. Indention width is two spaces (0x20). One tab (0x09) is equivalent
  50     to 8 spaces (0x20).
  51   §5.3. Indention is done for the content of all tags that start a new line
  52
  53 2 XML styleguide by example
  54   Example for §1 General
  55   Following the rules in §1 each xml file of the GIMP manual starts with:
  56
  57   <?xml version='1.0' encoding='UTF-8'?>
  58   <!DOCTYPE abcd
  59   PUBLIC '-//OASIS//DTD DocBook XML V4.3//EN'
  60   'http://www.docbook.org/xml/4.3/docbookx.dtd'>
  61
  62   where abcd is the root element of the file (usually book, sect1 of sect2).
  63
  64   Example for §2. Length of lines
  65   // to be done
  66
  67   Example for §3. Elements and new lines
  68   // to be done
  69
  70   Example for §4. Element attributes
  71   // to be done
  72
  73   Example for §5. Indention
  74   // to be done
  75
  76 Appendix I Inline elements
  77   <abbrev>
  78   <accel>
  79   <acronym>
  80   <action>
  81   <anchor>
  82   <application>
  83   <citation>
  84   <citerefentry>
  85   <citetitle>
  86   <classname>
  87   <command>
  88   <computeroutput>
  89   <constant>
  90   <database>
  91   <email>
  92   <emphasis>
  93   <envar>
  94   <errorcode>
  95   <errorname>
  96   <filename>
  97   <firstterm>
  98   <footnote>
  99   <forignphrase>
 100   <function>
 101   <guibutton>
 102   <guiicon>
 103   <guilabel>
 104   <guimenu>
 105   <guimenuitem>
 106   <guisubmenu>
 107   <glossterm>
 108   <hardware>
 109   <inlineequation>
 110   <inlinegraphic>
 111   <interface>
 112   <interfacedefinition>
 113   <keycap>
 114   <keycode>
 115   <keycombo>
 116   <keysym>
 117   <link>
 118   <literal>
 119   <markup>
 120   <medialabel>
 121   <menuchoice>
 122   <mousebutton>
 123   <msgtext>
 124   <olink>
 125   <option>
 126   <optional>
 127   <parameter>
 128   <phrase>
 129   <prompt>
 130   <property>
 131   <quote>
 132   <replacable>
 133   <returnvalue>
 134   <shortcut>
 135   <structfield>
 136   <structname>
 137   <subsrcipt>
 138   <superscript>
 139   <symbol>
 140   <systemitem>
 141   <token>
 142   <trademark>
 143   <type>
 144   <ulink>
 145   <userinput>
 146   <varname>
 147   <wordasword>
 148   <xref>