The DocBook rules are strict and must be maintained in order for the manual to build using xsltproc. However, there are some rules we like to follow to make editing the manual more efficient and organized.
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 beging 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. 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.
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.