Last updated on 27-aug-2004
.
Copyright © 2001 Nokia Corporation
Written by Henri Ranki
This HOWTO gives a brief description on different documentation forms used in Affix project. This discusses the purpose of the documentation and how it should be written and edited.
Affix is a Bluetooth protocol stack for Linux platform. It contains the kernel part which do the job and the administration utilities that are used to manage Affix and your Bluetooth devices.
Affix web pages are located at http://affix.sourceforge.net. There you can find all the information you need for using and developing Affix. All the documentation describet in this HOWTO is there.
On web pages you also find links to other Bluetooth and Affix related sources in the Internet. This is the primary place to download Affix sources. The Sourceforge portal is not actively updated apart from mailing lists and bug reporting system.
To edit web pages you have to be a member of Affix development team and should have shell account at sourceforge. Then just log in and you'll find the sources for the web pages in /home/groups/a/af/affix/XXX directory.
Affix has two main manuals. One for end users and one for the developers. Both can be downloaded in pdf form Affix web pages. If you are new to Affix you should start by reading the end user manual that contains also installation instructions.
Noth of these documents are maintained in docbooc (XML) document. Docbook allows to produce many different documents from a single source (pdf, html, ps etc.).
The editing can be done by hand, but using an editor is highly recommended. One fairly good editor is XMLMind XML Editor. To produce the final document you should have docbook utilities installed. On Debian it is done easily with the following command:
apt-get install docbook-utils
This instals you a range of utilities needed to produce documents in different formats out of a docbook document. To produce pdf document say:
docbook2pdf file_name
Affix management utilities have man pages that briefly describes the usage. Man pages are produced from the Affix end user manual. Chapter seven in this manual is actual a set of reference entrys that can be converted to man page. Each utility makes one reference (see the document source).
To produce man pages you should install docbook2x package. then you can produce sources for man pages saying:
docbook2x-man Affix-enduser.xml
After this as root user copy all *.1 files to directory /usr/share/man/man1
FAQ document is maintained as a HTML document and located on Affix web pages. Collect here all the general simple information that is needed often.
The same instructions apply to editing FAQ than editing Affix web pages.
Affix project has two mailing lists that are open to all. Lists can be found at Sourceforge. There you can subscribe with lists.
Affix developers mailing list's address is affix-devel@lists.sourceforge.net and Affix support mailing list's address is affix-support@lists.sourceforge.net. Lists are moderated unless you are not subscriber.
To avoid double work and minimize the effort of updating documentation it is good idea to produce the API description direcly from the sources. The goal would be produce a docbook document that could be easily included in Affix technical documentation.
The problem is that it seems that there does'n not exist any simple document generator that could produce docbook XML. Doxygen is quite good. It can produce several formats, but the XML is not in valid Docbook format.
A compromise would be just to produce HTML documentation and put it on the web pages. The technical documentation could then be limited to architechtural description.
Affix-doc repository has a configuration file for doxygen documentation generator. To produce the API documentation first install Doxygen and checkout affix-doc source tree. Then you can run doxygen in the Affix source tree root directory. The format is: doxygen <configuration_file>
Doxygen produces also man pages of the API. To install these copy all the files from api_doc/man/man3/ directory to /usr/share/man/man3/. You need to be logged as root to do this.
For further information on Doxygen tags see http://www.stack.nl/~dimitri/doxygen/manual.html
Note! To include some file in the documentation you have to add the following header for it. The documented functions do not appear in the API documentation until this header is inserted in the file.
/*! \file btcore.h (name of the file where this header is)
\brief This is brief for the file.
Describe here more specific what does this file contain.
*/