RDoc generated documentation available in rubygem-*-doc subpackages
suffers the similar issues and I honestly don't know how to fix this
situation.
Best would be if upstream acknowledged that the generated documentation
does not need to contain the copy of template including JS and what not.
The template could be shared among the generated documentation.
The other possibility is to grant some exception to generated documentation.
Vít
Dne 28. 09. 21 v 0:54 Fabio Valentini napsal(a):
On Mon, Sep 27, 2021 at 3:35 PM Ben Beasley <code@xxxxxxxxxxxxxxxxxx> wrote:
One last follow-up:
It turns out that even the situation with Doxygen is worse. The file
jquery.js inserted by Doxygen was not just a copy of JQuery (js-jquery)
to be unbundled; it also contained in the same file:
- JQuery UI (js-jquery-ui)
- jquery.ScrollTo (https://github.com/flesler/jquery.scrollTo/)
- PowerTip (https://stevenbenner.github.io/jquery-powertip/)
- JQuery UI Touch Punch (js-jquery-ui-touch-punch)
- SmartMenus jQuery Plugin (http://www.smartmenus.org)
It’s possible to account for all of these, package the missing ones
separately, and reconstruct the bundle using unminified sources (or
patch the generated HTML to use separate script tags, yuck), but the
burden is getting ridiculous again. It looks like dropping all
Doxygen-based HTML documentation, or building a less-useful PDF instead,
will be the sensible (but disappointing) outcome.
Thank you for starting this conversation, I had similar thoughts when
I last touched my .spec files for packages that build docs for Python
(with sphinx) or C (with doxygen).
In my opinion, building PDFs instead of HTML docs would actually be an
improvement in at least some ways:
There's no weird bundled JavaScript libraries, and docs can get
shipped as a single file (?) instead of lots and lots of small HTML /
JS / CSS files (with questionable licenses).
PDF is probably as "standard file format" today as HTML (even most web
browsers can open them), and probably all Fedora Editions and Spins
ship with a PDF viewer anyway (most of which also have good Ctrl-F and
PDF chapter bookmark functionality, which is way nicer than clicking
through dozens of hyperlinks in HTML docs).
At any rate, discoverability of pre-built docs from Fedora packages is
very poor to start with:
- most are hidden away in a separate -doc subpackage that doesn't get
installed by default
- even if the package is installed, the user has to manually navigate
their file browser to /usr/share/doc/foo/html/ (or similar), then open
the "index.html" file, and hopefully not forget to add a browser
bookmark for it
So, I'm not sure if the benefits of building HTML (or PDF, for that
matter) docs actually outweighs the headache they often cause.
Fabio
_______________________________________________
packaging mailing list -- packaging@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe send an email to packaging-leave@xxxxxxxxxxxxxxxxxxxxxxx
Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/
List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines
List Archives: https://lists.fedoraproject.org/archives/list/packaging@xxxxxxxxxxxxxxxxxxxxxxx
Do not reply to spam on the list, report it: https://pagure.io/fedora-infrastructure
_______________________________________________
packaging mailing list -- packaging@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe send an email to packaging-leave@xxxxxxxxxxxxxxxxxxxxxxx
Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/
List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines
List Archives: https://lists.fedoraproject.org/archives/list/packaging@xxxxxxxxxxxxxxxxxxxxxxx
Do not reply to spam on the list, report it: https://pagure.io/fedora-infrastructure
