Conventions for Writing this Manual

We recommend to use bluefish to write the manual. 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-gtk2/doc/source directory.

However, there are some rules we like to follow to make editing the manual more efficient and organized.

The id Attribute

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.

All id names should begin with the name of the book. In our case the main book file is bluefish.xml, so every id should begin with bluefish.

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's best to do a global search for an id in all the manual's files before changing an id.

Using Screen shots

All screen shots are png files. They should be placed in the bluefish-gtk2/doc/source/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.

Referencing Bluefish interface elements

We use the following DocBook GUI tags:

Interface elements

Isolated shortcut
<keycombo>
<keycap>Ctrl</keycap>
<keycap>S</keycap>
</keycombo>
Isolated menu

<guimenu>File</guimenu>
Menu with submenuitem

<menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Open...</guimenuitem>
</menuchoice>
Menu with submenu

<menuchoice>
<guimenu>Edit</guimenu>
<guisubmenu>Replace special</guisubmenu>
</menuchoice>
Menu with submenuitem and shortcut

<menuchoice>
<shortcut>
<keycombo>
<keycap>Ctrl</keycap>
<keycap>O</keycap>
</keycombo></shortcut>
<guimenu>File</guimenu>
<guimenuitem>Open...</guimenuitem>
</menuchoice>
Label

<guilabel>Use spaces to indent, not tabs</guilabel>

Using procedures

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.

Using notes, tips, warnings

As we need them in places where there are not supposed to be, we use the following workaround:

<variablelist>
<varlistentry>
<term><emphasis>Warning</emphasis></term>
<listitem>
<para>You have to keep in mind...</para>
</listitem>
</varlistentry>
</variablelist>

Using links

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

Others tags

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?>

Recommendation

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.

Producing the final files

You have the following options to make and remove the various files, which will be stored in the bluefish-gtk2/doc directory:

Options to make the Bluefish manual

make html

Produces the book in html format.

make pdf-a4

Produces the book in PDF format suitable for A4 paper.

make ps-a4

Produces the book in PostScript format suitable for A4 paper.

make pspdf-a4

Produces the PDF and PostScript versions for A4 paper.

make pdf-us

Produces the book in PDF format suitable for USLetter paper.

make ps-us

Produces the book in PostScript format suitable for USLetter paper.

make pspdf-us

Produces the PDF and PostScript versions for USLetter paper.

make all

Produces all versions of the book.

clean html

Produces the book in html format.

clean pdf-a4

Removes the book in PostScript format suitable for A4 paper.

clean ps-a4

Removes the book in PDF format suitable for A4 paper.

clean pdfps-a4

Removes the PDF and PostScript versions for A4 paper.

clean pdf-us

Removes the book in PDF format suitable for USLetter paper.

clean ps-us

Removes the book in PostScript format suitable for USLetter paper.

clean pspdf-us

Removes the PDF and PostScript versions for USLetter paper.

clean all

Removes all versions of the book.

make validate-all

Validate the whole book.

If you want to create a new format, you will have to make a copy of the titlepage-a4.xml and pdf-ps-a4.xsl files in the bluefish-doctools directory, rename them according to the new format, and modify them.

Contact us

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.