Recent changes to doc-requests

outdated info at http://www.docbook.org/whatis

Kevin Hawkins — Sun, 13 Sep 2015 18:04:40 -0000

I couldn't find any contact information on the webpages at docbook.org, so I'll report this here ...

The last sentence at http://www.docbook.org/whatis says that there are plans to develop an XML Schema, but it seems that these have already been developed (and published), so you'll want to update this text.

"DocBook 5.1: The Definitive Guide" V1.4.14 needs updates to be in sync with assembly.rng V5.1CR3 - More updates

Hussein Shafie — Thu, 14 May 2015 10:09:33 -0000

In my first post called

"DocBook 5.1: The Definitive Guide" V1.4.14 needs updates
to be in sync with assembly.rng V5.1CR3

I forgot the following discrepancies between the doc and the schema:

6. DocBook Assemblies

3.4. Relationships
http://docbook.org/tdg51/en/html/ch06.html#relationships

In the following example:

<relationship type="seealso">
  <instance resourceref="tut1"/>
  <instance resourceref="tut2"/>
  <instance resourceref="task1"/>
</relationship>

and also in:

<relationship type="path">
  <info>
    <title>New User Introduction</title>
  </info>
  <instance resourceref="over1"/>
  <instance resourceref="over2"/>
  <instance resourceref="task3"/>
  <instance resourceref="cleanup"/>
</relationship>

Attribute resourceref should be replaced by attribute
linkend. (Or is it the schema which is incorrect, because
attribute resourceref is also used on element merge in
addition to elements structure and module.)

II. DocBook Assembly Element Reference

"Attributes" in element instance:
http://docbook.org/tdg51/en/html/instance.html

Please explain attribute linking by giving an example of its use.

"Processing expectations" in element relationship:
http://docbook.org/tdg51/en/html/relationships.html

Please explain how the links specified by relationships and
relationship elements are added to the realized document.

"Processing expectations" in element relationships:
http://docbook.org/tdg51/en/html/relationships.html

Same comment as above.

Clarifications needed about common attributes processing in an assembly

Hussein Shafie — Sun, 10 May 2015 08:28:28 -0000

In my understanding, something like: snippet #1:

<module>
  <output renderas="appendix"/>
  <info>
    <title>Troubleshooting spindle and bearing problems</title>
  </info>

or like this (where "tut3" points to a topic having no
xml:id and containing no info element other than a title):
snippet #2:

<module resourceref="tut3">
  <output renderas="appendix"/>
  <merge>
    <title>Troubleshooting spindle and bearing problems</title>
  </merge>

gives the following realized structure:

<appendix>
  <info>
    <title>Troubleshooting spindle and bearing problems</title>
  </info>

My questions are then:

How to add or replace common attributes to/in the realized
structure?
How to add info elements to the realized structure?

Let's suppose I want the realized structure to be:

<appendix xml:id="spindle_bearing_problems">
  <info>
    <title>Troubleshooting spindle and bearing problems</title>
    <author><orgname>ACME Corp.</orgname></author>
  </info>

(1) Do I need to change snippet #1 to:

<module xml:id="spindle_bearing_problems">
  <output renderas="appendix"/>
  <info>
    <title>Troubleshooting spindle and bearing problems</title>
    <author><orgname>ACME Corp.</orgname></author>
  </info>

or is it:

<module>
  <output renderas="appendix" xml:id="spindle_bearing_problems"/>
  <info>
    <title>Troubleshooting spindle and bearing problems</title>
    <author><orgname>ACME Corp.</orgname></author>
  </info>

(2) Do I need to change snippet #2 to:

<module resourceref="tut3">
  <output renderas="appendix"/>
  <merge xml:id="spindle_bearing_problems">
    <title>Troubleshooting spindle and bearing problems</title>
    <author><orgname>ACME Corp.</orgname></author>
  </merge>

In "DocBook 5.1: The Definitive Guide" V1.4.14, II. DocBook
Assembly Element Reference, I can read:

Element structure
http://docbook.org/tdg51/en/html/structure.html

Common attributes on the structure element are generally copied onto the
output root element.

However there is no such indication on element module
http://docbook.org/tdg51/en/html/module.html which seems
to be inconsistent because a structure is basically a top
level module.

Element merge
http://docbook.org/tdg51/en/html/merge.html
- How to merge (that is, add or replace) common attributes is not
  specified.
- I can read:
  
  When used in a module, the merge element indicates
  elements in the meta-information of the included resource
  that should be replaced with the content of the merge
  element.
  
  Each element in the merge replaces all elements of
  the same name in the meta-information of the
  included resource.
  
  But what about adding info elements? Shouldn't the
  above paragraph read:
  
  When used in a module or in a structure, the merge
  element indicates elements in the meta-information of the
  included resource that should be merged, that is added or
  replaced, with the content of the merge element.

"DocBook 5.1: The Definitive Guide" V1.4.14 needs updates to be in sync with assembly.rng V5.1CR3

Hussein Shafie — Sat, 09 May 2015 09:56:26 -0000

I'm using the DocBook V5.1CR3 RELAX NG Schema of assemblies
as a reference and after carefully reading everyting related
to assemblies in "DocBook 5.1: The Definitive Guide"
V1.4.14, I think I've found the following discrepancies:

6. DocBook Assemblies

All over this chapter:
http://docbook.org/tdg51/en/html/ch06.html
- Attribute type is discussed in many places. However
  according to the schema, only structure has a type
  attribute, not elements output, filterin, filterout.
  
  Moreoever, attribute type is set on elements output,
  filterin, filterout in several examples.
  
  In my understanding, except on element structure, attribute
  type should be replaced by attribute outputformat.
- In some examples, attribute format is set on element
  output. In my understanding, attribute type should be
  replaced by attribute outputformat.
"3.5. Transformations"
http://docbook.org/tdg51/en/html/ch06.html#transformations

A use case for attribute grammar should be given.

4.1. Describing a Help System with an Assembly,
Example 6.1. Resources for a Help System
http://docbook.org/tdg51/en/html/ch06.html#assemblies.15.6

Some resource elements are missing required attribute href.

4.1. Describing a Help System with an Assembly,
Example 6.3. The Front End
http://docbook.org/tdg51/en/html/ch06.html#assemblies.15.6

A module element cannot contain <toc/> or <index/>. In my
understanding, one should reference a resource pointing to a
topic containing <toc/> or <index/>.

1. Example: Assembling a Printed Book
  http://docbook.org/tdg51/en/html/ch06.html#ex-book

Same problem as above.

1. Example: Assembling a Printed Book
  http://docbook.org/tdg51/en/html/ch06.html#ex-book

In paragraph and in the example which follows:

Instead, we introduce one more convention: if a module
refers to another resource and contains an info element,
then the elements within that info replace any elements of
the same name in the referenced resource's metadata. (If the
referenced resource has no metadata, then the specified info
becomes the first child of the referenced resource.)

in my understanding, element info should be replaced by element merge.

1. Example: Assembling an Online Book
  http://docbook.org/tdg51/en/html/ch06.html#ex-html

Same problem as above in the example.

1. Example: Assembling an Online Book
  http://docbook.org/tdg51/en/html/ch06.html#ex-html

Please clarify the effect of elements filterin, filterout on
the contents pulled from the resource referenced by a
module.

For example, just writing "print only content is excluded
globally" to describe

<structure xml:id="user-guide">
    ...
    <filterout type="web" condition="print"/>

is not very clear.

(In contrast, writing "If no conditions are specified on
filterout, the module is unconditionally excluded" is quite
clear.)

II. DocBook Assembly Element Reference

"Examples" in element transform:
http://docbook.org/tdg51/en/html/transform.html

attribute fileref must be replaced by attribute href

"Attributes" in element structure:
http://docbook.org/tdg51/en/html/structure.html

Please clarify attributes type, defaultformat.

More comments on TCG, 4th edition

Mauritz Jeanson — Fri, 15 Jan 2010 19:59:37 -0000

1. http://www.sagehill.net/docbookxsl/IndexOutput.html (page 312)

Here it says: "Characters such as a, à, and ä should sort together, but they do not."

This needs some clarification, since it varies a lot between languages. For example, Swedish has a (U+0061) and ä (U+00E4) characters, and they should not be sorted together.

2. http://www.sagehill.net/docbookxsl/Chunking.html#ControllingChunks (pages 67-68)

Quote: "When you use this process, you must have an id attribute on every element that you want to start a new chunk. This includes the document element, which generates the title page and table of contents. You can see which elements do not have an id by examining the generated TOC file and looking for empty id attributes in the tocentrys."

As far as I can tell, there is no need to have id attributes on every element that should start a new chunk. If there are no IDs, they are autogenerated (and btw, the tocentrys don't have id attributes; they have linkend attributes.)

man.string.subst.map example uses undefined ss namespace

Peter Eisentraut — Sun, 02 Aug 2009 20:10:48 -0000

The examples for the man.string.subst.map parameter use an ss namespace like <ss:substitution>, but this namespace is not defined anywhere and turns out not to be necessary. It should be removed from the documentation.

Wrong the first name of pan Kosek

Yuri Zhilin — Thu, 16 Apr 2009 09:41:35 -0000

In the pdf under the book title where all persons are mentioned the first name of pan Kosek looks somehow strangely

Needless words after sentence

Yuri Zhilin — Thu, 16 Apr 2009 09:38:38 -0000

In the description of the parameter title.margin.left there is:
"... Currently this method is only used for FOP
because it cannot properly use the body.start.indent parameter. the relative"
That "the reletive" I mean as needless, but maybe there should be somthing meaningfull...

Errors in TCG, 4th edition

Mauritz Jeanson — Sat, 12 Jul 2008 14:16:36 -0000

Here are some minor errors in Docbook XSL TCG, fourth edition.

1. http://www.sagehill.net/docbookxsl/OnlineResources.html (page 5)

The address to the SF account registration page is https://sourceforge.net/account/registration/
(as of 2008-07-12).

2. http://www.sagehill.net/docbookxsl/ToolsSetup.html#Validation (page 14)
"For example, xsltproc includes a program called xmllint...".

This is not correct: xmllint is not part of xsltproc; it comes with the libxml2 library.

3. http://www.sagehill.net/docbookxsl/InstallingAProcessor.html (pages 24, 25, 26)

Replace "xalan25.jar" with "xalan27.jar".

4. http://www.sagehill.net/docbookxsl/SpecialChars.html#MissingChars (page 331)
"Most XSLT processors do not do full validation, but they do load the entities defined in the DTD."

http://www.sagehill.net/docbookxsl/ToolsSetup.html#Validation (page 13)
"Most XSL processors won't automatically take the time to validate your document while it is converting it to HTML or XSL-FO".

Both these sentences are a little misleading: the XML parser does the validation and loading of entities.

5. http://www.sagehill.net/docbookxsl/OtherOutputForms.html#XhtmlXsltproc (page 409)
"The head element includes an XHTML namespace declaration"

Wrong: it is the "html" element that has the namespace declaration.

dbhtml_bgcolor PI documentation addition (minor)

Matthew Creech — Tue, 20 May 2008 17:50:16 -0000

The text:

Use the <?dbhtml bgcolor?> PI as child of a table row or cell to set a background color for that table row or cell.

should probably be modified to indicate that this PI only works for CALS tables, not HTML tables.