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

5
1. Introduction
6

7 8 9
  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
luzpaz's avatar
luzpaz committed
10
  involved, there is a strong need for the xml files being well formatted.
11
  Additionally there are a couple of technical reasons (diff, cvs) that
luzpaz's avatar
luzpaz committed
12 13
  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
14 15 16
  in xml files that build the current documentation, as well as on the
  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 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45
  §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

luzpaz's avatar
luzpaz committed
46
  §5. Indentation
47 48 49
  §5.1. Space or tab characters can be used for indentation, but it is higly
    recommended not to mix space and tab character usage in one single xml
    file.
luzpaz's avatar
luzpaz committed
50
  §5.2. Indentation width is two spaces (0x20). One tab (0x09) is equivalent
51
    to 8 spaces (0x20).
luzpaz's avatar
luzpaz committed
52 53 54
  §5.3. Indentation is done for the content of all tags that start a new line

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

  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
75
  Example for §5. Indentation
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 149 150
  // 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>