| Summary: | [Future EAPI] Ban dohtml | ||
|---|---|---|---|
| Product: | Gentoo Hosted Projects | Reporter: | Ulrich Müller <ulm> |
| Component: | PMS/EAPI | Assignee: | PMS/EAPI <pms> |
| Status: | RESOLVED FIXED | ||
| Severity: | normal | CC: | bircoph, esigra |
| Priority: | Normal | ||
| Version: | unspecified | ||
| Hardware: | All | ||
| OS: | Linux | ||
| Whiteboard: | in-eapi-7 | ||
| Package list: | Runtime testing required: | --- | |
| Bug Depends on: | |||
| Bug Blocks: | 174380 | ||
|
Description
Ulrich Müller
2014-08-22 14:10:43 UTC
Or even try to deprecate and kill it altogether. I doubt that many of the uses of dohtml are done because of the filtering and other magic. It would be really useful to estimate the impact of replacing 'dohtml' with 'docinto html; dodoc -r'. Use of dohtml options: -r: 726 packages -V: not used at all -A: 32 packages -a: 19 packages -f: not used at all -x: 4 packages -p: 7 packages Suffixes added by -A: api c cgi chm css dia erl gif h hhc hhp hrl ico info java jpg kwc odg pdf png py README setup sql svg tpl txt web xhtml xml xpm (yes, we have a few occurences of filenames there, and some uses of '.foo' rather than 'foo') -x is used to either avoid CVS or some random Sphinx files. Or -- in one case -- to do something as dumb as 'dohtml *' in top-level directory. Long story short, most of this is self-inflicted complexity. The function itself confuses people, and is prone to mistakes. I am now running rebuild of packages installing HTML docs with PORTAGE_DOHTML_WARN_ON_SKIPPED_FILES=yes. Oh, and for comparison: 1466 packages call 'dodoc' directly, 261 specify HTML_DOCS. I suspect there may be some use via eclasses too. (and by package I mean the whole directory, didn't count each ebuild) Small update: out of 123 html-installing packages I've rebuilt, 16 of them would install extra files if dohtml is replaced with dodoc. For most of those cases, it seems that the command is supposed to find HTML docs inside generic doc directory with other kind of docs or build files.
In some cases it's .pdf or .ppt file that doesn't get installed. In two cases (gd and libsdl), dohtml is run on whole ${S}...
Tomorrow, I will try expanding the list using 'USE=doc emerge --newuse ...'
Ok, after doing full @world rebuild with USE=doc, I count 68 packages where dohtml skips some files, where the rebuild involved 220 extra packages. Per yesterday's council decision: - dohtml to be deprecated in EAPI 6 (most likely won't be part of the spec, but a repoman check or similar). Recommended replacement is "dodoc -r". - dohtml to be banned in EAPI 7. - einstalldocs in EAPI 6 must not use dohtml (this was seen as an obvious consequence, therefore no vote taken). - The council did not make any statement about eclasses. http://www.gentoo.org/proj/en/council/meeting-logs/20140909.txt (In reply to Ulrich Müller from comment #6) > Per yesterday's council decision: > - dohtml to be deprecated in EAPI 6 (most likely won't be part of the spec, > but a repoman check or similar). Recommended replacement is "dodoc -r". In some cases html source directories contain a bloody mix of needed and unneeded files. A complicated scripting will be required to fix all this if dohtml is removed at all. Though, if it will be moved to some eclass, I'm OK with this. The bug has been referenced in the following commit(s): https://gitweb.gentoo.org/proj/portage.git/commit/?id=9326ac37c0163b111397594c289e728f3dcd4ad7 commit 9326ac37c0163b111397594c289e728f3dcd4ad7 Author: Michał Górny <mgorny@gentoo.org> AuthorDate: 2017-09-21 14:35:47 +0000 Commit: Michał Górny <mgorny@gentoo.org> CommitDate: 2018-03-04 21:03:52 +0000 Ban dohtml for EAPI 7 Bug: https://bugs.gentoo.org/show_bug.cgi?id=520546 bin/eapi.sh | 6 +++++- bin/ebuild-helpers/dohtml | 7 ++++++- 2 files changed, 11 insertions(+), 2 deletions(-)} The bug has been referenced in the following commit(s): https://gitweb.gentoo.org/proj/pms.git/commit/?id=5dc82247b747fc03e22cfeabe001aae5d64bc3d8 commit 5dc82247b747fc03e22cfeabe001aae5d64bc3d8 Author: Ulrich Müller <ulm@gentoo.org> AuthorDate: 2015-11-15 17:20:13 +0000 Commit: Ulrich Müller <ulm@gentoo.org> CommitDate: 2018-03-31 15:30:43 +0000 EAPI 7: dohtml banned. Bug: https://bugs.gentoo.org/520546 eapi-differences.tex | 4 ++++ pkg-mgr-commands.tex | 20 ++++++++++++-------- 2 files changed, 16 insertions(+), 8 deletions(-)} |
