Bug#639663: [debian-policy] Please provide upgrading-checklist via web
Charles Plessy <plessy@debian.org> writes:
> Le Sun, Sep 04, 2011 at 09:13:14AM +0200, Raphael Hertzog a écrit :
>> On Sat, 03 Sep 2011, Giovanni Mascellani wrote:
>>> I though about this, but couldn't come up with any easy solution. I
>>> mostly consider this tool to be useful for people who just have to
>>> check the very last versions of the policy, so the problem is actually
>>> quite mitigated.
>>> I don't even think that old versions of the policy are available online.
>> Policy could start putting "id" attributes to sections linked from the
>> upgrading checklist. Then those references will be more stable that
>> plain section numbers.
> the Policy actually has already ID attributes in some of its sections,
> for instance 's-f-Architectureq for 5.6.8. It would indeed be a good
> idea to add IDs to other sections when we modify them.
> For links from the PTS to the checklist, the easy part would be to also
> add IDs in the checklist
> Using IDs, like this:
> <sect id='3.9.3.0'> Version 3.9.3.0
> The HTML document will have anchors like that:
> <h2><a name="s-3.9.3.0"></a>2.1 Version 3.9.3.0</h2>
> They will be easy to preserve if the checklist migrates to DocBook.
These both sound like good ideas to me and don't seem like they'd be too
difficult to maintain. If someone would like to send a patch to add the
missing id attributes, I'll merge it.
> Having nice HTML links from the upgrade checklist to the Policy's
> section numbers is more challenging, as it looks difficult to have links
> that would be valid on both www.debian.org and the users local disks.
> On users local disks:
> /usr/share/doc/debian-policy/policy.html/ch-*.html
> /usr/share/doc/debian-policy/upgrading-checklist.html/ch*.html
> or
> /usr/share/doc/debian-policy/upgrading-checklist-1.html
> On www.debian.org:
> /doc/debian-policy/ch-*.html
> This means we would need to install upgrading-checklist-1.html or
> upgrading-checklist-1.html/ in /doc, or to make adjustments or hardcode
> to the www.debian.org version.
My first inclination would be to change the debian-policy package to stop
generating the broken-down version of the upgrading-checklist that has
multiple HTML files (there doesn't seem to be much point for that
document), generate the one-page HTML version as just
upgrading-checklist.html, and put it into the debian-policy.html directory
instead of at the top level. Then, the links to Policy can just be to the
individual ch-*.html files and are relative within a directory, which will
make them work on both www.debian.org and on local disk.
The drawback to this, though, is that upgrading-checklist links to other
policies then don't work or are quite a bit harder.
We could rename the directory structure in debian-policy to match
www.debian.org, but /usr/share/doc/debian-policy/debian-policy looks
rather weird.
--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>
Reply to: