We recommend writing the manual with bluefish. It has most of the tags used in the manual in the DocBook custom menu. By unchecking the Use spaces to indent, not tabs and checking Word wrap default in the Preferences Editor panel, you will ensure that no unnecessary white space will be produced when processing the files.
The DocBook rules are strict and must be maintained in order for the manual to build using xsltproc
. Thus, you should always validate the whole book before sending or committing any change. To do it, just issue:
$ make validate-all
in the bluefish-doc/src
directory.
However, there are some rules we like to follow to make editing the manual more efficient and organized.
We use id
on chapter, appendix, section, figure, and procedure. This provides a convenient way to reference them in the text as well and to get them listed in the table of contents.
If you need to reference some chunk of text embedded in a tag different from those already mentionned, you can also use an id on this tag, since DocBook allows id on all tags.
Separate words in the id
with hyphens.
Finally, include a word or two describing the content in the section. For example, a chapter entitled Using Bluefish
would have the id bluefish-using. And, a section within that chapter called Keyboard Shortcuts
could have the name bluefish-using-shortcuts.
The main thing is that all id's must be unique or processing will fail. To ensure that all id's are unique, just run make validate-all before committing the changes.
Also, be careful when renaming id's, since the name could be used in links within other parts of the manual. It is best to do a global search for an id in all the manual's files before changing an id.
All screen shots are png files. They should be placed in the bluefish-doc/src/figures
directory. They are inserted in the xml files with the following tags:
<para> <figure id="figure-file-menu"> <title id="figure-file-menu-title">Bluefish File Menu</title> <screenshot> <mediaobject> <imageobject> <imagedata fileref="figures/file_menu.png" format="PNG"/> </imageobject> <textobject> <phrase>A screen shot of the Bluefish File Menu</phrase> </textobject> </mediaobject> </screenshot> </figure> </para>
Notice that the figure id
, the title id
, and the imagedata fileref
are very similar. The former ones use hyphens, while the later uses underscore to separate the id
parts. They have in common the significant part. Do not forget to put in the phrase
tag, a sentence meaningful for blind people.
We use the following DocBook GUI tags:
Interface elements
<keycombo> <keycap>Ctrl</keycap> <keycap>S</keycap> </keycombo>
<guimenu>File</guimenu>
<menuchoice> <guimenu>File</guimenu> <guimenuitem>Open...</guimenuitem> </menuchoice>
<menuchoice> <guimenu>Edit</guimenu> <guisubmenu>Replace special</guisubmenu> </menuchoice>
<menuchoice> <shortcut> <keycombo> <keycap>Ctrl</keycap> <keycap>O</keycap> </keycombo></shortcut> <guimenu>File</guimenu> <guimenuitem>Open...</guimenuitem> </menuchoice>
<guilabel>Use spaces to indent, not tabs</guilabel>
When you want to explain some process, use procedures; this way, the user benefits of a clear step by step guidance:
<procedure id="installing-docbook-xsl"> <title>Installing docbook-xsl</title> <step> <para>Install them for your distribution</para> </step> <step> <para>Put a copy ... <filename>bluefish-doctools/tools</filename></para> </step> </procedure>
If the explanation consists mainly in orders, you may want to use ordered list instead.
Be aware that DocBook is picky about their usage inside variable list: you can put them either just after the title or inside a list item. They are used as follows:
<warning> <para>You have to keep in mind...</para> </warning>
To reference an external link, we use:
<ulink url="http://www.sourceforge.net">http://www.sourceforge.net</ulink>
Or:
<ulink url="http://xmlsoft.org/XSLT/">libxslt</ulink>
To reference an internal link (i.e. internal to the book), we use:
<xref linkend="getting-bluefish-updates"/>
This generates a linked text similar to "the section called ...". This is the preferred form, but it may not be always suitable; in this case, you can use:
<link linkend="getting-bluefish-updates">here</link>
To reference a chapter by number, we use:
Chapter <xref linkend="getting-bluefish" role="template:%n"/>
To highlight command line tools or small applications, we use:
<command>make</command>
To emphasize file or directory names, we use:
<filename>make</filename>
For user's instructions, use either:
<screen>$ make install</screen>
or:
Run the command <userinput>make</userinput>
Be aware that the former is shown alone on its proper line, while the latter is embedded within the line flow. If you use the screen
tag, you should prepend either a $
or a #
followed by a space before the instruction, depending on how the command should be run, as non root for the former, as root for the latter. Moreover, with the screen
command, we should check that the line is not too long, split it if needed, and add a backslash to indicate the splitting.
To embed chunk of code, we use:
<programlisting> <![CDATA[ Run the command <userinput>make</userinput>]]> </programlisting>
As a workaround a bug in fop, we use a special processing instruction to insert page breaks for PDF production. If the break is the same for A4 and USLetter format, the instruction is:
<?pagebreak?>
If it is only for A4 format, the instruction is:
<?pagebreaka4?>
Likewise for USLetter format only, it is:
<?pagebreakus?>
Similar processing instructions are used to insert line breaks for PDF production:
<?linebreak?> <?linebreaka4?> <?linebreakus?>
Do not use simplesect
as it messes the table of contents.
Avoid to add blank lines or unnecessary white spaces in the files, it may break the files production and has the disadvantage to increase the files size.
A chapter should at least contains an id
, a title
, and either a para
or section tag. Be aware that you cannot use an isolated para
tag after a section.
All list items should use a para
tag to embed their contents. If all of the items contents are very short, i.e. fit into one line, you may want to use the following attribute to suppress the additional line between items:
<itemizedlist spacing="compact">
The same applies to ordered lists.
Avoid contractions. Use you will instead of you'll.
Use the spell checker to correct any misspelling.
If you find errors in the manual, or just want to add more, please contact us. If you have questions on how to edit the manual that are not addressed in this appendix, you can always ask on the mailing list. Often, you can look to the chapter source to see how things are done.