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

[Burkhard Lück]

Am Montag, 8. Oktober 2012 01:45:10 schrieb Luigi Toscano:
> 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.
> 
> 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).
> 
> 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.
> 
> 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=2
> 1935&atid=373747
> 
> 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-chur
> n
> 
> 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 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 :)

We have 116 article markup, 43 of them with an id and 207 book markup, 7 of 
them with an id.

Makes sense to add the missing id's

-- 
Burkhard Lück