| Developer GuideChapter 8. Documentation Tools Red Hat Enterprise Linux 6 has two documentation tools available to include documentation with a project. These are Publican and Doxygen. Publican a program is used to publish and process documentation through DocBook XML. In the process of publishing books, it checks the XML to ensure it is valid and in a publishable standard. It is particularly useful for publishing the documentation accompanying a newly created application. Publican has a vast number of commands and actions available, all of which can be found in the --help or --man pages. The most common ones are: buildConverts the XML files into other formats more suitable for documentation (PDF, HTML, HTML-single, for example). createcreate_brandpackagePackages the files of a book into an RPM ready to distribute.
8.1.2. Create a New DocumentUse the publican create command to create a new document including all the required files. There are a number of options available to append to the publican create. These are: --helpPrints a list of accepted options for the publican create command. --name Doc_NameSet the name of the book. Keep in mind that the title must contain no spaces. --lang Language_CodeIf this is not set, the default is en-US. The --lang option sets the xml_lang in the publican.cfg file and creates a directory with this name in the document directory. --version versionSet the version number of the product the book is about. --product Product_NameSet the name of the product the book is about. Keep in mind that this must contain no spaces. --brand brandSet the name of a brand to use to keep the look of the documents consistent.
Refer to --help for more options. Remember to change into the directory the book is to be created in before running publican create. This prevents the files and directories be added to the user's home directory. When a book is made, a number of files are created in the book's directory. These files are required for the book to be built properly and should not be deleted. They are, however, required to be edited for links (such as chapters) to work, as well as to contain the correct information regarding authors and titles etc. These files are: publican.cfgThis file configures the build options and always includes the parameters xml_lang (the language the book is in, en-US for example), type (the type of document, a book or a set, for example), and brand (the branding the document uses, found here: Section 8.1.6, "Brands". Red Hat, for example.). There are a number of optional parameters but these should be used cautiously as they can cause problems further on in areas like translation. A full list of these advanced parameters can be found in the Publican User Guide. The publican.cfg file is unlikely to be edited much beyond the initial creation. book_info.xmlThis file is the template of the book. It contains information such as the title, subtitle, author, publication number, and the book's ID number. It also contains the basic Publican information printed at the beginning of each publication with information on the notes, cautions, and warnings as well as a basic stylistic guide. This file will be edited often as every time a book is updated the publication number has to be incremented. Author_Group.xmlThis file is used to store information about the authors and contributors. Once initially set up it is unlikely further editing will be required unless a change of authorship occurs. Chapter.xmlThis file is an example of what the actual content will be. It is created as a place holder but unless it is linked in the Doc_Name.xmlDoc_Name.xml. When the book is built, the content of this file will form the content of the book. This specific file is unlikely to ever be edited but others like it will be edited constantly as content is changed, updated, added to or removed. Doc_Name.xmlThis file is the contents page of the publication. It contains a list of links to the various chapters a book is to contain. It will not actually be called 'Doc_Name' but will have whatever the title of the publication is in it's place (Developer_Guide.xml, for example). This will only be edited when new chapters are added, removed or rearranged. This must remain the same as Doc_Name.ent Doc_Name.entThis file contains a list of local entities. By default YEAR is set to the current year and HOLDER has a reminder to place the copyright owner's name there. As with Doc_Name.xmlDoc_Name.xml Revision_History.xmlWhen publican package is run, the first XML file containing a <revhistory> tag is used to build the RPM revision history.
8.1.3.1. Adding Media to DocumentationOccasionally it may become necessary to add various media to a document in order to illustrate what is being explained. To link to any of these files, use the following XML: <xi:include parse="text" class="edunwman1" href="extras/fork/fork1.c" xmlns:xi="http://www.w3.org/2001/XInclude" /> 8.1.4. Building a DocumentIn the root directory, first run a test build to ensure that all the XML is correct and acceptable by typing publican build --formats=chosen_format --langs=chosen_language. For example, to build a document in US English and as a single HTML page, run publican build --formats=html-single --langs=en-US. Provided there are no errors the book will be built into the root directory where the pages can be viewed to see if it has the look required. It is recommended to do this regularly in order to make troubleshooting as easy as possible. When creating a build to test for any bugs in the XML code, sometimes it may be useful to use the --novalid option. This skips over any cross-references and links that point to files or sections of the document that do not yet exist. Instead they are shown as three question marks (???). There are a number of different formats a document can be published in. These are: - html
An ordinary HTML page with links to new pages for new chapters and sections. - html-single
One long HTML page where the links to new chapters and sections at the top of the page directing the user further down the page, rather than to new page. - html-desktop
One long HTML page where the links to new chapters and sections are in a panel on the left side of the document, directing the user further down the page, rather than to a new page. - man
A man page for Linux, UNIX, and other similar operating systems. - pdf
A PDF file. - test
The XML is validated without actually creating a file for viewing. - txt
A single text file. - epub
An e-book in EPUB format. - eclipse
An Eclipse help plug-in.
8.1.5. Packaging a PublicationOnce the documentation is complete and can be built with no errors, run publican package --lang=chosen_language. This will output SRPM packages to tmp/rpm in the document's directory, and binary RPM packages will go to tmp/rpm/noarch in the document's directory. By default, these packages are named productname-title-productnumber-[web]-language-edition-pubsnumber.[build_target].noarch.file_extensionpublican.cfg. Brands are used in a similar way as templates in that they create a level of consistency in appearance, with aspects like matching logos, images and color schemes, across a range of documents. This can be particularly useful when producing several books for the same application or the same bundle of applications. In order to create a new brand, it must have a name and a language. Run publican create_brand --name=brand --lang=language_code. This will create a folder called publican-brand and place it in the publication's directory. This folder contains the following files: COPYINGPart of an SRPM package and containing the copyright license and details. defaults.cfgProvides default values for the parameters that can be set in publican.cfg. Specifications from this file are applied first before applying those in the publican.cfg file. Therefore, values in the publican.cfg file override those in the defaults.cfg file. It is best used for aspects that are routinely used throughout the documents but still allows writers to change settings. overrides.cfgAlso provides values for the parameters that can be set in publican-brand.spec. Specifications from this file are applied last, thus overriding both the defaults.cfg and the publican.cfg. It is best used for aspects the writers are not allowed to change. publican.cfgThis file is similar to the publican.cfg file for a publication in that it configures basic information for the brand, such as version, release number and brand name. publican-brand.specThis file is used by the RPM Package Manager to package the publication into an RPM. READMEPart of an SRPM package and providing a brief description of the package.
A subdirectory, named by the language code, is also placed in this directory and contains the following files: Feedback.xmlThis is generated by default to allow readers to leave feedback. Customize it to contain the relevant contact details or a bug reporting process. Legal_Notice.xml:Contains copyright information. Edit it to change the details of the chosen copyright license.
Two more subdirectories are within this directory. The images subdirectory contains a number of images of both raster (PNG) and vector (SVG) formats and serve as place holders for various navigation icons that can be changed by replacing the images. The css folder contains overrides.css, which sets the visual style for the brand, overriding those in common.css. In order to package the new brand ready for distribution, use the publican package command. By default this creates source RPM packages (SRPM Packages) but it can also create binary RPM packages using the option --binary. Packages are named publican-brand-version-release.[build_target].[noarch].file_extensionpublican.cfg file. SRPM packages have the file extension .src.rpm while binary RPM packages have the file extension .rpm Binary RPM packages include [build_target].noarch before the file extension, where [build_target] represents the operating system and version that the package is built for as set by the os_ver parameter in the publican.cfg file. The noarch element specifies that the package can be installed on any system, regardless of the system architecture. 8.1.7. Building a WebsitePublican can also build websites to manage documentation. This is mostly useful when only one person is maintaining the documentation, but where a team is working on the documentation Publican can generate RPM packages of documentation to install on a web server. The website created consists of a homepage, product and version description pages, and the pages for the documentation. In the publication's root directory, Publican creates a configuration file, an SQLite database file, and two subdirectories. There could be many configuration files depending on how many languages the documentation is published in, with a new subdirectory for each language. Publican has comprehensive --man, --help and --help_actions pages accessed from the terminal. For information on XML including the different tags available, see the DocBook guide, DocBook: the definitive guide by Norman Walsh and Leonard Muellner, found here: http://www.docbook.org/tdg/en/html/docbook and specifically Part II: Reference for a list of all the tags and brief instructions on how to use them. Doxygen is a documentation tool that creates reference material both online in HTML and offline in Latex. It does this from a set of documented source files which makes it easy to keep the documentation consistent and correct with the source code. 8.2.1. Doxygen Supported Output and LanguagesDoxygen has support for output in: RTF (MS Word) PostScript Hyperlinked PDF Compressed HTML Unix man pages
Doxygen supports the following programming languages: C C++ C# Objective -C IDL Java VHDL PHP Python Fortran D
Doxygen uses a configuration file to determine its settings, therefore it is paramount that this be created correctly. Each project requires its own configuration file. The most painless way to create the configuration file is with the command doxygen -g config-file. This creates a template configuration file that can be easily edited. The variable config-file is the name of the configuration file. If it is committed from the command it is called Doxyfile by default. Another useful option while creating the configuration file is the use of a minus sign (-) as the file name. This is useful for scripting as it will cause Doxygen to attempt to read the configuration file from standard input (stdin). The configuration file consists of a number of variables and tags, similar to a simple Makefile. For example: TAGNAME = VALUE1 VALUE2...
For the most part these can be left alone but should it be required to edit them refer to the configuration page of the Doxygen documentation website for an extensive explanation of all the tags available. There is also a GUI interface called doxywizard. If this is the preferred method of editing then documentation for this function can be found on the Doxywizard usage page of the Doxygen documentation website. There are eight tags that are useful to become familiar with. Running doxygen config-file creates html, rtf, latex, xml, and / or man directories in whichever directory doxygen is started in, containing the documentation for the corresponding filetype. There are a number of commands that may be useful. The command make ps_2on1 prints two pages on one physical page. It is also possible to convert to a PDF if a ghostscript interpreter is installed by using the command make pdf. Another valid command is make pdf_2on1. When doing this set PDF_HYPERLINKS and USE_PDFLATEX tags to yes as this will cause Makefile will only contain a target to build refman.pdf directly. 8.2.4. Documenting the SourcesThere are three main steps to document the sources. First, ensure that EXTRACT_ALL is set to no so warnings are correctly generated and documentation is built properly. This allows doxygen to create documentation for documented members, files, classes and namespaces. There are two ways this documentation can be created: - A special documentation block
This comment block, containing additional marking so Doxygen knows it is part of the documentation, is in either C or C++. It consists of a brief description, or a detailed description. Both of these are optional. What is not optional, however, is the in body description. This then links together all the comment blocks found in the body of the method or function. While more than one brief or detailed description is allowed, this is not recommended as the order is not specified. The following will detail the ways in which a comment block can be marked as a detailed description: C-style comment block, starting with two asterisks (*) in the JavaDoc style. /** * ... documentation ... */ C-style comment block using the Qt style, consisting of an exclamation mark (!) instead of an extra asterisk. /*! * ... documentation ... */ The beginning asterisks on the documentation lines can be left out in both cases if that is preferred. A blank beginning and end line in C++ also acceptable, with either three forward slashes or two forward slashes and an exclamation mark. ////// ... documentation/// or //!//! ... documentation ...//! Alternatively, in order to make the comment blocks more visible a line of asterisks or forward slashes can be used. //////////////////////////////////////////////////// ... documentation ...///////////////////////////////////////////////// or /********************************************//** * ... documentation ... ***********************************************/ Note that the two forwards slashes at the end of the normal comment block start a special comment block.
There are three ways to add a brief description to documentation. To add a brief description use \brief above one of the comment blocks. This brief section ends at the end of the paragraph and any further paragraphs are the detailed descriptions. /*! \brief brief documentation. * brief documentation. * * detailed documentation. */ By setting JAVADOC_AUTOBRIEF to yes, the brief description will only last until the first dot followed by a space or new line. Consequentially limiting the brief description to a single sentence. /** Brief documentation. Detailed documentation continues * from here. */ This can also be used with the above mentioned three-slash comment blocks (///). The third option is to use a special C++ style comment, ensuring this does not span more than one line. /// Brief documentation./** Detailed documentation. */ or //! Brief documentation.//! Detailed documentation //! starts here The blank line in the above example is required to separate the brief description and the detailed description, and JAVADOC_AUTOBRIEF must to be set to no.
It is also possible to have the documentation after members of a file, struct, union, class, or enum. To do this add a < marker in the comment block.\ int var; /*!< detailed description after the member */ Or in a Qt style as: int var; /**< detailed description after the member */ or int var; //!< detailed description after the member //!< or int var; ///< detailed description after the member ///< For brief descriptions after a member use: int var; //!< brief description after the member or int var; ///< brief description after the member - Documentation at other places
While it is preferable to place documentation in front of the code it is documenting, at times it is only possible to put it in a different location, especially if a file is to be documented; after all it is impossible to place the documentation in front of a file. This is best avoided unless it is absolutely necessary as it can lead to some duplication of information. To do this it is important to have a structural command inside the documentation block. Structural commands start with a backslash (\) or an at-sign (@) for JavaDoc and are followed by one or more parameters. /*! \class Test \brief A test class. A more detailed description of class. */ In the above example the command \class is used. This indicates that the comment block contains documentation for the class 'Test'. Others are: \struct: document a C-struct
\union: document a union
\enum: document an enumeration type
\fn: document a function
\var: document a variable, typedef, or enum value
\def: document a #define
\typedef: document a type definition
\file: document a file
\namespace: document a namespace
\package: document a Java package
\interface: document an IDL interface
Next, the contents of a special documentation block is parsed before being written to the HTML and / Latex output directories. This includes: Special commands are executed. Any white space and asterisks (*) are removed. Blank lines are taken as new paragraphs. Words are linked to their corresponding documentation. Where the word is preceded by a percent sign (%) the percent sign is removed and the word remains. Where certain patterns are found in the text, links to members are created. Examples of this can be found on the automatic link generation page on the Doxygen documentation website. When the documentation is for Latex, HTML tags are interpreted and converted to Latex equivalents. A list of supported HTML tags can be found on the HTML commands page on the Doxygen documentation website.
More information can be found on the Doxygen website. mallopt is a library call that allows a program to change the behavior of the malloc memory allocator.
Example A.1. Allocator heuristics An allocator has heuristics to determine long versus short lived objects. For the former, it attempts to allocate with mmap. For the later, it attempts to allocate with sbrk. In order to override these heuristics, set M_MMAP_THRESHOLD. In multi-threaded applications, the allocator creates multiple arenas in response to lock contention in existing arenas. This can improve the performance significantly for some multi-threaded applications at the cost of an increase in memory usage. To keep this under control, limit the number of arenas that can be created by using the mallopt interface. The allocator has limits on the number of arenas it can create. For 32bit targets, it will create 2 * # core arenas; for 64bit targets, it will create 8 * # core arenas. mallopt allows the developer to override those limits. Example A.2. mallopt To ensure no more than eight arenas are created, issue the following library call: mallopt (M_ARENA_MAX, 8); The first argument for mallopt can be: M_MXFAST M_TRIM_THRESHOLD M_TOP_PAD M_MMAP_THRESHOLD M_MMAP_MAX M_CHECK_ACTION M_PERTURB M_ARENA_TEST M_ARENA_MAX
malloc_trim is a library call that requests the allocator return any unused memory back to the operating system. This is normally automatic when an object is freed. However, in some cases when freeing small objects, glibc might not immediately release the memory back to the operating system. It does this so that the free memory can be used to satisfy upcoming memory allocation requests as it is expensive to allocate from and release memory back to the operating system.
malloc_stats is used to dump information about the allocator's internal state to stderr. Using mallinfo is similar to this, but it places the state into a structure instead.
| Revision History |
|---|
| Revision 2-34 | Tue Feb 19 2013 | Jacquelynn East | | Version for 6.4 GA release. |
| | Revision 2-32 | Fri Jan 25 2013 | Jacquelynn East | | Updated Developer Toolset section. |
| | Revision 2-7 | Wed Jul 11 2012 | Jacquelynn East | | Altered Developer Toolset chapter to add more information and remove hard links. |
| | Revision 2-5 | Mon Jul 09 2012 | Jacquelynn East | | Re-release for Developer Toolset chapter. |
| | Revision 2-3 | Mon Jun 18 2012 | Jacquelynn East | | Version for the 6.3 GA release. New edition for major changes especially in Eclipse chapters. |
| | Revision 1-46 | Wed Jun 13 2012 | Jacquelynn East | | Many bugs after doc review. |
| | Revision 1-44 | Mon May 14 2012 | Jacquelynn East | | | Revision 1-40 | Tue Mar 13 2012 | Jacquelynn East | | | Revision 1-39 | Wed Mar 07 2012 | Jacquelynn East | | | Revision 1-38 | Tue Mar 06 2012 | Jacquelynn East | | | Revision 1-34 | Tue Mar 01 2012 | Jacquelynn East | | | Revision 1-33 | Wed Feb 29 2012 | Jacquelynn East | | | Revision 1-31 | Mon Feb 13 2012 | Jacquelynn East | | | Revision 1-28 | Wed Jan 25 2012 | Jacquelynn East | | BZ#722517. | | BZ#722504. | | BZ#785194. | | BZ#785191. | | BZ#722520. | | BZ#722517. |
| | Revision 1-21 | Mon Jan 09 2012 | Jacquelynn East | | | Revision 1-19 | Mon Dec 12 2011 | Jacquelynn East | | | Revision 1-18 | Thu Dec 08 2011 | Jacquelynn East | | | Revision 1-16 | Fri Dec 02 2011 | Jacquelynn East | | Release for GA of Red Hat Enterprise Linux 6.2. |
|
|
| |
