Sec Nums Out of Synch between HTML and PDF Manual

[Tristano Ajmone]

Either:

• Fix numbering in PDF doc.
• Remove :sectnums!: suppression in source document.

Sections numbers between the HTML and PDF docs are out of synch: e.g. "§3.1. General Rules" of the HTML doc is §3.2 in the PDF document.

This seems to be due to the temporary suppression of sectnums for some sections. From the §3.1 example mentioned above, we find in manual_03.asciidoc:

:sectnums!:
== General Rules

The Alan language is [...]

:sectnums:
== An Adventure

which was intended to suppress the sec.num. for the intruoductiory sec. "General Rules", and start over from the next sec. This works as excpected in the HTML doc, but not so in the PDF version, which apprarently ignores the :sectnums!: attribute directive.

NOTE — Suppression of sec.num. in certain sections was done for legacy reasons, because the original ODT/PDF Manual did so. It was intended to preserve section numbering across various editions as close as possible — although this might not be possible due to the introudction of new sections.

[Tristano Ajmone]

Issue created on asciidoctor-fopub for this problem:

• asciidoctor/asciidoctor-fopub#98

[Tristano Ajmone]

From @mojavelinux's reply to Issue #98 on asciidoctor-fopub it seems that this is a problem intrinsic to the DocBook specs and backend, so chances are that there are no solutions.

I propose to remove suppression of sec.numbering in those (few) introductory sections at the beginning of chapters, for the sake of numbering consistency across output formats.

[Dan Allen]

In theory, if the section is a special section (like a dedication), it shouldn't be numbered. But even that is up to the DocBook toolchain.

[Thomas Nilefalk]

Yeah. Let's go with your suggestion, @tajmone.

[Tristano Ajmone]

Great! And a huge thank to @mojavelinux for having kindly joined in and helped us out of this conondrum!