Fellow developers, I would like you to answer three questions, without looking at some cheatsheet:
a. what does dohtml do, exactly? b. what are the default file suffixes installed by dohtml? c. what are the options accepted by dohtml? what do they do? I doubt that most of the developers can answer those questions. Long story short, dohtml is a terribly overcomplex, confusing function that shouldn't really live in its current form. Bug #520546 gives some insight and numbers on the issues with dohtml and the scope of it. Most importantly: 1. Many ebuilds use it as some kind of 'docinto html; dodoc -r ...' without even knowing that it does filtering by suffix. Some ebuilds fail to install some of the files because of that... 2. The default suffix list will never fit everyone. Most people don't have an idea what's there, bugs asking to change it will keep happening, and requests for even more features [2,3]. 3. The number of options exceeds any other PM command. Some of them are not used even once, some of them are used scarcely. Having so many options only increases confusion and makes reading ebuilds harder. 4. By default, dohtml installs into $docdir/html. However, once docinto is used, it installs to whatever directory was specified there (without html subdir). One of the most confusing ideas ever invented. 5. dohtml has pretty powerful filtering. doins doesn't have any. This is really upside-down that HTML documentation install command is more powerful than generic file install command... We've (me and ulm) have come up with the following ideas: 1. make HTML_DOCS in EAPI6 use plain 'docinto html; dodoc -r ...' instead of dohtml, 2. possibly remove dohtml from EAPI6 completely, 3. ulm wants to reintroduce dohtml in an eclass for people who want to use it. I'd rather cover it with warnings signs and tell people not to touch it. IMHO a better replacement is the plain 'docinto html; dodoc -r ...', possibly with some extra filtering applied before or after install. What do you think? [1]:https://bugs.gentoo.org/show_bug.cgi?id=520546 [2]:https://bugs.gentoo.org/show_bug.cgi?id=423245 [3]:https://bugs.gentoo.org/show_bug.cgi?id=263808 -- Best regards, Michał Górny
signature.asc
Description: PGP signature
