Difference between revisions of "DocumentationStandards"

From Inkscape Wiki
Jump to navigation Jump to search
 
(13 intermediate revisions by 2 users not shown)
Line 2: Line 2:


=DocBook tags we should use=
=DocBook tags we should use=
(official definitions can be found [http://www.docbook.org/tdg5/en/html/ here])
*<book> - main tag encapsulating the whole book
*<book> - main tag encapsulating the whole book
*<part> - For larger sections (e.g. "Menus", etc; should only be a few of these in the book)
*<part> - For larger sections (e.g. "Menus", etc; should only be a few of these in the book)
Line 7: Line 8:
*<section> - subsections of a chapter (e.g. "Save" menu item)
*<section> - subsections of a chapter (e.g. "Save" menu item)
*<para> - encapsulating any subsection of a chapter that needs a distinction from the preceeding and proceeding text (textual paragraphs, text content withing each list item or procedural item, etc)
*<para> - encapsulating any subsection of a chapter that needs a distinction from the preceeding and proceeding text (textual paragraphs, text content withing each list item or procedural item, etc)
*<formalpara> to replace <simplesect> - paragraphs with titles
*<formalpara> (to replace <simplesect>) - paragraphs with titles (uses <title> tag)
*<guimenuitem> (guimenuitem accel accel guimenuitem) -  is for final menu, for example "save as" in the "file  <guimenu>
*<guimenu> - a top-level menu (such as "File")
*<guisubmenu> - any sub-menu of another menu
*<guimenuitem> (guimenuitem accel accel guimenuitem) -  is for a terminal item on a menu (for example "save as" in the "File" menu)
*<guilabel> - stands for any label at any places : Fill at the bottom or X property ...
*<guilabel> - stands for any label at any places : Fill at the bottom or X property ...
*<emphasis> -
*<accel> - a key used with a meta key for key commands (e.g. "s" when you hit "ctrl+s" to do a quick save)
*<accel> - ?
*<emphasis> used for emphasizing text - WHEN SHOULD THIS BE USED?
*<keycap> - ?
*<keycap> - the actual label of a key on the keyboard (usage: probably used within <keycombo> tags most often)
*<keycombo> - standard key combination for a command (keycombo is to define a key combination for ex Ctrl+S where Ctrl is a keycap and S another one)
*<keycombo> - standard key combination for a command (e.g. "ctrl+s" would be marked up as <keycombo><keycap>Ctrl</keycap><keycap>S</keycap></keycombo>)
* i would also keep accel, keycap, and keycombo which are different ways of reaching a command, and having them it is also easy to build a accel list, keycombo list.
*<mediaobject> - a wrapper for media (if multiples media objects are included in the same tag, only one is shown, depending on the displaying system) (see below)
*tag-tree for pictures especially screenshots and icons (for tools and cursors) (maybe http://www.docbook.org/schemas/sdocbook/elements.html?)
*<imageobject> - a wrapper for an image file (see below)
*<imagedata> - pointer to the image file (used with "fileref" attribute, see below)
*caption> - brief but specific description of an image
*<guiicon> - points to an application icon image file (see below)
*<inlinemediaobject>
*<itemizedlist>
*<listitem>
*<procedure>
*<step>
*<variablelist>
*<varilistentry>
 
=Usages=
 
*tag-tree for pictures especially screenshots and icons (for tools and cursors)  
**mediaobject imageobject imagedata fileref="" imageobject mediaobject
**mediaobject imageobject imagedata fileref="" imageobject mediaobject
(+caption = légende)
*** caption - légende
**guiicon inlinegraphic fileref="" guiicon
**guiicon inlinegraphic fileref="" guiicon
*tag for index : indexeterm primary secondary indexterm
*indexeterm primary secondary indexterm - tag for index
*itemizedlist listitem para listitem itemizedlist
*itemizedlist listitem para listitem itemizedlist
*procedure step step procedure
*procedure step step procedure
*variablelist varilistendry => ?????????? what's that ?
*variablelist varilistentry => ?????????? what's that ?
 
maybe http://www.docbook.org/schemas/sdocbook/elements.html?
http://live.gnome.org/ProjectMallard - not much there


=Basic Structure of a Part=
=Basic Structure of a Part=
Line 48: Line 62:
=Miscellany=
=Miscellany=
* Links to sections should be named the same as the section title, except don't use caps and replace all spaces with dashes, e.g., the link for section "Menu Bar" would be "menu-bar".
* Links to sections should be named the same as the section title, except don't use caps and replace all spaces with dashes, e.g., the link for section "Menu Bar" would be "menu-bar".
=References=
Simplified DockBook - http://www.docbook.org/schemas/sdocbook/elements.html
Gnome project standards project - not much there yet as it's developing - http://live.gnome.org/ProjectMallard

Latest revision as of 20:22, 20 November 2007

Here is a list of proposals for documentation standards for the User Manual (most important for DocBook xml and content)

DocBook tags we should use

(official definitions can be found here)

  • <book> - main tag encapsulating the whole book
  • <part> - For larger sections (e.g. "Menus", etc; should only be a few of these in the book)
  • <chapter> - subsections of a part (e.g."File" menu)
  • <section> - subsections of a chapter (e.g. "Save" menu item)
  • <para> - encapsulating any subsection of a chapter that needs a distinction from the preceeding and proceeding text (textual paragraphs, text content withing each list item or procedural item, etc)
  • <formalpara> (to replace <simplesect>) - paragraphs with titles (uses <title> tag)
  • <guimenu> - a top-level menu (such as "File")
  • <guisubmenu> - any sub-menu of another menu
  • <guimenuitem> (guimenuitem accel accel guimenuitem) - is for a terminal item on a menu (for example "save as" in the "File" menu)
  • <guilabel> - stands for any label at any places : Fill at the bottom or X property ...
  • <accel> - a key used with a meta key for key commands (e.g. "s" when you hit "ctrl+s" to do a quick save)
  • <emphasis> used for emphasizing text - WHEN SHOULD THIS BE USED?
  • <keycap> - the actual label of a key on the keyboard (usage: probably used within <keycombo> tags most often)
  • <keycombo> - standard key combination for a command (e.g. "ctrl+s" would be marked up as <keycombo><keycap>Ctrl</keycap><keycap>S</keycap></keycombo>)
  • <mediaobject> - a wrapper for media (if multiples media objects are included in the same tag, only one is shown, depending on the displaying system) (see below)
  • <imageobject> - a wrapper for an image file (see below)
  • <imagedata> - pointer to the image file (used with "fileref" attribute, see below)
  • caption> - brief but specific description of an image
  • <guiicon> - points to an application icon image file (see below)
  • <inlinemediaobject>
  • <itemizedlist>
  • <listitem>
  • <procedure>
  • <step>
  • <variablelist>
  • <varilistentry>

Usages

  • tag-tree for pictures especially screenshots and icons (for tools and cursors)
    • mediaobject imageobject imagedata fileref="" imageobject mediaobject
      • caption - légende
    • guiicon inlinegraphic fileref="" guiicon
  • indexeterm primary secondary indexterm - tag for index
  • itemizedlist listitem para listitem itemizedlist
  • procedure step step procedure
  • variablelist varilistentry => ?????????? what's that ?

Basic Structure of a Part

  • title+Intro+screenshot+Activation+Procedure+Additional infos+Links

<part> <title></title>

<chapter> <title></title>
 <section> <title></title>
  <indexterm> <primary></primary><secondary></secondary></indexterm> (here or after ?)
  <formalpara> <title></title>
   <mediaobject> <imageobject><imagedata firelef="url/"></imageoject>

</mediaobject> <para></para> <itemizedlist><listitem><para></para></listitem></itemizedlist> <emphasis></emphasis> </section> <chapter> </part>

Miscellany

  • Links to sections should be named the same as the section title, except don't use caps and replace all spaces with dashes, e.g., the link for section "Menu Bar" would be "menu-bar".

References

Simplified DockBook - http://www.docbook.org/schemas/sdocbook/elements.html

Gnome project standards project - not much there yet as it's developing - http://live.gnome.org/ProjectMallard