1 |
Fellow developers, |
2 |
|
3 |
I would like you to answer three questions, without looking at some |
4 |
cheatsheet: |
5 |
|
6 |
a. what does dohtml do, exactly? |
7 |
|
8 |
b. what are the default file suffixes installed by dohtml? |
9 |
|
10 |
c. what are the options accepted by dohtml? what do they do? |
11 |
|
12 |
I doubt that most of the developers can answer those questions. Long |
13 |
story short, dohtml is a terribly overcomplex, confusing function that |
14 |
shouldn't really live in its current form. |
15 |
|
16 |
|
17 |
Bug #520546 gives some insight and numbers on the issues with dohtml |
18 |
and the scope of it. Most importantly: |
19 |
|
20 |
1. Many ebuilds use it as some kind of 'docinto html; dodoc -r ...' |
21 |
without even knowing that it does filtering by suffix. Some ebuilds |
22 |
fail to install some of the files because of that... |
23 |
|
24 |
2. The default suffix list will never fit everyone. Most people don't |
25 |
have an idea what's there, bugs asking to change it will keep |
26 |
happening, and requests for even more features [2,3]. |
27 |
|
28 |
3. The number of options exceeds any other PM command. Some of them are |
29 |
not used even once, some of them are used scarcely. Having so many |
30 |
options only increases confusion and makes reading ebuilds harder. |
31 |
|
32 |
4. By default, dohtml installs into $docdir/html. However, once docinto |
33 |
is used, it installs to whatever directory was specified there (without |
34 |
html subdir). One of the most confusing ideas ever invented. |
35 |
|
36 |
5. dohtml has pretty powerful filtering. doins doesn't have any. This |
37 |
is really upside-down that HTML documentation install command is more |
38 |
powerful than generic file install command... |
39 |
|
40 |
|
41 |
We've (me and ulm) have come up with the following ideas: |
42 |
|
43 |
1. make HTML_DOCS in EAPI6 use plain 'docinto html; dodoc -r ...' |
44 |
instead of dohtml, |
45 |
|
46 |
2. possibly remove dohtml from EAPI6 completely, |
47 |
|
48 |
3. ulm wants to reintroduce dohtml in an eclass for people who want to |
49 |
use it. I'd rather cover it with warnings signs and tell people not to |
50 |
touch it. IMHO a better replacement is the plain 'docinto html; dodoc |
51 |
-r ...', possibly with some extra filtering applied before or after |
52 |
install. |
53 |
|
54 |
What do you think? |
55 |
|
56 |
|
57 |
[1]:https://bugs.gentoo.org/show_bug.cgi?id=520546 |
58 |
[2]:https://bugs.gentoo.org/show_bug.cgi?id=423245 |
59 |
[3]:https://bugs.gentoo.org/show_bug.cgi?id=263808 |
60 |
|
61 |
-- |
62 |
Best regards, |
63 |
Michał Górny |