Re: Bug#639663: [debian-policy] Please provide upgrading-checklist via web
Charles Plessy <plessy@debian.org> writes:
> Le Sun, Dec 25, 2011 at 09:58:37AM -0800, Russ Allbery a écrit :
>> 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.
> I think that despite this drawback it is a good thing to do, better be
> able to link cleanly to the Policy than to not be able to link cleanly
> anywhere at all.
> Here is a not-so-elegant patch that moves upgrading-checklist-1.html to
> policy.html/upgrading-checklist.html. The SGML version is not
> distributed anymore but could be added back if you prefer. The location
> of the compressed text version does not change, so the upgrading
> checklist would be the only document where the HTML and text versions
> are not side-to-side in the same directory. If you think this is
> troublesome, maybe it could be solved with a symbolic link ?
Thanks!
I thought about this more this morning, and realized that the real
solution to all of this is to make the upgrading checklist an appendix to
Policy. That way, we can use regular internal document links and let the
documentation build system resolve them and turn them into appropriate
links, and the upgrading checklist would naturally come as part of the
overall Policy document in every format.
However, I'd rather not do that work in DebianDoc-SGML (see the upcoming
long-term strategy message that I'll write later today). It feels better
as part of a more thorough overhaul when we're changing things around
anyway.
So, for right now, I committed a variation of your patch that does
something more minimal. It ships upgrading-checklist.html (the one-page
version) in policy.html and makes upgrading-checklist-1.html a symlink to
it, without changing anything else about the package layout. This should
make it easy for the existing www.debian.org deployment scripts to deal
with it until we do something more comprehensive.
This will happen in the next release, which I plan to upload some time
next week.
--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>
Reply to: