Difference between revisions of "DocumentationStandards"

From Inkscape Wiki
Jump to navigation Jump to search
Line 2: Line 2:


=DocBook tags we should use=
=DocBook tags we should use=
* maybe http://www.docbook.org/schemas/sdocbook/elements.html?
*<book> - main tag encapsulating the whole book
* http://live.gnome.org/ProjectMallard - not much there
*<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)


*book
(are we keeping these?)
*part
 
*chapter
*<guimenuitem> - ?
*section
*<guilabel> - ?
*para
*<emphasis> - ?
*<accel> - ?
*<keycap> - ?
*<keycombo> - standard key combination for a command
 
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
*title+Intro+screenshot+Activation+Procedure+Additional infos+Links
<part> <title></title>
<chapter> <title></title>
  <section> <title></title>
  <para></para>
  </section>
<chapter>
</part>


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

Revision as of 21:49, 12 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)

(are we keeping these?)

  • <guimenuitem> - ?
  • <guilabel> - ?
  • <emphasis> - ?
  • <accel> - ?
  • <keycap> - ?
  • <keycombo> - standard key combination for a command

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