Manualguidelines.Html

INKSCAPE MANUAL : GUIDELINES FOR AUTHORS AND TRANSLATORS

Style Guide

This Manual of Style has the simple purpose of making things easy to read by following a consistent format — it is a style guide. The following rules don't claim to be the last word. One way is often as good as another, but if everyone does it the same way, user documentation will be easier to read and use, not to mention easier to write and edit. In this regard the following quote from The Chicago Manual of Style deserves notice:

   "Rules and regulations such as these, in the nature of the case, cannot be endowed 
   with the fixity of rock-ribbed law. They are meant for the average case, and must 
   be applied with a certain degree of elasticity."

(Above quoted from Wikipedia:Manual Of Style)

• Refer to the terms defined at Inkscape Terminology
• Use good writing and documentation practices and maintain a neutral point of view
• Write in a platform and hardware agnostic view, delineate differences where appropriate in a neutral way
• Do not use first or second person pronouns, i.e, I, you, etc.
• Refer to users as "Inkscape artists" or simply, "artists"
• Remain consistent in terminology
• Keys on the keyboard are never "button" they are always "key"
• The Control key should be written "Ctrl"
• Key combinations should be written "Ctrl+Alt+Shift+<key>"
• Tool names capitalize each word before "tool" but "tool" is not a proper noun and is not capitalized
• A panel in the Document window is a "bar" (Tool Controls bar) and is not concatenated with the name, (i.e., "Status bar" not "Statusbar")
• A "dialog" is a confirmation window, while other option dialogs are referred to as "window," and "window" is not capitalized
• Refer to Menu selections with the ">" separator, a users "selects" a Menu "option" (or "command") and where possible include the keyboard shortcut in parentheses immediately after. For example: "...and then select Path>Object To Path (Shift+Ctrl+C) or if the..." It is not desirable to use the "/" character to denote levels of the Menu since / appears in the Menu and > does not. Capitalize each Menu option.

Help file should be minimally structured to make it easy to use and comprehend. We propose that each page should be structured according to the base:

  1. Tool Name or Page Theme name
  2. Image (screenshot of a dialog ...)
  3. Methods for tool activation, eventually with step by step demonstration
  4. Keydings, modifiers , eventually with step by step demonstration
  5. Tool options, eventually with a screenshot of the Dialog, and , eventually with step by step demonstration
  6. Additionnal Information
  7. Links to other related pages

DocBook

We have decided to use, for good compliance, the most popular documentation system present in OpenSource. Help file may be written in Docbook (the XML one) format, that can be converted with different tools. For more informations, follow the links placed at the end of this page.

Help Structure

The Manual should be one unique big XML file, in which content can be separated in multiple included files by mean of entities. Each one of the included files will treat a unique point (a tool for example) and may have at least one link to access to it. Each one should also begin with the

<sect1>

root element to keep the hierarchy of the content. This root element can be changed into

<sect2>

in case of use of intermediate index (for example, some dialogs are full of options or manipulations advises that justify to have an index for its own).

Help file should be minimally structured to make it easy to use and comprehend. We propose that each page should be structured according to the base:

  1. Tool Name or Page Theme name
  2. Image (screenshot of a dialog ...)
  3. Methods for tool activation, eventually with step by step demonstration
  4. Keydings, modifiers , eventually with step by step demonstration
  5. Tool options, eventually with a screenshot of the Dialog, and , eventually with step by step demonstration
  6. Additionnal Information
  7. Links to other related pages

DocBook Tags

Please, have a look at the Docbook Advice page and to the Websites listed below.

We also ask that contributors make a good use of indentation, in order to have more readable and useable source files.

  1. Each tag containing visitor-readable-text should be placed on a new line with an additional indent;
  2. Open and close tag of an element should be placed in the same indent.

Useful (Necessary for newbies to Docbook!!) Links

   * [|Wiki Gimp Proposing advises in creating help file with Docbook]
   * [|Docbook Site]
   * [|Norman Walsh's WebSite, very complete about Docbook]
   * [|Tools for Docbook transformations]
   * [|Advises for creating KDE compliant help files]