Bug#872944: www.debian.org: Debian Policy Manual not fully published
Hello Russ, Sean and website team
Thanks for your mail.
El 23/08/17 a las 06:01, Russ Allbery escribió:
> Sean Whitton <spwhitton@spwhitton.name> writes:
>
>> The Debian Policy Manual just changed its HTML output and while the HTML
>> has published, the CSS and included images have not.
>
>> Looking at [1], the CSS and included images should have been published
>> because they're still installed to
>> /usr/share/doc/debian-policy/policy.html/. So I think this is a problem
>> on your end rather than ours. Please do reassign this bug if I'm wrong
>> about that, and thanks in advance for your help.
>
>> [1] https://anonscm.debian.org/cgit/debwww/cron.git/tree/parts/7doc
The CSS and images issue is solved now.
If you publish a future version of Debian Policy including a customized
theme, if that theme is in the _static folders, it will be shown too. If
the theme is in another folder, ping us, because the function
mvhtml_sphinx() in our
https://anonscm.debian.org/cgit/debwww/cron.git/tree/parts/7doc script
should be modified to include the new folder.
>
> Hi debian-www folks,
>
> Just a heads-up that we're fixing some more stuff and Policy 4.1.1.0 will
> be a bit different again (it's not yet uploaded). Here's what I currently
> have staged for the next version:
>
> * usr/share/doc/debian-policy/policy.html/ in the package will have the
> multi-file HTML version. This is a directory with a couple of
> subdirectories, and all the internal HTML links should be relative.> However, please note that some of the Javascript is symlinks to files
> that are shipped in the libjs-sphinxdoc package, so you may need a bit
> of machinery to turn those symlinks into real files.
These Javascript symlinks are present in the current version too, and
I'm thinking about how to solve this issue.
I've found that for the .js files to be "available" we need to unpack
these packages (in a similar fashion as we do with debian-policy package):
libjs-sphinxdoc
libjs-jquery
libjs-underscore
Then, the /usr tree that we create in the crondir/tmp for unpacking and
copying the manuals to the website, will be consistent, but until now we
were copying only documents or images under the /usr/share/doc folder in
that tree, and now we should copy *code* files under the
/usr/share/javascript folder too.
I'm not sure about the points below:
* If we should copy those javascript files to "live" under
www.debian.org/doc/policy-manual or in another place in the
www.debian.org site (or in cgi.debian.org?). For now, policy-manual is
the only manual using them, but maybe in the future, more manuals are
moved to use sphinx too. I'm not aware of any other piece of the website
using Javascript, so I have no references of a canonical place to copy
the files (we would also need to change the symlinks to point to that
place, but that's another topic).
* If we should use the packages from "sid" as we use for the
documentation packages, or stable, or backports...
* If the www-master.debian.org machine (and all the mirrors) should have
the libjs-sphinxdoc, libjs-jquery and libjs-underscore packages
installed, and we should find the way to use those from the website
(change the symlinks, I guess, to... which path?)
* Other solution?
I hope other website team members or DSA can shed a light on the best
way to solve this.
Cheers
--
Laura Arjona
https://wiki.debian.org/LauraArjona
>
> * usr/share/doc/debian-policy/policy-1.html will be the single-file HTML
> version. However, the Sphinix single-file version still requires static
> assets in usr/share/doc/debian-policy/{_images,_static} that will need
> to be in the right position relative to policy-1.html. These have the
> same symlinks to libjs-sphinxdoc.
>
> The current state in the archive right now only has the single-file
> version, and it is in the policy.html subdirectory. But we got feedback
> after this release that people really wanted both versions available.
>
> Unfortunately things might be just a touch chaotic for a bit as we work
> through finishing this reStructuredText conversion. Apologies for the
> extra work! We think the long-term result will be worth it both in terms
> of better output and in terms of a more maintainable Policy document.
>
Reply to: