[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-doc-english
Subject:    [kde-doc-english] Proposal: add missing IDs to top-level tags of manuals
From:       Luigi Toscano <luigi.toscano () tiscali ! it>
Date:       2012-10-07 23:45:10
Message-ID: 50721406.8080303 () tiscali ! it
[Download RAW message or body]

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=21935&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-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 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

_______________________________________________
kde-doc-english mailing list
kde-doc-english@kde.org
https://mail.kde.org/mailman/listinfo/kde-doc-english
[prev in list] [next in list] [prev in thread] [next in thread]