wiki:WritingDocBook

Writing DocBook

The books in thisr epository are written in DocBook, an XML-based format for structuring documentation and books. The version of DocBook used is 4.5.

All the DocBook tags you can use are listed and structured in the Logical Divisions section of DocBook: The Definitive Guide. You can find a good description of typical usage of some tags in Using DocBook Lite, a document from O'Reilly for their book authors.

Style guide

Here are common tips, DOs andDON'Ts about writing DocBook docs for the WordPress documentation.

  • Use the available entities, wherever possible (complete list is in the entities.ent file).
  • Don't use a standard itemized list, when you have terms and their definitions. Use a variablelist, instead.
  • Wrap URLs in <systemitem>
  • Use &exurl; and &exdomain; for example blog URLs. Here is an example: <systemitem>&exurl;/wp-admin/import.php</systemitem>. This will produce <systemitem>http://example.com/wp-admin/import.php</systemitem>
  • Don't use a single quote, when you mean an apostrophe. Use &rsquo;.
  • Wrap main menu groups in <guimenu>, main menu items in <guimenuitem> and menuchoices (e.g. Settings > General) in menuchoice tags.
  • Use xref for internal links, whenever possible. If you don't link to titleless entity (like a paragraph), use a link. For external links, use ulink.
  • Wrap filenames (wp-config.php, .htaccess) in a <filename>.
  • Use typographically correct dashes.
  • Construct the IDs of the elements using the following pattern: "chapterid.sect1id.sect2id.sect3id....". For identifiers for sections use lowercase words, or phrases separated by dashes (not underscores). Example id for <sect3>: content.links.categories.manage.
  • Never be afraid to consult the DocBook definitive guide, consult the source or file a ticket.
Last modified 9 years ago Last modified on 02/13/09 14:52:27