The reason being that this feature is now included in DocBook 5.1:

https://github.com/docbook/defguide/blob/docbook-5.2/src/defguide/appb.xml#L131

1. About use of keysym for key combinations
2. About use of keycombo without action attributes

Use of keysym for key combinations

keysym's description is below:

The keysym identifies the symbolic name of a key on a computer keyboard. This is distinct from any scan code that it may generate (keycode), or any text (keycap) that might be printed on the key.

However, some pages in the tdg.docbook.org reference, keysym is used to represent key combinations:
https://github.com/docbook/defguide/search?utf8=%E2%9C%93&q=keysym&type=

Here is one of such examples:

Is this usage (<keysym>C-x</keysym>) valid?
I think this is invalid use (because keysym "identifies the symbolic name of a key on a computer keyboard"), and it should be written as <keycombo action="simul"><keysym>C</keysym><keycap>x</keycap></keycombo> (for example) or something like that.

If <keysym>C-x</keysym> is ok, the description of keysym element should be changed.

Use of keycombo without action attributes

In the same parts of examples:

<keycombo><keysym>C-c</keysym><keysym>C-x</keysym></keycombo> is used and this seems to represent "sequential" combination.
But in the reference, action attribute is decribed as below:

If keycombo contains more than one element, simul is the default, otherwise there is no default.

The keycombo contains two keysyms, so this keycombo should have action="seq".
I think this should be fixed, whether the keysym use here is correct or nested keycombo should be used.

Via email.

From: Sasha Unknown
Subject: Bug report related to tdg.docbook.org
Date: September 20, 2021 at 10:38:46 MDT
To: [email protected]

Hello.

This message is really not a proposal but a bug report about the web-interface of the “DocBook 5.2: The Definitive Guide”
book https://tdg.docbook.org/tdg/5.2/index.html (probably it relates to other book versions as well, but I've just tried to
read 5.2). Sorry, if I've chosen a wrong recipient, but I've spend some time to find a proper one and this e-mail address is
the only active thing I've found (the SourceForge-backed bug tracker for DocBook seems to be dead for several years, while GitHub repo for DocBook seems to related only to the stylesheets, not to the documentation). I would be grad if you redirect my letter to the correct recipient or suggest me the one.

I thank you very much for the content of the book. But the web interface makes the book almost unreadable by
unexpectedly redefining hotkeys that are the most used during reading. Examples:

• I press Up/Down to scroll the current page. But absolutely unexpectedly, when I press Up, instead of scrolling the page up, web-browser (Google Chrome 93.0.4577.82) jumps to another page.

• I then press Alt+Left in attempt to return to the previous page. But absolutely unexpectedly browser redirects me some third page, not the one that I've just left (so I can't even return to the page which was taken away when I tried to scroll it page in a convenient way).

• And this happens so-o-o many times during reading and annoys so much.

• Pressing Home in order to return to the top of the page also leads to some unpredictable results.

I understand that you (or whoever implemented these scripts on the pages) tried to do it for good; that you intentionally
assigned Up key for going one level up, Left and Right keys for switching to the previous/next chapter and Home key to do
something useful as well. But, to be honest, all these functions are much much less useful than the original meanings of
these hotkeys. The ability to scroll up and down is crucial. (And no, PgUp and PgDown keys don't substitute the Up and
Down keys for real. PgUp and PgDown keys jump sharply. When a reader wants to scroll smoothly, just 1-2 lines, without
losing the focus point, they press Up and Down). Just try to compare how often you scroll up and down and how often you
need to jump the one-level-up page. While jumping level up is useful per se, but not at the cost of scrolling. Overriding
browser standard hotkeys like Alt+Left (Back) and Alt+Right (Forward) is a no way either.

Thanks for your attention. I really hope such pity but easy-to-fix peculiarities will be fixed soon.

namest
Specifies a starting column by name.
namest
Specifies a starting column by name.

The redirect from docbook.org points to tdg.docbook.org/{edition}/ and the GitHub pages provide no flexibility to change the default document. That means that "index.html" gets served up, but what we really want is to serve "docbook.html".

I don't think that's fixable, so I propose reworking the generated HTML so that the home page is index.html and the page for the index element is "index-hack.html" or something. :-(

The DefGuide contains a section about Safari Book Online which ends with a link to http://my.safaribooksonline.com/?portal=oreilly which does not work anymore.

Greetings,
Frank

In the course of getting 5.2 ready, I spent a bunch of time cleaning up the build. I've learned a lot about gradle since I started this build.

It'll be a complete refactor of the repo. It's been years since someone expressed an interest in translating it into another language, so I'm taking out the conceit that this is the English version. It's also unlikely that the build system for the 4.x edition survives at all so I'm taking that out.

Along the way, I hope to make new versions of the other docs as well. I'll bring publishers up to be a customization of 5.2 and see if the slides, website, and sdocbook variants can be made reasonable.

Trang does this:

      <db:refpurpose>A subscript (as in H<db:subscript>2</db:subscript>
O, the molecular formula for water)</db:refpurpose>

We need to get rid of that newline.

The background color is set but the foreground isn't, perhaps?

(Reported by Liam Quin on the xml.com slack.)

The link to Common linking attributes doesn't make it clear that the common attributes apply as well.

When I started using the v5.1 assembly functionality, I could not figure out how to set the title of a book. After reading http://tdg.docbook.org/tdg/5.1/ch06.html, I tried including an info section in my structure. This did not result in metadata for the rendered book.

@bobstayton kindly clarified that if I include my metadata in a merge element, the metadata in it will be rendered in an info element in the resulting book (or other renderas value).

I switched my structure/info to structure/merge and I now see the book metadata that I need.

I reread the TDG section about assemblies and it seems to me that the information is outdated. At the moment, it implies that:

• A title is valid as a child of structure.
• An info element for a structure or module and the metadata it contains will be copied into the resulting root element when rendered.

I think that section should describe how to use the merge element.

Problem

According to the DocBook RNG schema, there is an association element defined:

  db.association =
    ## Identifies the type of relationship between one or more resources
    element association { db.association.attlist, text? }

However, the reference at https://tdg.docbook.org/tdg/5.2/ref-elements.html never mentions that.

Possible solution

Add the missing element into the reference. 😉

Problem

Chapter "Assemblies", section "Relationships" contains a description about the relationship(s) structure.

The section shows this example:

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

However, this example is a bit misleading as it seems to be incomplete. The section and the example has the following issues:

• Does not mention <relationships> (plural!) element
• Does not distinguish between <relationships> (plural) and <relationship> (singular)
• Does not mention <association> element as it required in DocBook 5.2*

Possible solution

IMHO, we should amend this example like this:

<relationships>
  <relationship type="seealso">
    <association>???</association>
    <instance linkend="tut1"/>
    <instance linkend="tut2"/>
    <instance linkend="task1"/>
  </relationship>
</relationship>

Not sure what we should put inside the <association> element.

Related issue

docbook/docbook#214

When doing make -C en/defguide on a freshly cloned git source, I get this error:

Makefile:1: ../../buildtools/Makefile.incl: No such file or directory
make: *** No rule to make target '../../buildtools/Makefile.incl'.  Stop.

Is there a missing file or a step I failed to do to get this build going?

Per this thread.

On page https://tdg.docbook.org/ in section "DocBook 5: The Definitive Guide" there is a typo: I guess 1.5.3 should be 5.1.3 . See screenshot.

Maybe also mention deprecation of ulink?

It goes to index.html which is, uh, not the right page.

The moreinfo attribute has been removed in DocBook 5 and upwards. According to Bob, it's "replaced by the generalized linking with XLink with an arcrole attribute."

At the moment, this isn't mentioned in the TDG:
http://www.docbook.org/tdg5/en/html/ch01.html#ch-gsxml.4
http://www.docbook.org/tdg51/en/html/ch00-online.html#changes-in-51

Original thread on the docbook mailinglist:
https://lists.oasis-open.org/archives/docbook/201606/msg00000.html

See email.

See docbook/docbook#228

In the stylesheet for the book...

The DocBook Assembly schema is documented in chapter 6 of the TDG.

However, there are some differences between the current RELAX NG schema and its documentation.

For example:

• In Section 3.4 Relationships, there is a resourceref attribute whereas the RNC schema allows only an linkend.
• In Section 3.5 Transformations the documentation uses a type attribute, but the RNC schema hasn't one.
  The same section advises to use a type attribute on <output/> which is also not available in the RNC.
• In Section 4.1.2 Resources the documentation uses a <resource/> element without a href attribute (not allowed with the above RNC schema).
• In Section 4.1.3. Setting Up the Structure <output/> uses format instead of outputformat.

The whole chapter contains these little errors. I'd suggest to check it with the current RELAX NG implementation and correct all issues. :-)

Stefan Knorr reports:

I hope this is the right avenue for feedback for TDG.

On http://docbook.org/tdg51/en/html/simplesect.html , in "Description,"
a sentence says that there are "threetwo types of sectioning elements".

When looking at the tag <orderedlist> we have a.o. the attributes: numeration and startingnumber and these correspond with the attributes type and start of the HTML tag <ol>.
An item in HTML is given by means of the <li> tag and here we have the attribute value, the docbook equivalent of the HTML tag <li> tag is the <listitem> tag but here there is no value or similar tag present.

Request: would it be possible to add an attribute similar to the value attribute of the HTML <li> tag to the docbook <itemlist> tag?

Note: I'm not sure whether or not this is the right place for this request, in case this is not the case please point me to the right place.

Dang it.

Showing the changes for the most recent version in the preface is reasonable, but for someone interested in a longer history, there should be a comprehensive changelog.

They are apparently same-document links.