Man 1 apcs04
Please consider to edit the Manual 2!
How To edit the Wiki Manual| {{#if:4. Conventions for Writing this Manual| | ||
| Prev }} | }} | |
4. Conventions for Writing this Manual
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.
4.1. 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 mentioned, 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.
4.2. Using Screen shots
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.
4.3. 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>
4.4. 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.
Keep in mind that steps and ordered lists are automatically numbered, thus words such as first, then, etc. are useless.
4.5. Using notes, tips, warnings
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>
4.6. Using links
To reference an external link, we use:
<ulink url="http://www.sourceforge.net"/>
Or:
<ulink url="http://xmlsoft.org/XSLT/">libxslt</ulink>
]] Note that the first form produces in html and ps/pdf formats a clickable link with the url as text, while the second form produces in html format a clickable link with the url as underlying url and the text as viewable text, and in ps/pdf formats a clickable link with the text as text and add the url into brackets after the text, so that the url is not lost when printing on paper. Hence it is important to use the second form when the text does not match the url.
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: Section x.y.z “Getting Bluefish updates”. 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>
]] Note that you may have to prepend the appropriated article if needed.
To reference a chapter by number, we use:
Chapter <xref linkend="getting-bluefish" xrefstyle="template:%n"/>
4.7. Others tags
To highlight command line tools or small applications, we use:
<command>make</command>
To emphasize file names or directories, we use:
<filename>make</filename>
For user's instructions, use either:
<screen><prompt>$</prompt> 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?>
4.8. 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.
4.9. Contact us
If you find errors in the manual, or just want to add more, please bluefish-contact contact the manual's maintainer, as well as if you have questions on how to edit the manual that are not addressed in this appendix. Often, you can look to the sources to see how things are done.