[kde-doc-english] Proposal: add missing IDs to top-level tags of manuals

[T.C. Hollingsworth]

On Sun, Oct 7, 2012 at 4:45 PM, Luigi Toscano <luigi.toscano at tiscali.it> wrote:
> Hi all,
>
> I was pinged by Fedora packagers (more precisely Rex Dieter, in CC and I guess
> not subscribed) about this bug:
> https://bugzilla.redhat.com/show_bug.cgi?id=862388
>
> In the generated index.cache.bz2 of the sonnet manual you can see that an
> anchor tag was automatically added in the "area" of the title:
> <h2 class="title"><a name="idm7625248"></a>Check Spelling Dialog</h2></div>
>
> What happened here is that, if the "id" attribute for some tag (<article> for
> sonnet, or in some cases <book>) is not specified, a random one is generated,
> which is not guaranteed to be the same for different runs of the generation
> program.

Is this only a problem for the toplevel DocBook tags (<article> and
<book>)?  If meinproc4 generates random ids for tags like <sect1> and
<chapter> too, yum will still be unhappy.  (Of course, we might be so
awesome as to not be missing any ids for such tags.  ;-)

> The problem arise when a distribution, like Fedora, allows for co-installation
> of packages of different architectures, where the architecture-independent
> files shipped into co-installable arch-specific packages must be the same. But
> unfortunately this is not the case.
> (yes, a possible solution could be moving arch-independent stuff to a separate
> library, but if I understand it correctly in the Fedore build infrastructure
> they are generated anyway on all the architectures and they needs to match).

Actually, I think that would work, because Koji is smart and only
builds noarch subpackages once.  But, I really don't want to have
dozens of tiny kate-doc, kwrite-doc, etc. subpackages on my system
just to work around RPM's silly multiarch issues.

> Fedora packagers patched their packages to remove the generated anchors (<a
> name="<randomid>"></a>). So I was looking for a generic solution.
>
> It seems that there are _not_ easy ways to not generate those anchors, and by
> "easy" I mean by setting a parameter. I only found a parameter
> (generate.id.attributes) which writes the id into an id attribute for the
> associated tag instead of new anchor tag.

Yeah, that doesn't help at all.  (I'd very much like to turn it on in
the future, as it allows us to do cool stuff like highlight the
destination section when someone clicks a link in the TOC, but that
can wait until I offer up patches that make use of it.  ;-)

> There is a patch for docbook-xslt which will allow to generate a fixed IDs,
> but it is still pending:
> http://sourceforge.net/tracker/index.php?func=detail&aid=2929679&group_id=21935&atid=373747

The Fedora docbook-xsl maintainer might want to include that patch, as
KDE can't be the only software in the distribution hitting this issue.

> The only working solution is mentioned in the blog post which spawned that
> feature request, and would involve adding other instructions to our custom
> xslt layer:
> http://journal.dedasys.com/2009/09/07/stopping-docbook-version-control-churn
>
> which is feasible, but I was wondering if it would make sense to simply add
> fixed ids to our documents.
>
> The highest priority would be for files which are part of co-installable
> multiarch packages (usually libraries, like kdelibs, kdepimlibs, etc)..
> I forgot to mention that I volunteer for this (for 4.9 - at least for the most
> important ones - and master).

I can quickly script a fix for this for all docs in the project to
save you a lot of manual labor, if you'd like.  :-)

> I don't think it should affect the string extraction; a document regeneration
> for translated manuals is not needed, as this impact only the original
> document, packaged together with the code.
>
> Any comments would be highly appreciated :)
>
> Ciao
> --
> Luigi

-T.C.