As errors are discovered in The DITA Style Guide, they will be added on this page. Please report any errors you find, so that we can review, discuss, and correct the book in future editions.
Links to DITA Specification
A sentence in The DITA Style Guide says: “The online version of The DITA Style Guide will have links to the DITA Language Reference.” This does not refer to the ePub and Kindle electronic versions of the book, but to the future Web-based version of the book to be made available in two years time, when the whole book will become open source. Sorry for any confusion. (And thanks to Marcia Johnston for pointing out the problem.)
In the ePub version, which includes short descriptions (not included in the print version), there is incorrect pluralisation in the sentence: “The steps of a procedure are defined in a task topics.” The text should read: “The steps of a procedure are defined in a task topic.” That error in the short description text is repeated in the summary of that section. Thanks to Erlend Leganger for finding this error.
Parameters and Arguments Wrong Way Round
In the topic entitled “Parameter and variable names” in the Syntax and Mark-up chapter, the terms variables and parameters have been used the wrong way around. The lead-in sentence to the example of a program procedure should read “For example, in the <cmdname>CalcCharge</cmdname> procedure following, the parameters are…”. In the sentence following the example, the text should read “When the <cmdname>CalcCharge</cmdname> procedure is called, the values passed to the procedure are the arguments…”. And one paragraph down, the meaning is clearer if read as, “In some cases, the values of variables will be passed as arguments; that is, they will be a named substitute for the value.” Thanks to Erlend Leganger for finding these errors.
There is also a major problem in the code example, where pt and pd are the wrong way around. The example should be:
<p>The <apiname>CalcCharge</apiname> has two parameters:
<pd>The hourly rate charged to the client.</pd>
<pd>The total number of hours spent on the client’s project.</pd>
<p>Both <parmname>rate</parmname> and <parmname>hours</parmname> must be integer values. </p>
Thanks to Amy Kurtzman for identifying this problem.
In the “Messages displayed in a user interface” topic in the Syntax and Mark-up chapter, the phrase (in the second last paragraph, last sentence) “resulted displayed” should be “result displayed”. In the “Nested quotations” topic in the Language and Punctuation chapter, the short description (only included in the ePUB and Kindle versions of The DITA Style Guide) includes the word “withing”, which should be “within”. The word “characterized” is accidentally repeated in Australian English in the “Re-use and the DITA Maturity Model” topic in the Content Re-use chapter. Thanks to Erlend Leganger for finding these typos.
The processing-role Attribute
This is not really an error, but an omission. In DITA 1.2, the topicref element has a processing-role attribute. The Content Re-use chapter recommends marking up referenced conref source topics with the print, toc and linking attributes all set to “no”. While this is perfectly OK for DITA 1.1, in DITA 1.2 it is better to alternatively set the processing-role attribute to “resource-only”. Thanks to Erlend Leganger for this suggestion.
Glossary of Terms
In the topic entitled “Creating a Glossary of Terms” in the DITA Map Files chapter, a code example showing the abbreviated-form element has text content inside the tag. The abbreviated-form element has to be empty. The code example should be:
<p>Your car has <abbreviated-form keyref="abs"/>.
Thanks again to the eagle-eyed Erlend Leganger for spotting this error.
Include and Exclude Filtering Actions
In the topic entitled “Include and exclude filtering actions” in the Metadata, Conditional Processing, and Indexing chapter, it is incorrectly stated that if a paragraph was marked with values of admin and manager, and the ditaval specified that admin should be excluded, but manager included (or not mentioned), the paragraph would be excluded. For processing with the DITA Open Toolkit, this is incorrect. For an element with multiple conditions set in the same attribute to be excluded from the output, all exclude conditions must be specified in the ditaval.
Thanks to Wim Hooghwinkel for finding this error.
In the topic entitled “Cross-referencing tables” in the Cross-referencing chapter, an example showing a cross-reference to a table doesn’t match the text. The text refers to the example showing a table with an id of table_perf_data, but the example itself refers to an id of perfdata. The example should be:
<xref href="#concept_ej25_perf/table_perf_data" type="table"/>
Thanks to Roger Fienhold Sheen for identifying this error.
Conditions in Cross-references
In the topic entitled “Conditions in cross-references” in the Cross-referencing chapter, the code sample has the full stop (period) on the wrong side of close element tag. In that position, the full stop would be conditional, and would thus be omitted in some cases, leaving the sentence without closing punctuation. Further, the <xref> element isn’t correctly closed. The code sample should be:
<p>The coolant expansion tank is attached to the firewall<ph audience="help_user">, as shown in <xref href="c_engine_bay#eng_bay/fig_coolant_system" type="fig" /></ph>. </p>
Thanks to Roger Fienhold Sheen for identifying these errors.
In the topic entitled “Re-use guidelines” in the Content Re-use chapter, the word “manual” in redundant in the sentence in the last list item beginning:
“When the content needs to be re-used in a manual for a differently-badged product manual…”.
The relevant part of the sentence should read, “When the content needs to be re-used in a differently-badged product manual…”.
Thanks to Roger Fienhold Sheen for identifying this error.
Assorted Typos and Gremlins
A number of typos and other assorted gremlins have found their way into the following.
- “relcell” should be “relcell” in the topic “Types of relationship tables” in the DITA Map Files chapter.
- the word “use” has snuck into the sentence that should have read “In this case, you would enter the…” in “The copy-to attribute” topic in the DITA Map Files chapter.
- The Banjo Paterson quotation should have started with “There was movement…” rather than “The was movement…”, in the example in the “Keeping connected blocks together” topic in the Syntax and Mark-up chapter.
- The word “you” inadvertently appears in the note in the “Keeping connected blocks together” and “Lists within paragraphs” topics in the Syntax and Mark-up chapter. The relevant sentence should be: “you are writing for translation, avoid including text after a nested block inside
another block element.”
- In the list of character escapes, non-breaking space is listed twice. This occurs in “Non-breaking spaces and special characters” in the Syntax and Mark-up chapter.
- A space is missing before the opening bracket in the second last list item in the “Condition versus transclusion” topic in the Metadata, Conditional Processing, and Indexing chapter.
- The example of the result of a see also index should have been “See also turbocharger” rather than “See turborcharger”. This example occurs on the “Index see and see also” topic in the Metadata, Conditional Processing, and Indexing chapter.
Thanks to Frank Dissinger for identifying these errors.
In the Variables in DITA topic (Content Reuse), there is a quote mark missing from the code example (at the end of the “id” attribute).
Mandatory Elements in Constraints
In the topic entitled “Constraints” in the Authoring Concepts appendix, the explanation of the way constraints cannot make optional elements mandatory is incomplete. It should read as follows (with the changed area highlighted in bold):
A constraint can remove an optional element from a content model, make an otherwise optional element required, and modify the attributes of an element by adding attributes or making them required. However, a constraint cannot make a mandatory element optional, and nor can it remove a mandatory element.
Thanks to Frank Dissinger for identifying this error.
Error in Title: Restricting Tasks to One Procedure Only
The word “procedure” is incorrectly pluralised in the topic that should have been entitled “Restricting tasks to one procedure only” in the Syntax and Mark-up chapter.
Thanks again to Frank Dissinger for reporting this error.
Missing Word in Topic on -dita-use-conref-target
The word “include” is missing in the sentence which should read:
However, because that referencing tm element does not include a tmtype attribute, it is invalid.
Thanks to Dave Gash for reporting this error.
Incorrect Description of Glossary Linking
In the topic entitled “Glossary entry” (in Chapter 1: Information types and topics), the text refers to an href attribute of the term element. The term element does not have an href attribute. Further, the text implies that linking is part of the authoring process, when it is part of the publishing process. The offending sentence should correctly read:
The linking of a term occurring in-line in a normal content topic to its relevant glossentry definition is a matter of associating the term (semantically identified in a term element) with the key reference (keyref) of the glossary topic, and relying on the publishing process to create the link.
Thanks to Jim Owens for identifying this error.
Attribute Name Error
In the topic entitled “Indirect linking with keys” (in Chapter 6: Cross-referencing), the ditamap keys attribute is referred to incorrectly as the key attribute. The sentence with the error should read:
Key values are defined in a ditamap using the syntax keys=”target URI”.
Thanks again to Jim Owens for reporting this error.
Addition to Special Characters
Patrick Gribben has made the excellent suggestion of adding a non-breaking hyphen to the list of special characters in Chapter 3: Syntax and Markup. The code for a non-breaking hyphen is ‑.
Multimedia Code Example
The topic entitled “Multimedia in DITA Topics” (Chapter 5: Graphics and Figures) nominates two different SWF files in the code example. The example should be:
< object id="anim_ej25" data="../images/ej25.swf" type="application/x-shockwave-flash" width="350" height="100"> <param name="movie" value="../images/ej25.swf"/> <param name="quality" value="high"/> </object>
Thanks to Greg Dutkowski for identifying this error.