Mobicents Community Documentation

Name	Location	Team	Email
Ivelin Ivanov	Austin, Texas	Development Manager and Founder	`<ivelin.atanasoff.ivanov@gmail.com>`
Vladimir Ralev	Republic of Bulgaria	SIP Servlets Server Developer	`<vladimir.ralev@gmail.com>`
Eduardo Martins	Sesimbra, Portugal	JAIN SLEE Server & SIP Presence Service Lead	`<emmartins@gmail.com>`
Jean Deurelle	France	SIP Servlets Server Lead	`<jean.deruelle@gmail.com>`
Oleg Kulikov	Volgograd, Russian Federation	Media Server Lead	`<oleg.kulikoff@gmail.com>`
Amit Bhayani	Pune, India	Media Server Developer	`<amit.bhayani@gmail.com>`
Luis Barreiro	Portugal	QE Lead and Hudson Build Server Maintainer	`<lbbbarreiro@gmail.com>`
Alexandre Mendonça	Lisbon, Portugal	Diameter Lead, JAIN SLEE Server Developer	`<brainslog@gmail.com>`
Bartosz Baranowski	Warsaw, Poland	Media Server Developer, Diameter Developer, JAIN SLEE Server Developer	`<baranowb@gmail.com>`
Pavel Šlégr	Brno, Czech Republic	Productization Lead	`<pslegr@redhat.com>`
Rob Cardwell	McLean, VA, USA	Program Manager	`<rcardwel@redhat.com>`
Mr Vicky Kak	India	JBCP GSS Product Support	`<vkak@redhat.com>`

XML Book Component	Description	Order of Component in the Book
`[Book_Name].xml`	Contains the structure of the user guide, represented by xi:include references to each chapter-`[Chapter_Name]`.xml component, and other mandatory components in this table.	Top Level (or Parent) component of any user guide.
`Book_Info.xml`	Contains information about the book title, book version number, abstract and copyright information.	1st Child. This is the opening information a reader will see in the user guide.
`Author_Group.xml`	Contains contact information about the authors that contributed to the content of the book.	2nd Child. This component is included in the `Book_Info.xml` component.
`Preface.xml`	Contains pre-defined content explaining the typographical standards used in the guide, and other information that will assist the reader with using the guide.	3rd Child. This component is included after the `Book_Info.xml` content.
`chapter-[Chapter_Name].xml`	Contains XML markup and content included at a Chapter level in the document. The XML file is named only for human-readability.	4th. This is the top level element for each chapter in the user guide. The order of these files in the `[Book_Name].xml` file determines the structure of the guide.
`section-[Section_Name].xml`	Contains XML markup and content included at a Section level in the document. The XML file is named only for human-readability.	5th. This component is included in `chapter-[Chapter_Name].xml` files by xi:include reference.
`Revision History.xml`	Contains a record of the revisions made to the document over time. Top-level information about changes in the guide are provided to the reader.	6th.

XML Component	Description	Order of Component in the Book
`Conventions.xml`	Contains typographical standards used within the guide.	Inserted by xi:fallback reference at the end of the `Preface.xml` file.
`Feedback.xml`	Contains information about how to raise a bug against the JBCP user documentation.	Inserted by xi:fallback reference at the end of the `Preface.xml` file.
`Legal_Notice.xml`	Contains standardized Red Hat legal information.	Inserted by xi:fallback reference at the end of the `Book_Info.xml` file

Variable Name	Description	Substituted Values (if applicable)
${platform.name}	Substitutes the Platform name, based on whether the documentation is being produced for Mobicents or JBCP.	Mobicents, JBCP
${bookid}	Substitutes the Book ID, which is used to populate the book identifier in the preface. The Book ID is necessary for readers to uniquely identify the book when raising documentation tickets.	doc-`[book_name]`. For example, `doc-SIP_Servlets_Server_User_Guide`.
${release.integrated.filename}	Substitutes the Binary filename for the release, based on the binary file nomenclature for the community and product.
${release.xdms.filename}	Specific to the XML Document Management Server, the binary file name for the release based on the binary file nomenclature for the community and product.
${version}	Substitutes the product version number for the release. This variable is used to substitute the version numbers in all path names.

6.1. Disallowed Elements and Attributes

Supported, unsupported, and disallowed

Not every element and attribute that works with Publican is supported. Specifically, not every element has been tested with regards its effect on the presentation of a document once it has been built in HTML or PDF.

Publican works with almost all DocBook 4.5 elements and their attributes, and most of these elements are supported. Supported elements and attributes are those whose presentation in Publican HTML and PDF output has been tested and is of an acceptable quality.

Other elements and attributes that are not known to be harmful or redundant but which have not been tested for quality are unsupported. If material within a particular DocBook element does not look correct when you build a document in HTML or PDF, the problem could be that the transformation logic for that element has not yet been tested. Build the document again and examine Publican's output as the document builds. Publican presents warnings about unsupported elements that it encounters in your XML files.

Finally, a small group of elements and attributes are disallowed. These elements and attributes are set out below, each accompanied by rationale explaining why it is disallowed.

6.1.1. Disallowed elements

<caution> , <tip>

DocBook XML supports five admonitions of varying severity: <tip>, <note>, <important>, <caution>, and <warning>. Taken together, these represent a very fine-grained set of distinctions. It is unlikely that these fine distinctions can be applied consistently within a document, especially when more than one person writes or maintains the document. Moreover, this level of granularity is meaningless to readers. By design, Publican disallows the <tip> and <caution> elements, these elements being the two most redundant in the set.

Use <note> instead of <tip>, and use either <important> or <warning> instead of <caution>. Some criteria by which you might select a suitable level of severity are presented in the Document Conventions section of the preface of books produced with Publican's default brand.

<entrytbl>

Publican depends on an external application, FOP, to render PDF documents. At present, FOP does not support nested tables, so attempts to build PDF files from Publican documents that contain nested tables fail.

Nested tables are therefore disallowed at least until they are supported in FOP. If you planned to include a nested table in your document, reconsider your data structure.

<glossdiv> , <glosslist>

This element set presents terms in glossaries in alphabetical order; however, the terms are sorted according to the original language of the XML, regardless of how these terms are translated into any other language. For example, a glossary produced with <glossdiv>s that looks like this in English:

A: Apple — an apple is
G: Grapes — grapes are
O: Orange — an orange is
P: Peach — a peach is

looks like this in Spanish:

A: Manzana — la manzana es
G: Uva — la uva es
O: Naranja — la naranja es
P: Melocotonero — el melocotonero es

In a translated language that does not share the same writing system with the original language in which the XML was written, the result is even more nonsensical.

<inlinegraphic>

This element presents information as a graphic rather than as text and does not provide an option to present a text alternative to the graphic. This element therefore hides information from people with visual impairments. In jurisdictions that have legal requirements for electronic content to be accessible to people with visual impairments, documents that use this element will not satisfy those requirements. Section 508 of the Rehabilitation Act of 1973^[1] is an example of such a requirement for federal agencies in the United States.

Note that <inlinegraphic> is not valid in DocBook version 5.

<link>

The <link> element provides a general-purpose hyperlink and therefore offers nothing that the <xref> and <ulink> elements do not, for internal and external hyperlinks respectively. The <link> element is disallowed due to its redundancy.

<olink>

The <olink> element provides cross-references between XML documents. For <olink>s to work outside of documents that are all hosted within the same library of XML files, you must provide a URL for the document to which you are linking. In environments that use <olink>s, these URLs can be supplied either as an XML entity or with a server-side script. Publican produces documents intended for wide dissemination in which URLs are always necessary for cross-references. Therefore, the <olink> element offers no advantage over the <ulink> element, and is disallowed due to its redundancy.

6.1.2. Disallowed attributes

<[element] xreflabel="[any_string_here]">

The presence of an <xreflabel> attribute reduces the usability of printed versions of a book. As well, attribute values are not seen by translators and, consequently, cannot be translated.

For example, if you have the following:




<chapter id="ch03" xreflabel="Chapter Three">

 <title>The Secret to Eternal Life</title>

 <para>The secret to eternal life is</para>

</chapter>



[more deathless prose here]     



see <xref linkend="ch03"> for details.

when your XML is built to HTML, the <xref> element becomes an HTML anchor element as follows:




see <a href="#ch03">Chapter Three</a> for details.

The text contained by the anchor element is the same as the data in the <xreflabel> attribute. In this case, it means that readers of printed copies have less information available to them.

You could work around this if you make the value of the <xreflabel> attribute the same as the text within the <title></title> element. However, this duplication increases the risk of typo-level errors and otherwise offers no underlying improvement. And it still reduces the amount of information presented to readers of printed copies.

The following XML:




<chapter id="ch03" xreflabel="The Secret to Eternal Life">

 <title>The Secret to Eternal Life</title>

 <para>The secret to eternal life is</para>

</chapter>



[more deathless prose here]     



see >xref linkend="ch03"> for details.

Will result in an HTML anchor element as follows:




see <a href="#ch03">The Secret to Eternal Life</a> for details.

This is not as informative as the text presented to a reader if you do not use an <xreflabel> attribute. The following:




<chapter id="ch03">

 <title>The Secret to Eternal Life</title>

 <para>The secret to eternal life is</para>

</chapter>



[more deathless prose here]  



see <xref linkend="ch03"> for details.

transforms the <xref> element as follows when built to HTML:




see <a href="#ch03">Chapter 3: The Secret to Eternal Life</a> for details.

More important, however, are the translation problems that <xreflabel> elements cause. Attribute values are not seen by translators. Consequently, they are not translated. Consider the second example above again:




<chapter id="ch03" xreflabel="The Secret to Eternal Life">

 <title>The Secret to Eternal Life</title>

 <para>The secret to eternal life is</para>

</chapter>



[more deathless prose here]  



see <xref linkend="ch03"> for details.

In English, the <xref> is still transformed into an anchor element as follows:




see <a href="#ch03">The Secret to Eternal Life</a> for details.

Someone reading the German version, however, will have this as their underlying HTML:




Sehen Sie <a href="#ch03">The Secret to Eternal Life</a> f�r Details.

If the <xreflabel> attribute is not used, the title and chapter indicator, both properly translated, appear to the reader. That is, the following:




<chapter id="ch03">

 <title>The Secret to Eternal Life</title>

 <para>The secret to eternal life is</para>

</chapter>



[more deathless prose here]  



see <xref linkend="ch03"> for details.

will, after translation, present thus to a German-speaking reader:




Sehen Sie <a href="#ch03">Kapitel 3: Das Geheimnis des ewigen Lebens</a> f�r Details.

This is, not surprisingly, what we want.

The xreflabel attribute is therefore disallowed.

<[element] endterm="[any_string_here]">

The endterm attribute allows you to present hyperlinked text other than the name of the section or chapter to which the hyperlink points. As such, it decreases the usability of printed versions of documents, and causes difficulty for translators.

The text presented in an element (such as an <xref>) that contains the endterm attribute is taken from a <titleabbrev> element in the target chapter or section. Although the content of the <titleabbrev> element is available to translators in the document's PO files, it is removed from the context of the <xref>. The absence of this context makes reliable translation impossible in languages that mark prepositions or articles for grammatical number and grammatical gender.

For example, if you have the following:




<chapter id="The_Secret">

 <title>The Secret to Eternal Life</title>

 <titleabbrev id="final">the final chapter</titleabbrev>



 <para>The secret to eternal life is</para>

</chapter>



[more deathless prose here]     



The solution is in <xref linkend="The_Secret" endterm="final"/>.

The text surrounding the <xref> presents in the English version of the document as:

The solution is in the final chapter.

A translator sees the <titleabbrev> in a PO file as:

#. Tag: titleabbrev
#, no-c-format
msgid "the final chapter"
msgstr ""

and sees the text that contains the <xref> elsewhere in the PO file (or, more likely, in a completely different PO file) as:

#. Tag: para
#, no-c-format
msgid "The solution is in <xref linkend="The_Secret" endterm="final"/>."
msgstr ""

The translator has no way of telling what will be substituted for <xref linkend="The_Secret" endterm="final"/> when the document builds, so a translation in Italian might read:

#. Tag: para
#, no-c-format
msgid "The solution is in <xref linkend="The_Secret" endterm="final"/>."
msgstr "La soluzione è in <xref linkend="The_Secret" endterm="final"/>."

Note the preposition in.

If the translator rendered the final chapter in Italian as l'ultimo capitolo, the result when the document builds will read:

La soluzione è in l'ultimo capitolo.

This result is comprehensible, but inelegant, because Italian combines some of its prepositions with its definite articles. More elegant Italian would be:

La soluzione è nell'ultimo capitolo.

Without knowing what text will appear in place of <xref linkend="The_Secret" endterm="final"/>, the translator into Italian cannot know whether to leave the preposition in to stand by itself, or which of seven different possible combinations with the definite article to use: nel, nei, nello, nell', negli, nella, or nelle.

Furthermore, note that the combined preposition and article also poses a problem with regard to whether this word should be placed in the text surrounding the <xref>, or in the <titleabbrev>. Whichever of these two solutions the translator selects will cause problems when the endterm appears in other grammatical contexts, because not all Italian prepositions can combine with the definite article in this way.

Due to the problems that endterm presents for translation, Publican disallows this attribute.

6.2. Entities

Use entities with extreme caution

Entities offer convenience but they should be used with extreme caution in documents that will be translated. Writing (for example) &FDS instead of Fedora Directory Server saves the writer time but transformed entities do not appear in the portable object (PO) files that translators use. Complete translations of documents containing entities are, as a consequence, impossible.

Entities present special obstacles to translators and can preclude the production of high-quality translations. The very nature of an entity is that the word or phrase represented by the entity is rendered exactly the same way every time that it occurs in the document, in every language. This inflexibility means that the word or word group represented by the entity might be illegible or incomprehensible in the target language and that the word or word group represented by the entity cannot change when the grammatical rules of the target language require them to change. Furthermore, because entities are not transformed when XML is converted to PO, translators cannot select the correct words that surround the entity, as required by the grammatical rules of the target language.

If you define an entity — <!ENTITY LIFT "Liberty Installation and Formatting Tome"> — you can enter &LIFT in your XML and it will appear as Liberty Installation and Formatting Tome every time the book is built as HTML, PDF or text.

Entities are not transformed when XML is converted to PO, however. Consequently, translators never see Liberty Installation and Formatting Tome. Instead they see &LIFT, which they cannot translate.

Consider something as simple as the following English sentence fragment being translated into a related language: German.

As noted in the Liberty Installation and Formatting Tome, Chapter 3

A translation of this might be as follows:

Wie in dem Wälzer für die Installation und Formatierung von Liberty, Kapitel 3, erwähnt

Because there is no text missing, the title can be translated into elegant German. Also, note the use of dem, the correct form of the definite article ('the') when referring to a Wälzer ('tome') in this grammatical context.

By contrast, if entities are used, the entry in the PO file says:

#. Tag: para
#, no-c-format
msgid "As noted in the <citetitle>&LIFT</citetitle>, Chapter 3"
msgstr ""

The translation of this would probably run thus:

#. Tag: para
#, no-c-format
msgid "As noted in the <citetitle>&LIFT</citetitle>, Chapter 3"
msgstr "Wie in <citetitle>&LIFT</citetitle>, Kapitel 3, erwähnt"

And the presentation would be thus:

Wie in Liberty Installation and Formatting Tome, Kapitel 3, erwähnt

This, of course, leaves the title in English, including words like 'Tome' and 'Formatting' that readers are unlikely to understand. Also, the translator is forced to omit the definite article dem, a more general construction that comes close to a hybrid of English and German that German speakers call Denglisch or Angleutsch. Many German speakers consider this approach incorrect and almost all consider it inelegant.

Equivalent problems emerge with a fragment such as this:

However, a careful reading of the Liberty Installation and Formatting Tome afterword shows that

With no text hidden behind an entity, a German translation of this might be:

Jedoch ergibt ein sorgfältiges Lesen des Nachworts für den Wälzer für die Installation und Formatierung von Liberty, dass

If an entity was used to save the writer time, the translator has to deal with this:

#. Tag: para
#, no-c-format
msgid "However, a careful reading of the <citetitle>&LIFT</citetitle> afterword shows that"
msgstr ""

And the translation would be subtly but importantly different:

#. Tag: para
#, no-c-format
msgid "However, a careful reading of the <citetitle>&LIFT</citetitle> afterword shows that"
msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle>&LIFT</citetitle>, dass"

When presented to a reader, this would appear as follows:

Jedoch ergibt ein sorgfältiges Lesen des Nachworts für Liberty Installation and Formatting Tome, dass

Again, note the missing definite article (den in this grammatical context). This is inelegant but necessary since the translator can otherwise only guess which form of the definite article (den, die or das) to use, which would inevitably lead to error.

Finally, consider that although a particular word never changes its form in English, this is not necessarily true of other languages, even when the word is a proper noun such as the name of a product. In many languages, nouns change (inflect) their form according to their role in a sentence (their grammatical case). An XML entity set to represent an English noun or noun phrase therefore makes correct translation impossible in such languages.

For example, if you write a document that could apply to more than one product, you might be tempted to set an entity such as &PRODUCT. The advantage of this approach is that by simply changing this value in the Doc_Name.ent file, you could easily adjust the book to document (for example) Red Hat Enterprise Linux, Fedora, or CentOS. However, while the proper noun Fedora never varies in English, it has six different forms in Czech, depending on one of seven ways that you can use it in a sentence:

Table 6.1. 'Fedora' in Czech

Case	Usage	Form
Nominative	the subject of a sentence	Fedora
Genitive	indicates possession	Fedory
Accusative	the direct object of a sentence	Fedoru
Dative	the indirect object of a sentence	Fedoře
Vocative	the subject of direct address	Fedoro
Locative	relates to a location	Fedoře
Instrumental	relates to a method	Fedorou

For example:

Fedora je linuxová distribuce. — Fedora is a Linux distribution.
Inštalácia Fedory — Installation of Fedora
Stáhnout Fedoru — Get Fedora
Přispějte Fedoře — Contribute to Fedora
Ahoj, Fedoro! — Hello Fedora!
Ve Fedoře 10 — In Fedora 10
S Fedorou získáváte nejnovější — With Fedora, you get the latest

A sentence that begins S Fedora získáváte nejnovější remains comprehensible to Czech readers, but the result is not grammatically correct. The same effect can be simulated in English, because although English nouns lost their case endings during the Middle Ages, English pronouns are still inflected. The sentence, 'Me see she' is completely comprehensible to English speakers, but is not what they expect to read, because the form of the pronouns me and she is not correct. Me is the accusative form of the pronoun, but because it is the subject of the sentence, the pronoun should take the nominative form, I. Similarly, she is nominative case, but as the direct object of the sentence the pronoun should take its accusative form, her.

Nouns in most Slavic languages like Russian, Ukrainian, Czech, Polish, Serbian, and Croatian have seven different cases. Nouns in FinnoUgaric languages such as Finnish, Hungarian, and Estonian have between fifteen and seventeen cases. Other languages alter nouns for other reasons. For example, Scandinavian languages inflect nouns to indicate definiteness — whether the noun refers to 'a thing' or 'the thing' — and some dialects of those languages inflect nouns both for definiteness and for grammatical case.

Now multiply such problems by the more than 40 languages that Publican currently supports. Other than the few non-translated strings that Publican specifies by default in the Doc_Name.ent file, entities might prove useful for version numbers of products. Beyond that, the use of entities is tantamount to a conscious effort to inhibit and reduce the quality of translations. Furthermore, readers of your document in a language that inflects nouns (whether for case, definiteness, or other reasons) will not know that the bad grammar is the result of XML entities that you set — they will probably assume that the translator is incompetent.

6.3. Chapters and Sections

Chapters and Sections form the underlying skeleton for each guide. Therefore, structuring these important elements consistently is important.

New Chapter or Section

Over the life of a product, user guides often require content to be reorganized. Having sections directly included in a chapter, can make reordering book structure difficult. For this reason, when adding a <chapter> or <section> to an existing user guide, each <chapter> and <section> must be a separate XML file.

The file must be included in the book using an xi:include reference. See http://www.w3.org/TR/xinclude/#syntax for examples of xi:include syntax.

Naming Chapter or Section XML Files

A complete XML user guide may consist of a large number of XML files. Each file included in the book should be logically, and consistently, named so it is easy to include a file where it is required in the book's structure. For information about recommended file naming standards, refer to Table 4.1, “Book Components” in Section 4.1.1, “XML Book Components”.

ID Attributes for Chapter or Section XML Files

To allow cross-referencing within the book, the id attribute must be set for each chapter or section. The format for the chapter or section ID is explicit, to ensure cross-referencing within each user guide is consistent. For more information about links and references, refer to Section 6.14, “Links and References”

The id attribute is applied to the <chapter> or <section> element, and uses the following format:

<chapter id="chap-Book_Name-Chapter_Title">
<section id="sect-Book_Name-Chapter_Title-Section_Title">

For example, the XML ID of this section would be <section id="sect-Mobicents_Community_Documentation-Structure_Guidelines-Chapters_and_Sections">.

6.4. Lists

The two most common list types in DocBook are not named according to such programs as Microsoft Word, or Open Office. You would think that for a bulleted list, you would start the list using <bullets> or <bulletedlist>. Likewise, for a numbered list, you might consider using <numlist> or <numberedlist>.

In DocBook, these types of lists are referred to according to the following nomenclature:

Bulleted List - <itemizedlist>
Numbered List - <orderedlist>

<orderedlist> is no substitute for <procedure>

If you are documenting a complex set of steps, you must use a <procedure> to contain the steps. Procedures can contain multiple steps, and offer greater content flexibility. For more information about <procedure>, refer to Section 6.5, “Procedures”

Lead-in Sentence is Mandatory

A list must have an introductory sentence, and it must not be a sentence fragment. Sentence fragments are very hard to translate.

<itemizedlist>

An itemized list is used to replace a semi-colon separated list in a sentence.

The XML form of an itemized list has a number of mandatory elements. For a complete list, refer to the DocBook.org <itemizedlist> page.

Example 6.1. <itemizedlist> Mandatory Elements


<itemizedlist>

    <listitem>

        <para>Item One.</para>

    </listitem>

    <listitem>

        <para>Item Two.</para>

    </listitem>

    <listitem>

        <para>Item Three.</para>

    </listitem>

</itemizedlist>

The XML Structure looks like this when published:

Item One.
Item Two.
Item Three.

You can further enhance the <itemizedlist> by adding in a <title> element after the opening <itemizedlist> element. A title might assist the reader with understanding what a large list contains. The XML structure looks like this when published:

<itemizedlist> Title

Item One.
Item Two.
Item Three.

<orderedlist>

An <orderedlist> is just like an <itemizedlist>, except it displays the content in number order. This type of list is better suited to listing small sub-steps in <procedure> lists.

The XML form of an itemized list has a number of mandatory elements. For a complete list, refer to the DocBook.org <itemizedlist> page.

Example 6.2. <orderedlist> Mandatory Elements


<orderedlist>

    <listitem>

        <para>Item One.</para>

    </listitem>

    <listitem>

        <para>Item Two.</para>

    </listitem>

    <listitem>

        <para>Item Three.</para>

    </listitem>

</orderedlist>

You can further enhance the <orderedlist> by adding in a <title> element after the opening <orderedlist> element. A title might assist the reader with understanding what a large list contains.

The XML structure looks like this when published:

<orderedlist> Title

Item One.
Item Two.
Item Three.

<variablelist>

A <variablelist> can be used to define a list of terms, or in situations where a table of only two columns might be used. Variable lists can have optional titles.

Example 6.3. <variablelist> example




<variablelist>

    <title>This Title is Optional</title>

    <varlistentry>

        <term>This is the first term</term>

        <listitem>

            <para>Here are the item details for the first term.</para>

        </listitem>

    </varlistentry>

    <varlistentry>

        <term>This is the second term</term>

        <term>this is the third term</term>

        <listitem>

            <para>Here are the item details for the second and third terms.</para>

        </listitem>

    </varlistentry>

</variablelist>

This Title is Optional
This is the first term
Here are the item details for the first term.
This is the second term, this is the third term
Here are the item details for the second and third terms.

6.5. Procedures

When it is necessary to document a complex set of installation instructions, an <orderedlist> is usually not the best XML element to choose. It has limitations regarding what level of detail each <listitem> element can contain.

The best option for large work-flows, or detailed steps, is the <procedure> element.

You may not be aware, but this element is used extensively throughout this user guide to capture the steps involved in the Authoring Process.

The biggest advantage to using a <procedure> element is that it uses the <step> element. <step> elements can contain a much wider variety of child elements than the <listitem> element used in <itemizedlist> and <orderedlist>.

The XML form of a procedure has a number of mandatory elements. For a complete list, refer to the DocBook.org <procedure> page. Be sure to visit the pages of the child elements that the <procedure> element supports, particularly the <step> element.

The minimum set of elements required for all procedure lists in the Mobicents UDS are described in the following example:

Example 6.4. <procedure> Mandatory Elements

<procedure>
  <title>&lt;procedure&gt; Title</title>
  <step>
    <title>Step One Title</title>
    <para>Step one info.</para>
  </step>
  <step>
    <title>Step Two Title</title>
    <para>Step two info.</step>
</procedure>

The XML structure looks like this when published:

Procedure 6.1. <procedure> Title

Step One Title
Step one info.
Step Two Title
Step two info.

You can further enhance the <procedure> by adding in any number of supported child elements into each <step>. Each <step> can contain any number of <para> elements, and also permits <itemizedlist> and <orderedlist> elements. Be sure that the elements inserted are not included in Section 6.1.1, “Disallowed elements”.

Example 6.5. <procedure> Extra Elements


<procedure>

    <title>&lt;procedure&gt; Title</title>

        <step>

            <title>Step 1 Title</title>

            <para>Step one info.  You can have multiple <sgmltag>&lt;para&gt;</sgmltag> elements, in one step.</para>

            <para>Second para to further describe step.  </para>

        </step>

        <step>

            <title>Step 2 Title</title>

            <para>If you find you need sub-steps, use an <sgmltag>&lt;orderedlist&gt;</sgmltag> to capture these:</para>

            <para>The ordered list should have a lead-in sentence introducing the list:</para>

            <orderedlist>

                <listitem>

                    <para>Sub-step one.</para>

                </listitem>

                <listitem>

                    <para>Sub-step two, etc.</para>

                </listitem>

            </orderedlist>

        </step>

</procedure>

Procedure 6.2. <procedure> Title

Step 1 Title
Step one info. You can have multiple <para> elements, in one step.
Second para to further describe step.
Step 2 Title
If you find you need sub-steps, use an <orderedlist> to capture these:
The ordered list should have a lead-in sentence introducing the list:
1. Sub-step one.
2. Sub-step two, etc.

6.6. Tables

Depending on the authoring tools you use to edit your XML documentation, inserting tables may take a few mouse clicks. If you prefer to author in plain text mode, you will need sound knowledge of XML table structure so the table you create is valid, and looks the way you want it to when published.

For many new XML authors, tables cause a lot of problems . This section describes the components of an XML table, and includes an XML sample of a three column table. The concept of splitting cells in a row is also discussed.

For the definitive list of table elements and attributes, refer to the Docbook.org <table> page.

Consider <variablelist> for two-column tables

In certain situations, a table that would otherwise only have two columns may be better implemented as a variable list, using the <variablelist> element (see Section 6.4, “Lists”).

The majority of tables used throughout JBoss documentation are classed as formal tables. In contrast to informal tables, formal tables always feature a <title> that gives the reader a basic summary of the table contents. A formal table consists of the following structural elements (in order):

<table>

The parent element of all formal tables, which contains all the child elements. <table> accepts attributes that control how the table is processed at publish time. The frame and pgwide attributes are applied to the <table> element.

<tgroup>

Below the <table> element, the <tgroup> element contains the information that governs the basic framework of your table. <tgroup> contains settings that govern the amount of columns in the table, along with the <row> structural information. <tgroup> also contains column and span specifications required to set the table geometry and cell formatting.

<thead>

Defines the column headers for the table. <thead> is also used if you include a table footer, however table footers are not common in JBoss documentation.

<colspec>

Defines the column specifications for the table. Column and row separators, and column widths, are specified as attributes of this element. <colspec> is also used if you include a header (<thead>)

<tbody>

<tbody> is a wrapper element for the <row> elements that comprise the table. Generally, no attributes are applied to the <tbody> element.

<row>

Defines a row in the table, and contains the <entry> elements that comprise each cell in the table.

<entry>

Defines a cell in the table. Each cell can contain block elements or inline elements, but not both concurrently.

For example, one <entry> might contain a paragraph or a list while another <entry> contains parsed character data (#PCDATA), but no single <entry> can contain a mixture of both.

Example 6.6. Three-column Table


<table frame="all" pgwide="1">

  <title>Three-column Table</title>

  <tgroup colsep="1" cols="3">

    <colspec colnum="1" colname="c0"/>

    <colspec colnum="2" colname="c1"/>

    <colspec colnum="3" colname="c2"/>

    <thead>

      <row>

        <entry>Header Row, Column 1</entry>

        <entry>Header Row, Column 2</entry>

        <entry>Header Row, Column 3</entry>

      </row>

    </thead>

    <tbody>

      <row>

        <entry>A</entry>

        <entry>B</entry>

        <entry>C</entry>

      </row>

      <row>

        <entry>D</entry>

        <entry>E</entry>

        <entry>F</entry>

      </row>

      <row>

        <entry>G</entry>

        <entry>H</entry>

        <entry>I</entry>

      </row>

      <row>

        <entry>J</entry>

        <entry>K</entry>

        <entry>L</entry>

      </row>

    </tbody>

  </tgroup>

</table>

When published, the XML structure described in Example 6.6, “Three-column Table” publishes in the following way.

Table 6.2. Three-column Table

Header Row, Column 1	Header Row, Column 2	Header Row, Column 3
A	B	C
D	E	F
G	H	I
J	K	L

Merging Cells Horizontally (spanning cells)

Merging cells horizontally is controlled by specifying the namest and nameend attributes in the <entry> element. The colname value of the starting column and the finishing column are specified in the <entry> element that you want the cell span to start from.

Example 6.7. Cell spanning

This example describes how to merge the B and C cells together in Table 6.2, “Three-column Table” using the namest and nameend attributes.

In the <thead> element of the table, the <colspec> element has two attributes specified: colnum and colname. By default, the colname attribute starts from c0.

To span the B and C cells, you need to specify namest="c1" as the starting cell (the second column) and nameend="c2" as the finishing cell (the third column).


<row>

  <entry>A</entry>

  <entry 

namest
=

"c1"
 

nameend
=

"c2"
>BC</entry>

</row>

<row>

  <entry>D</entry>

  <entry>E</entry>

  <entry>F</entry>

</row>

6.7. Emphasis (Bold, Italic, Underline)

In DocBook v4.5, the <emphasis> element supports attributes that allow you to override default stylesheet behaviour. Do not use attributes such as bold, italic, or underline to alter text enclosed in <emphasis> elements.

Remember that XML authoring separates content from style. By applying attributes in this way, you are effectively introducing style into your content.

If you want to change the way the <emphasis> element formats the text at publish time, you should consider updating the stylesheet, and not "work around" the problem by applying attributes.

6.8. Graphics and Screenshots

There are a number of graphical elements that are supported in DocBook. For consistency, the best element to use is <figure>.

The <figure> element has the advantage of containing a well-formatted title for the image. It is suitable for both diagrams, and screenshots, which are included through the use of the <mediaobject> element. The <mediaobject> element must also contain a <textobject> element with a description of the image for accessibility purposes.

Screenshots increase user guide maintenance

Think carefully before inserting a screen shot. Often, you can explain what fields a user must complete in the user interface without a screen shot. If you can, you will save a lot of maintenance in the future.

Screenshots increase the maintenance of a user guide. What happens if the interface changes? What happens if the product logo is updated? These situations require the screen shot to be recaptured again.

Example 6.8. <figure> element structure

<figure>
  <title>JBoss Community Logo</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/img-JBoss_Community_Logo.png" format="PNG"/>
    </imageobject>
    <textobject>
      <para>Logo for the JBoss Community<para>
    </textobject>
  </mediaobject>
</figure>

The XML structure looks like this when published:

[D]

Figure 6.1. JBoss Community Logo

The <imagedata> element defines the image path, and sets the way the image is displayed in the published output. Use the following recommendations when inserting <figure> elements:

To scale large diagrams or screenshots to fit within page boundaries, set width="450" to scale the screen shot within the boundaries of an A4 page.
If you need to include a screen shot of a large user interface, consider including only the area that relates to what you are discussing. You can get a much better result if you capture a small section of a user interface, because the user can easily see the detail of the area referred to in the procedure or concept.

If you are using a Linux-based operating system, chances are you will be using a graphics package such as the GNU Image Manipulation Program (GIMP). You can use the GIMP to capture screenshots, and save them in a format that will provide the best output for both HTML and PDF.

Procedure 6.3. Correctly capturing screenshots using the GIMP

The following procedure describes how to correctly capture and save a screen shot using the Create Screenshot function in The GIMP. The procedure assumes that you have The GIMP installed, and the program is open.

Prepare the Content to Capture
Ensure you have the correct application open, and that the part of the application you need to capture is activated. The GIMP will capture the screen immediately, unless a delay is set.
Select the Create Screenshot Option
Click File → Create Screenshot.
Confirm Capture Options
In the Screenshot dialog box, select the capture option you require according to the following guidelines:
- Do not include window decorations in any of your screenshots.
- Consider capturing only the section of the screen you need to refer to in the documentation. It will be clearer for the reader.
Capture the Screen
Click the Snap button to begin capturing the screen area. Select the program, or area of the screen you want to capture.
Scale the Image
Click Image → Scale Image.
If you need to scale a large screen shot or diagram, use the following settings:
- In the Image Size group, set the Width to (no greater than) 450 pixels.
- In the Quality group, set Interpolation to Sinc (Lancosz3).
Click Scale to set the image scale.
Save the Image
Click File → Save As.
Name the image according to the image file naming conventions. If in doubt, look at the naming convention in the Images folder of your user guide directory.
In the Save Image dialog, select PNG image (*.png) from the Image Type drop down menu.
Click Save.

6.9. Admonitions (Warning, Important, Note)

To alert readers to information that might otherwise be overlooked, DocBook v4.5 supports a number of admonitions you can use to highlight concepts for readers. The supported options are limited to:

Warning
Important
Note

The options are listed in order of priority, and alert the reader to the following conditions:

Warning: Warnings contain information that must not be ignored. Ignoring recommendations in Warnings may result in data loss, or other catastrophic issues.
Important: Includes information that might be easily overlooked and may cause unnecessary frustration when using the software. For example, configuration changes that only apply to the current session, or services that need restarting before an update will apply.
Note: Contains information that may be useful to the reader. Ignoring a note should have no negative consequences for the reader, but may result in the reader missing out on usability tips, or a shortcut that may help them complete a task.

The way these elements are formatted depends on what publishing system you use to produce a user guide. The Publican JBoss brand formats this information in a conspicuous way; lots of color, bold graphics, and a slightly different typeface to the normal content. The Publican jboss-community brand and the defalut jDocBook style formats the information slightly less aggressively by using softer colors, but each admonition is still quite conspicuous to the reader.

When writing information for any of these elements, you can maximize the effectiveness of the information by keeping the structure of the information consistent. Consider the following examples to see how effective this is.

Example 6.9. Warning and Important

Use the following XML structure when creating a Warning or Important admonition. See the sample Warning and Important in this example as a reference.


<warning>

  <title>Warning Summary</title>

  <para>Imperetive instruction to the user.  Reason why the user should obey the instruction.</para>

</warning>


<important>

  <title>Important Summary</title>

  <para>Information that will save the reader unnecessary frustration.</para>

</important>

Open Office Package Dependencies

Do not uninstall Open Office from Gnome Desktop systems. Open Office package dependencies may result in critical system files, including X Windows System files, being unintentionally removed.

Install MSS for JBoss 0.7 or Later

Only MSS for JBoss v0.7 bundles the Diameter JBoss Service (the Diameter SAR, or Servlet Archive), which is required to run the Diameter Event-Charging Service.

6.10. Special Characters (Symbols)

When writing XML documentation, certain symbols can prevent XML validating correctly. When parsing an XML document, the validator interprets symbols as XML processing instructions. As a rule, a good WYSIWYG XML Editor (for example, Syntext Serna) will correctly substitute special characters with their literal value entities automatically.

If you are editing XML using a basic text editing program, this automation may not exist. You must manually insert symbol entities when you need to insert a keyboard symbol (commonly) or non-keyboard symbols (copyright, etc).

The most common symbol entities that will break XML publishing are listed for reference.

&lt: Inserts a left angle bracket "<" symbol. The left angle bracket is used to open all XML elements, therefore the parser will assume that the text directly proceeding the symbol is a DocBook XML element. This will cause the publish to fail. Use this symbol entity when writing menu paths, referring to XML elements within <para> or other character data (CDATA) elements, or within code samples.
&gt: Inserts a right angle bracket ">" symbol. Use this symbol to close off XML elements when describing XML elements in CDATA elements such as <para> elements and within code samples.
&amp: Inserts an ampersand "&" symbol. Ampersand is used to start an entity reference, so this will break the XML publish if you directly insert it into your document.

6.11. Menus, Buttons, and Labels

In DocBook 4.5, there are a number of elements that can be used to mark-up items that the user has access to in a program Graphical User Interface (GUI). A user appreciates consistency in the way user commands are represented because it allows them to quickly identify the sequence of menu transitions required to execute a product feature.

Use the following elements as appropriate when describing a GUI:

<guibutton>
<guiicon>
<guilabel>
<menuchoice>
<guimenu>
<guimenuitem>
<guisubmenu>

<guimenu>, <guisubmenu>, and <guimenuitem> elements can be listed inside a <menuchoice> to provide a simplified notation for traversing the menu hierarchy, as demonstrated in Example 6.10, “GUI elements example”. Alternatively each can be used individually to describe menus and menu items.

Example 6.10. GUI elements example




Choose <menuchoice><guimenu>System</guimenu><guisubmenu>Preferences</guisubmenu><guimenuitem>Mouse</guimenuitem> </menuchoice> from the main menu bar to launch <application>Mouse Preferences</application>. In the <guilabel>Buttons</guilabel> tab, click the <guilabel>Left-handed mouse</guilabel> check box and click <guibutton>Close</guibutton> to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).

Choose System → Preferences → Mouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, click the Left-handed mouse check box and click Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).

6.12. Applications and Utilities

This section lists helpful elements for use when describing and documenting the use of applications and utilities. Also refer to Section 6.11, “Menus, Buttons, and Labels” for details on documenting an application or utility with a Graphical User Interface (GUI).

File and Directory Names

Use for files and directories. For packages and modules, use <package>.

Packages and Modules

Use the <package> element for packages and modules, such as those which need to be installed for a particular application.

Example 6.11. <package> example




To install <application>Publican</application>, download the <package>publican</package> package.

To install Publican, download the publican package.

<package> requirements

The <package> element was introduced in DocBook version 4.4, so documents using older versions will need to update their DOCTYPE declaration to use it. A minimum version of DocBook version 4.5 is recommended. The DOCTYPE declaration can be updated with the following code at the top of the document:




<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [

...

]>

Parameter Names and Parameter Values

Use the <parameter> element when referring to the name of a parameter for a command. Use <literal> for the actual value of a parameter.

Example 6.12. <parameter> example




Use the <parameter>--help</parameter> parameter for assistance.

Use the --help parameter for assistance.

The <parameter> element can also be used for parameters in a method in a programming language. If both uses appear in the same document it may be necessary to differentiate them using the class attribute, which can be set to command, function, or option.

Program Names

Use the <application> element for software applications, for example, Mozilla Firefox.

Protocols

Use the <systemitem> element for protocols in general, such as SSH, TCP, telnet, CGI, and protocols in general.

User-replaceable Text

Use the <replaceable> element for marking descriptive text in a command or computer output which the user is expected to replace with text specific to their particular application. It describes what the user is expected to use, but not the actual text they should use.

Example 6.13. <replaceable> example




Edit <filename><replaceable>filename</replaceable>.xml</filename>

Edit filename.xml

Terminal Commands

Use the <command> element for entered commands, such as ls, top, find, mount, and bash. When referring to applications launched this way, also use <command>, for example, firefox. When describing lengthy commands it may be suitable to mark up additional parameters within the <command> element with the <parameter> element.

Terminal Command Output

Use the <computeroutput> element in-line with text to represent text that is shown on a computer screen, such as output from a command. For displaying output text in a block, use the <screen> element.

Example 6.14. <computeroutput> example




The application status will display <computeroutput>cleaning files</computeroutput>.

The application status will display cleaning files.

Text Displayed On-screen

Use the <screen> element to represent text that is shown on a screen, usually an output from a command. The text is shown in a block. For referring to display text in-line, use the <computeroutput> element.

Example 6.15. <screen> example




<screen>

books        Desktop   documentation  drafts  mss    photos   stuff  svn

books_tests  Desktop1  downloads      images  notes  scripts  svgs

</screen>

books        Desktop   documentation  drafts  mss    photos   stuff  svn
books_tests  Desktop1  downloads      images  notes  scripts  svgs

User Account Names

Use the <systemitem> element for user account names.

6.13. Code Examples

Code samples feature prominently throughout JBoss documentation. The correct XML element to use for XML and Java code block examples is the <programlisting> element.

<programlisting> has been used extensively throughout this user guide to highlight the XML structure you need to use in specific situations. There are two ways you will need to use this element within your user documentation.

An advantage of using <programlisting> is that you can specify the way Maven and Publican displays the information to the user. This is achieved using the language and role attribute. When language is defined, Publican will format the code example with highlighting that will assist the reader in understanding the code structure. The role attribute does the same when using Maven.

XML Samples

For XML samples, you must specify "XML" (in uppercase) as the language and role values.

The code for an XML program listing will look similar to the following example.


<programlisting language="XML" role="XML">

  <important>

    <title>Important Summary</title>

    <para>Information that will save the reader unnecessary

      frustration.</para>

  </important>

</programlisting>

When output, the XML elements are highlighted to assist the reader.


<important>

    <title>Important Summary</title>

    <para>Information that will save the reader unnecessary

      frustration.</para>

</important>

If XML is not specified, the output looks far less attractive.

<important>
    <title>Important Summary</title>
    <para>Information that will save the reader unnecessary
      frustration.</para>
</important>

Java Samples

For Java code samples, the same rules apply. Instead of "XML", "JAVA" is specified as the role attribute value and "Java" for the language attribute.



package org.jboss.book.jca.ex1;


import javax.naming.InitialContext;


public class ExClient

{

   public static void main(String args[]) 

       throws Exception

   {

      InitialContext iniCtx = new InitialContext();

      Object         ref    = iniCtx.lookup("EchoBean");

      EchoHome       home   = (EchoHome) ref;

      Echo           echo   = home.create();


      System.out.println("Created Echo");


      System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));

   }

   

}

Long code samples

For lengthy code samples of more then a couple of lines, it is preferable to use an <xi:include> to an external file which contains only the code sample. These code sample files should end in the relevant extension and should be placed in an extras/ directory located in the source language directory.

Java files use the java extension.
XML files use the xml_sample extension. When referencing an external XML file with the xml extension, Publican formats the file as though it were DocBook text. Using xml_sample avoids this.

Example 6.16. <programlisting> example




<example id="exam-JBoss_Documentation_Guide-Code_Examples-programlisting_example">

    <title>&lt;programlisting&gt; example</title>

<programlisting language="XML" role="XML">

<xi:include parse="text" href="extras/exam-JBoss_Documentation_Guide-Code_Examples-programlisting_example.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" />

</programlisting>

    <para>

        <xref linkend="exam-JBoss_Documentation_Guide-Code_Examples-programlisting_example"/> describes itself.

    </para>

</example>

Example 6.16, “<programlisting> example” describes itself.

In-Line Code Samples

Where <programlisting> presents the code in a separate block, there are multiple elements to use when using code samples in-line with other text.

Attribute, Property, and Parameter Values

Use the <literal> element for values of attributes, properties and parameters. In the Directory Server documentation, for example, the nsslapd-accesslog-level attribute can have values of 0, 4, 256, and beyond. The <literal> elements should be used for these values.

Alternatively, the <option> element can be used for those attributes, properties and parameters with a limited set of possible values, for example, a boolean value of true or false, or an enumerated type.

Use the <parameter> element when referring to the name of the parameter, attribute, or property itself. When writing the parameter and its value together, or the parameter and its method or class together, use the <code> element.

Classes (Java or similar)

Use the <classname> element in-line with text to mark classes or similar objects in programming languages. Typically it refers to a class in an object-oriented language, such as Java.

Example 6.17. <classname> example




Use the <classname>java.lang.Object</classname> class in an example.

Use the java.lang.Object class in an example.

When writing the class together with a method or parameter, use the <code> element.

Computer Programming Code In-line With Text

Use the <code> element in-line with text to mark computer programming code.

<code> Compatible with DocBook 4.3 Onwards

The <code> element was introduced in DocBook version 4.3. For <code> to be supported, documents must reference the correct DocBook version in the DOCTYPE declaration. A minimum version of DocBook version 4.5 is recommended. The DOCTYPE declaration can be updated with the following code at the top of the document:




<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [

...

]>

The <code> element does not offer syntax highlighting. To provide sample code in a block, use the <programlisting> element instead.

For simplicity, do not mark individual elements within a <code> element. If you feel identifying elements of the code is necessary for readability, the following elements are available:

<classname>
<literal>
<methodname>
<option>
<parameter>
<sgmltag>
<type>
<varname>
Any other code-related elements not covered in this section.

Example 6.18. <code> example

Java




Use <code>a.equals(b)</code> to determine if object <parameter>a</parameter> is equal to object <parameter>b</parameter>.

Use a.equals(b) to determine if object a is equal to object b.

XML




Use <code>&ltprogramlisting language="XML" role="XML"&gt</code> to mark <acronym>XML</acronym> code.

Use <programlisting language="XML" role="XML"> to mark XML code.

Data Types

Use the <type> element for data types, such as int, char, or boolean. Although the markup is not styled by Publican, it clarifies the term's use for translation. For actual values for data types, use the <literal> element.

Example 6.19. <type> example




Used for data types, such as <type>int</type>, <type>char</type>, or <type>boolean</type>.

Used for data types, such as int, char, or boolean.

Method or Constructor Parameter Names

Use the <parameter> element when referring to the name of a parameter for a method or constructor in a programming language. Use <literal> for the actual value of a parameter.

When writing the parameter and its value together, or the parameter and its method or class together, use the <code> element.

The <parameter> element can also be used for parameters in a command. If both uses appear in the same document it may be necessary to differentiate them using the class attribute, which can be set to command, function, or option.

Programming Methods

Use the <methodname> element in-line with text to mark the name of a method in a programming language.

If including the class to clarify the method name, include the whole class in the <methodname> element rather than marking the class part with <classname>.

Example 6.20. <methodname> example




Use the <methodname>java.lang.Object.toString()</methodname> method to get a <type>string</type> representation.

Use the java.lang.Object.toString() method to get a string representation.

When writing the method together with its class or parameters, use the <code> element.

Variable and Attributes Names (all languages)

Use the <varname> element when referring to the name of a variable in an object-oriented language such as Java, or the name of an attribute of an XML element. Use <literal> (or <option> if appropriate) for the actual value of a variable or attribute.

Example 6.21. <varname> example




Use the <varname>class</varname> attribute, which can be set to <option>command</option>, <option>function<option>, or <option>option</option>.

Use the class attribute, which can be set to command, function, or option.

XML Elements

Use the <sgmltag> element in-line with text to mark XML elements.

When writing the element together with attributes, use the <code> element.

Example 6.22. <sgmltag> examples




Use the <sgmltag>&ltexample&gt</sgmltag> element for examples.

Use the <example> element for examples.




Use the <code>id="[section_name]"</code> attribute of the <sgmltag><section></sgmltag> element to set the ID for the section.

Use the id="[section_name]" attribute of the <section> element to set the ID for the section.

6.14. Links and References

Cross-references within the book

Use the <xref> element to cross-reference a chapter, section, or other content block. The linkend attribute points to the target block's id attribute.

Example 6.23. <xref> example




For more details refer to <xref linkend="exam-JBoss_Documentation_Guide-Code_Examples-xref_example" />.

For more details refer to Example 6.23, “<xref> example”.

Links to external URLs

Use the <ulink> element to link to an external URL. The url attribute points to the target link, and must be a complete URL.

Example 6.24. <ulink> example




For further information, refer to <ulink url="http://www.jboss.org" />.

For further information, refer to http://www.jboss.org.

By creating the link without providing a link alias, the reader can see the full URL. This is especially important to consider if you are producing both print-ready and online documentation.

When you need to include a <ulink> that resolves to a lengthy URL, you may wish to supply a link alias so the link is formatted cleanly. The reader can see the full URL, however the information wraps to the next line which can be distracting to the reader. If you

Example 6.25. <ulink> link alias examples

Long URL without an alias:




For further information, refer to <ulink url="http://docs.fedoraproject.org/installation-quick-start-guide/f12/en-US/pdf/Fedora_12_Installation_Quick_Start_Guide.pdf"/>.

For further information, refer to http://docs.fedoraproject.org/installation-quick-start-guide/f12/en-US/pdf/Fedora_12_Installation_Quick_Start_Guide.pdf.

PDF documentation handles link aliases by creating a footnote at the bottom of each page. This formatting can distract readers because they have to follow the footnote number and locate the link at the bottom of the page.

Long URL with an alias:




For further information about installing Fedora 12, refer to the <ulink url="http://docs.fedoraproject.org/installation-quick-start-guide/f12/en-US/pdf/Fedora_12_Installation_Quick_Start_Guide.pdf">Installation Quick Start Guide</ulink>.

By constructing the sentence differently, you can include the link for those readers that access the online version of the documentation. Readers who prefer PDF documentation are also supported, because they know what to search for when they are next online.

References to external content

Use the <citetitle> element when referring to another book, article, website, or other form of external content.

Unlike the <xref> element, <citetitle> does not link to the referenced section, so if the name of the referenced book is changed the <citetitle> element will need to be updated manually. External links such as those using the <ulink> element should not be used to reference another book, as an external link may become outdated at a later time.

Example 6.26. <citetitle> example




Refer to <citetitle>DocBook: The Definitive Guide</citetitle> for further details.

Refer to DocBook: The Definitive Guide for further details.

mobicents-public

mobicents-core

Note

Do Not Update the all-*.xml File

JBCP Platform Documentation

Important

Full Sentence

Fragment Sentence

Run-on Sentence

Simple Run-on

Correct

Complex Run-on

Correct

Original Wording

Suggested Wording

Result

Original Wording

Suggested Wording

Result

Fallback Content Accuracy Check

Note

XML Copy Editor

Naming Chapter or Section XML Files

ID Attributes for Chapter or Section XML Files

Lead-in Sentence is Mandatory

<itemizedlist>

<orderedlist>

<variablelist>

Consider <variablelist> for two-column tables

Merging Cells Horizontally (spanning cells)

Open Office Package Dependencies

Install MSS for JBoss 0.7 or Later

<package> requirements

In-Line Code Samples

Links to external URLs

References to external content

Note

Note

Commit Regularly

Note

Re-review, or straight to editing?

Note

No Spell Check, No Edit

Note

Re-review, or Straight to Closure?

Note