Difference between revisions of "DocumentationStandards"

From Inkscape Wiki
Jump to navigation Jump to search
Line 7: Line 7:
*<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
*<guimenuitem> (guimenuitem accel accel guimenuitem) -  is for final menu, for example "save as" in the "file  <guimenu>
*<guimenuitem> (guimenuitem accel accel guimenuitem) -  is for final menu, for example "save as" in the "file  <guimenu>
*<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 ...
*<accel> - ?
*<accel> - ?
*<emphasis> inline tag
*<emphasis> inline tag
*<keycap> - (keycombo keycap keycombo)
*<keycap> - (keycombo keycap keycombo)
*<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 (keycombo is to define a key combination for ex Ctrl+S where Ctrl is a keycap and S another one)  
*tag-tree for pictures especially screenshots and icons (for tools and cursors)  
*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
*indexeterm primary secondary indexterm - tag for index
*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 varilistentry => ?????????? what's that ?
*variablelist varilistentry => ?????????? what's that ?


maybe http://www.docbook.org/schemas/sdocbook/elements.html?
maybe http://www.docbook.org/schemas/sdocbook/elements.html?
http://live.gnome.org/ProjectMallard - not much there
http://live.gnome.org/ProjectMallard - not much there



Revision as of 21:13, 14 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

  • <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
  • <guimenuitem> (guimenuitem accel accel guimenuitem) - is for final menu, for example "save as" in the "file <guimenu>
  • <guilabel> - stands for any label at any places : Fill at the bottom or X property ...
  • <accel> - ?
  • <emphasis> inline tag
  • <keycap> - (keycombo keycap keycombo)
  • <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)
  • 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 ?

maybe http://www.docbook.org/schemas/sdocbook/elements.html?

http://live.gnome.org/ProjectMallard - not much there

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".