doc/source/Hacking.txt

   1 Hacking the Docs\r
   2 ================\r
   3 \r
   4 While you are working on the docs, please oberve the following rules for your markup.\r
   5 The markup is processed by XSL Transformations, FO Processors and the like. Always\r
   6 remember that you define the structure and leave the formatting to the processors\r
   7 For more information about tags in docbook read http://www.docbook.org/tdg/index.html.\r
   8 If you want to translate the german or french docs you have to enable UTF-8 BOM's in \r
   9 your editor.\r
  10 \r
  11 Rules\r
  12 =====\r
  13 - Separate XML tags from content\r
  14   In most cases, the XML tag should be included on a line by itself,\r
  15   and the content should be indented, eg.\r
  16   <para>\r
  17         Contents of the paragraph, which\r
  18         may span several lines or just one.\r
  19   </para>\r
  20   Some tags are only used for a few words, eg. <emphasis> and these\r
  21   may be included inline. But please do not break such a tag over\r
  22   a line boundary. eg <emphasis>NOT\r
  23   </emphasis> like this.\r
  24   \r
  25 - Use leading tabs, not spaces\r
  26   Please set up your editor NOT to expand tabs to spaces. If anyone\r
  27   else views the file with different tab settings it will look a mess.\r
  28   Recommended tab setting for viewing is 4 spaces.\r
  29 \r
  30 - Avoid very long lines\r
  31   Most of the files have kept line length to within 80 characters when\r
  32   viewed at tabstop=4, although this is not rigidly adhered to. Using\r
  33   very long lines just makes the file harder to read and edit.\r
  34 \r
  35 - Emphasis\r
  36   Don't use capitalization to emphasize,\r
  37   use <emphasis>Important</emphasis> instead\r
  38 \r
  39 - Key / Mouse Actions\r
  40   If you want to say: "Press Alt-A to abort", use the following markup:\r
  41   Click on <action>ALT+A</action> to abort\r
  42   If you want to say: "Do a right click to abort", use the following markup:\r
  43   Do a <action>right click</action> to abort\r
  44   For consistency, please use 'left click' instead of 'left-click' or\r
  45   'leftclick'. The same applies to 'right click' and 'double click'.\r
  46 \r
  47 - Gui Buttons\r
  48   If you want to say: "Click on OK to continue", use the following markup:\r
  49   Click on <guibutton>OK</guibutton> to continue\r
  50 \r
  51 - Gui Menus\r
  52   If you want to say: "Select Commit from the TortoiseGit menu", use the following\r
  53   markup, with layout shown:\r
  54   Select\r
  55   <menuchoice>\r
  56         <guimenu>TortoiseGit</guimenu>\r
  57         <guimenuitem>Commit</guimenuitem>\r
  58   </menuchoice>\r
  59 \r
  60   For context menus within TSVN dialogs, use this markup:\r
  61   <menuchoice>\r
  62         <guimenu>Context Menu</guimenu>\r
  63         <guimenuitem>Commit</guimenuitem>\r
  64   </menuchoice>\r
  65   \r
  66 - Gui Labels / Fields\r
  67   If you want to say: "Select the URL from the URL Combobox", use the following markup:\r
  68   "Select the URL from the <guilabel>URL</guilabel> Combobox"\r
  69 \r
  70 - User input, system output and properties are marked with <literal> like: \r
  71   "Enter <literal>something</literal> to continue"\r
  72   "The <literal>svn:ignore</literal> property"\r
  73 \r
  74 - Typing on a command line is marked with <command> like:\r
  75   "Enter <command>DIR/W</command> at the command prompt.\r
  76 \r
  77 - Multiline input/output or file content is marked using <screen>.\r
  78   Note that any leading spaces are also included in the formatting,\r
  79   so this text normally appears hard against the left margin in the\r
  80   XML source file. The <screen> tag should also be left aligned. eg.\r
  81   the content of the Apache config file is shown as follows:\r
  82 <screen>\r
  83 &lt;Location /svn&gt;\r
  84 DAV svn\r
  85 SVNParentPath D:\SVN\r
  86 AuthType Basic\r
  87 AuthName "Git repositories"\r
  88 AuthUserFile passwd\r
  89 #AuthzSVNAccessFile svnaccessfile\r
  90 Require valid-user\r
  91 &lt;/Location&gt;\r
  92 </screen>\r
  93 \r
  94 - Figures (graphics) should use a format like this:\r
  95   <figure id="tsvn-DUG-settings-dia-1">\r
  96         <title>The Settings Dialog, Main Tab</title>\r
  97         <graphic fileref="images/SettingsMain.png"/>\r
  98   </figure>\r
  99 \r
 100 - Links:\r
 101   Use this <xref linkend="tsvn-DUG-import-4"/> to reference internal sections.\r
 102   Use ulink for external links. This should be formatted as\r
 103   as shown below:\r
 104   <ulink url="http://svnbook.red-bean.com/">\r
 105         <citetitle>SVN book</citetitle>\r
 106   </ulink>.\r
 107 \r
 108 - A list of bullet points is declared as follows:\r
 109   <itemizedlist>\r
 110         <listitem>\r
 111                 paragraphs in point 1\r
 112         </listitem>\r
 113         <listitem>\r
 114                 paragraphs in point 2\r
 115         </listitem>\r
 116   </itemizedlist>\r
 117   Each paragraph should be enclosed in <para> tags.\r
 118 \r
 119 - A numbered list is declared as follows:\r
 120   <orderedlist>\r
 121         <listitem>\r
 122                 paragraphs in point 1\r
 123         </listitem>\r
 124         <listitem>\r
 125                 paragraphs in point 2\r
 126         </listitem>\r
 127   </orderedlist>\r
 128   Each paragraph should be enclosed in <para> tags.\r
 129 \r
 130 - A list with headings for each item is declared as follows:\r
 131   <variablelist>\r
 132         <varlistentry>\r
 133                 <term>First heading</term>\r
 134                 <listitem>\r
 135                         paragraphs in point 1\r
 136                 </listitem>\r
 137         </varlistentry>\r
 138         <varlistentry>\r
 139                 <term>Second heading</term>\r
 140                 <listitem>\r
 141                         paragraphs in point 2\r
 142                 </listitem>\r
 143         </varlistentry>\r
 144   </variablelist>\r
 145   Each paragraph should be enclosed in <para> tags.\r
 146 \r
 147 - Mark Filenames with <filename>Hacking.txt</filename>\r
 148   Note this also applies to executables when the reference includes the .exe extension.\r
 149 \r
 150 - Mark URLS with <systemitem class="url">file:///C:/SVNRepository/</systemitem>\r
 151 \r
 152 - Place markers where you want an index entry to point to:\r
 153   <indexterm>\r
 154         <primary>text to go in index</primary>\r
 155   </indexterm>\r
 156 \r
 157 - Avoid quotes (" or ').\r
 158   Use <literal> instead, because normally you refer to input or output text.\r
 159   If you really want to quote something, use <quote>Hello, world</quote>.\r
 160   Using literal quote characters can cause 'overflow' errors during\r
 161   formatting.\r
 162 \r
 163 - Don't use literal '<' and '>' marks\r
 164   The XML interpreter will get confused as they look like tag chars.\r
 165   Use &lt; for < and &gt; for >\r
 166   \r
 167 Use the out of line info boxes:\r
 168 ===============================\r
 169 like:\r
 170 <important>\r
 171 <tip>\r
 172 <caution>\r
 173 <warning>\r
 174 \r
 175 if you want to inform the reader about something special.\r
 176 \r
 177 Special markers for translation\r
 178 ===============================\r
 179 Some tags are marked like this:\r
 180 <entry condition="pot">:about</entry>\r
 181 \r
 182 The condition="pot" prevents the strings from being extracted into the .pot file,\r
 183 so that nobody translates them. Mostly these strings will have some feature\r
 184 such as a leading colon, slash, dot or dollar. Those chars have to stay there to\r
 185 prevent these strings from being translated if the po file "by chance" contains\r
 186 a matching translation.\r
 187 \r
 188 Be careful using this attribute. It must only be applied at paragraph level,\r
 189 not inline, otherwise the translation process will break.\r
 190 \r
 191 Add To this Document\r
 192 ====================\r
 193 Please add missing stuff to these docs and correct errors.\r
 194 \r
 195 Cheers\r
 196 -Lübbe\r