Re: root-doc subpackage slightly obese
Chen Lei wrote: How about qt-doc? Currently, it bundles src/qch/html docs, the src image files are completely useless and duplicate with files in html directory. The content of the qch and html docs is identical, since assistant_adp is dropped by qt 4.7, I suggest to split html docs into another subpackage or simply drop html docs. Personally, I only use assistant to open qch format docs. Yes, qt-doc should be split per format. Dropping the HTML docs entirely (in favor of the QCH) is also something I'd consider (for all Qt-based libraries). IMHO, showing those docs is what Qt Assistant is for. We'll discuss this in the meeting. (That said, assistant_adp is NOT dropped in Fedora, we ship a qt-assistant- adp compatibility package because some apps need it. But viewing Qt docs in the compatibility Assistant isn't of much use.) Kevin Kofler -- devel mailing list devel@lists.fedoraproject.org https://admin.fedoraproject.org/mailman/listinfo/devel
Re: root-doc subpackage slightly obese
Jonathan Underwood wrote: As I said in the bug report, I don't think building docs client side is the right way to go at all. In the general case this would require end users to install extra tools to build the docs, and defeats the purpose of a package managed system such as Fedora. +1 It also bypasses RPM's file ownership system. Scriptlets should really ONLY be used when it is IMPOSSIBLE to package the files in another way. (See also how dropping files into a someconfig.d is preferred to scriptlets tweaking someconfig.) Fedora is NOT a source-based distribution. Whatever can be generated on the build system MUST be generated on the build system, not on the client. Kevin Kofler -- devel mailing list devel@lists.fedoraproject.org https://admin.fedoraproject.org/mailman/listinfo/devel
Re: root-doc subpackage slightly obese
Jonathan Dieter wrote: While in the general case, I would agree with you, in this specific case, I think it's worth building on the client. 687MB is a very large download, over 90 minutes on a 1mbit/s link, and 45 minutes on a 2mbit/s link. Because of the large size and number of files, it also takes a non-trivial amount of time to actually install the rpm; on my laptop six minutes. In comparison, generating the html documents after installing root-* (excluding root-doc) took 37 minutes on my laptop. The total install time is the same for someone with someone with a 3mbit/s link, and client-side building is faster for someone with a slower link. At what point would you say it's worth the tradeoff? You need to also think of slow computers. My Pentium 4 Northwood is not going to be as fast at generating the files than a Core i7. And a Pentium Pro (the oldest CPU we support) is going to be a lot slower than even my P4. As for the Internet connection: I've just downloaded root-doc in 4 minutes, at 2.5 megaBYTES per second. And that's in Vienna, Austria. There are places with even faster Internet connections. Not everyone has slow Internet and a fast CPU. In my case, it'd take 20+ times as long to build the documentation on the client than to download it! Plus, there's also other technical issues, e.g. that the files generated that way bypass RPM's file ownership concept. Kevin Kofler -- devel mailing list devel@lists.fedoraproject.org https://admin.fedoraproject.org/mailman/listinfo/devel
Re: root-doc subpackage slightly obese
Jonathan Dieter wrote: I've taken a look at the root source rpm, and it looks like root-doc is generated by root itself *after* root has been completely built (rather than as part of root's build process). I've opened a bug, https://bugzilla.redhat.com/show_bug.cgi?id=621812 suggesting that the documentation generation be moved even later, into the %post section of the root-doc install. This means the documentation will be generated on the user's machine, eliminating the need for a massive download. In addition to the issues I pointed out elsewhere in this thread, this means you need to install the source code (!) of the package on the client. This is in itself a significant download and it's something Fedora does not normally do. Kevin Kofler -- devel mailing list devel@lists.fedoraproject.org https://admin.fedoraproject.org/mailman/listinfo/devel
Re: root-doc subpackage slightly obese
Toshio Kuratomi wrote: Depending on the technologies and applications involved I could see duplication being okay when one format is meant for people utilizing less /usr/share/doc/foo/* vs running /usr/bin/documentationviewer or /usr/bin/programmer-ide That's the case for the KDE stuff: plain HTML is for plain browsers, QCH is for Qt Assistant and KDevelop. The only issue is: kdelibs-apidocs is one of the largest binary packages in Fedora… But IMHO we'll really want that QCH. (In fact, we've been discussing building it for a while, I've just been caught up in other stuff.) KDevelop not showing KDE apidocs is a poor state of affairs and a regression from Fedora 12 / KDevelop 3.5. At least the QCH is one file, so it won't bloat the file list in the repository metadata. :-) FYI, I've put up QCH apidocs for discussion in the next KDE SIG meeting (Tuesday 14:00 UTC / 16:00 CEST / 10:00 (AM) EDT / 07:00 (AM) PDT). Kevin Kofler -- devel mailing list devel@lists.fedoraproject.org https://admin.fedoraproject.org/mailman/listinfo/devel
Re: root-doc subpackage slightly obese
I wrote: As for the Internet connection: I've just downloaded root-doc in 4 minutes, at 2.5 megaBYTES per second. And that's in Vienna, Austria. There are places with even faster Internet connections. PS: That's my HOME connection. You don't want to know how fast I could download that file at my university. :-p Kevin Kofler -- devel mailing list devel@lists.fedoraproject.org https://admin.fedoraproject.org/mailman/listinfo/devel
Re: root-doc subpackage slightly obese
2010/8/9 Kevin Kofler kevin.kof...@chello.at: Toshio Kuratomi wrote: Depending on the technologies and applications involved I could see duplication being okay when one format is meant for people utilizing less /usr/share/doc/foo/* vs running /usr/bin/documentationviewer or /usr/bin/programmer-ide That's the case for the KDE stuff: plain HTML is for plain browsers, QCH is for Qt Assistant and KDevelop. The only issue is: kdelibs-apidocs is one of the largest binary packages in Fedora… But IMHO we'll really want that QCH. (In fact, we've been discussing building it for a while, I've just been caught up in other stuff.) KDevelop not showing KDE apidocs is a poor state of affairs and a regression from Fedora 12 / KDevelop 3.5. At least the QCH is one file, so it won't bloat the file list in the repository metadata. :-) FYI, I've put up QCH apidocs for discussion in the next KDE SIG meeting (Tuesday 14:00 UTC / 16:00 CEST / 10:00 (AM) EDT / 07:00 (AM) PDT). Kevin Kofler How about qt-doc? Currently, it bundles src/qch/html docs, the src image files are completely useless and duplicate with files in html directory. The content of the qch and html docs is identical, since assistant_adp is dropped by qt 4.7, I suggest to split html docs into another subpackage or simply drop html docs. Personally, I only use assistant to open qch format docs. Regards, Chen Lei -- devel mailing list devel@lists.fedoraproject.org https://admin.fedoraproject.org/mailman/listinfo/devel
Re: root-doc subpackage slightly obese
On Fri, 2010-08-06 at 06:27 +0100, Jonathan Underwood wrote: On 5 August 2010 21:49, Toshio Kuratomi a.bad...@gmail.com wrote: Yaah -- so if it's useful documentation, then I'd be against creating a rule that bans it. The next question would be whether it's useful or not Public vs private certainly sounds like one thing to look at. However, some libraries might want to ship information about their private interfaces for people who want to help hack on the library so it's not a 100% thing that I'd want to enforce with a Guideline Perhaps in these two specific cases it would be best to open bugs for the maintainers to look at whether some of the documentation in here isn't considered useful and could be left out. I have to agree with Toshio here - it would be a bad move to be banning sub-packaged docs. In the case of root I can say that the root docs sub-package is very useful. Sigh. No one is suggesting banning sub-packaged docs. I find them quite useful myself. My suggestion was to limit the size of automatically generated documentation. However, the feedback I'm getting seems to suggest that a number of people disagree with me. :) I've taken a look at the root source rpm, and it looks like root-doc is generated by root itself *after* root has been completely built (rather than as part of root's build process). I've opened a bug, https://bugzilla.redhat.com/show_bug.cgi?id=621812 suggesting that the documentation generation be moved even later, into the %post section of the root-doc install. This means the documentation will be generated on the user's machine, eliminating the need for a massive download. Jonathan signature.asc Description: This is a digitally signed message part -- devel mailing list devel@lists.fedoraproject.org https://admin.fedoraproject.org/mailman/listinfo/devel
Re: root-doc subpackage slightly obese
On Fri, 06 Aug 2010 11:03:46 +0300
Jonathan Dieter wrote:
On Fri, 2010-08-06 at 06:27 +0100, Jonathan Underwood wrote:
On 5 August 2010 21:49, Toshio Kuratomi a.bad...@gmail.com wrote:
Yaah -- so if it's useful documentation, then I'd be against
creating a rule that bans it. The next question would be whether
it's useful or not Public vs private certainly sounds like
one thing to look at. However, some libraries might want to ship
information about their private interfaces for people who want to
help hack on the library so it's not a 100% thing that I'd want
to enforce with a Guideline
Perhaps in these two specific cases it would be best to open bugs
for the maintainers to look at whether some of the documentation
in here isn't considered useful and could be left out.
I have to agree with Toshio here - it would be a bad move to be
banning sub-packaged docs. In the case of root I can say that the
root docs sub-package is very useful.
Sigh. No one is suggesting banning sub-packaged docs. I find them
quite useful myself. My suggestion was to limit the size of
automatically generated documentation. However, the feedback I'm
getting seems to suggest that a number of people disagree with me. :)
I've taken a look at the root source rpm, and it looks like root-doc
is generated by root itself *after* root has been completely built
(rather than as part of root's build process).
I've opened a bug, https://bugzilla.redhat.com/show_bug.cgi?id=621812
suggesting that the documentation generation be moved even later, into
the %post section of the root-doc install. This means the
documentation will be generated on the user's machine, eliminating
the need for a massive download.
No, please not...
Generating that documentation will take ages, so each time, %post needs
at least 45 min - 1 hour to complete...
(One of my reasons for switching to Fedora from Gentoo, was exactly
that amount of updating time. ;-) )
How about writing a little shell script and include that in the doc
subpackage, so if a user wants to see documentation, they can run the
snipped and wait for the run, as they wish?
Currently, when building root, it's done the same:
# Generate documentation
echo Rint.Includes: 0 .rootrc
sed s...@pwd@!${PWD}!g %{SOURCE2} html.C
LD_LIBRARY_PATH=${PWD}/lib:${PWD}/cint/cint/include:${PWD}/cint/cint/stl
\ ROOTSYS=${PWD} ./bin/root.exe -l -b -q html.C
rm .rootrc
mv htmldoc ${RPM_BUILD_ROOT}%{_defaultdocdir}/%{name}-%{version}/html
Maybe putting that (except the mv in the end) in a snipped, would give
the user htmldoc in the current folder, where the user called it...
Thomas
--
devel mailing list
devel@lists.fedoraproject.org
https://admin.fedoraproject.org/mailman/listinfo/devel
Re: root-doc subpackage slightly obese
On Fri, 2010-08-06 at 10:46 +0200, Thomas Spura wrote:
On Fri, 06 Aug 2010 11:03:46 +0300
Jonathan Dieter wrote:
On Fri, 2010-08-06 at 06:27 +0100, Jonathan Underwood wrote:
On 5 August 2010 21:49, Toshio Kuratomi a.bad...@gmail.com wrote:
Yaah -- so if it's useful documentation, then I'd be against
creating a rule that bans it. The next question would be whether
it's useful or not Public vs private certainly sounds like
one thing to look at. However, some libraries might want to ship
information about their private interfaces for people who want to
help hack on the library so it's not a 100% thing that I'd want
to enforce with a Guideline
Perhaps in these two specific cases it would be best to open bugs
for the maintainers to look at whether some of the documentation
in here isn't considered useful and could be left out.
I have to agree with Toshio here - it would be a bad move to be
banning sub-packaged docs. In the case of root I can say that the
root docs sub-package is very useful.
Sigh. No one is suggesting banning sub-packaged docs. I find them
quite useful myself. My suggestion was to limit the size of
automatically generated documentation. However, the feedback I'm
getting seems to suggest that a number of people disagree with me. :)
I've taken a look at the root source rpm, and it looks like root-doc
is generated by root itself *after* root has been completely built
(rather than as part of root's build process).
I've opened a bug, https://bugzilla.redhat.com/show_bug.cgi?id=621812
suggesting that the documentation generation be moved even later, into
the %post section of the root-doc install. This means the
documentation will be generated on the user's machine, eliminating
the need for a massive download.
No, please not...
Generating that documentation will take ages, so each time, %post needs
at least 45 min - 1 hour to complete...
(One of my reasons for switching to Fedora from Gentoo, was exactly
that amount of updating time. ;-) )
According to http://root.cern.ch/root/Documentation.html , it will only
regenerate changed or added documentation, so it should only take a long
time on the first install (I haven't done it, so I'm assuming your 45
min - 1 hour is accurate).
How about writing a little shell script and include that in the doc
subpackage, so if a user wants to see documentation, they can run the
snipped and wait for the run, as they wish?
Currently, when building root, it's done the same:
# Generate documentation
echo Rint.Includes: 0 .rootrc
sed s...@pwd@!${PWD}!g %{SOURCE2} html.C
LD_LIBRARY_PATH=${PWD}/lib:${PWD}/cint/cint/include:${PWD}/cint/cint/stl
\ ROOTSYS=${PWD} ./bin/root.exe -l -b -q html.C
rm .rootrc
mv htmldoc ${RPM_BUILD_ROOT}%{_defaultdocdir}/%{name}-%{version}/html
Maybe putting that (except the mv in the end) in a snipped, would give
the user htmldoc in the current folder, where the user called it...
Sounds great. Honestly, I don't really mind which way it works.
Jonathan
signature.asc
Description: This is a digitally signed message part
--
devel mailing list
devel@lists.fedoraproject.org
https://admin.fedoraproject.org/mailman/listinfo/devel
Re: root-doc subpackage slightly obese
On Fri, 2010-08-06 at 10:04 +0100, Jonathan Underwood wrote: As I said in the bug report, I don't think building docs client side is the right way to go at all. In the general case this would require end users to install extra tools to build the docs, and defeats the purpose of a package managed system such as Fedora. While in the general case, I would agree with you, in this specific case, I think it's worth building on the client. 687MB is a very large download, over 90 minutes on a 1mbit/s link, and 45 minutes on a 2mbit/s link. Because of the large size and number of files, it also takes a non-trivial amount of time to actually install the rpm; on my laptop six minutes. In comparison, generating the html documents after installing root-* (excluding root-doc) took 37 minutes on my laptop. The total install time is the same for someone with someone with a 3mbit/s link, and client-side building is faster for someone with a slower link. At what point would you say it's worth the tradeoff? Jonathan signature.asc Description: This is a digitally signed message part -- devel mailing list devel@lists.fedoraproject.org https://admin.fedoraproject.org/mailman/listinfo/devel
Re: root-doc subpackage slightly obese
On Thu, 2010-08-05 at 14:24 -0400, Toshio Kuratomi wrote: I don't think we could just say don't package documentation that's ridiculously large but perhaps we could make some sort of guideline about not duplicating formats on extra large docs. Is the case with root-docs (and/or kdelibs-apidocs) that we have docs in text + html + tex + pdf + your_format_here? The problem is that, at least for root-doc (not sure about kdelibs-apidocs), it's all html. Please note that I'm not saying don't package documentation that's ridiculously large, but rather, don't package automatically generated documentation that's ridiculously large. Jonathan signature.asc Description: This is a digitally signed message part -- devel mailing list devel@lists.fedoraproject.org https://admin.fedoraproject.org/mailman/listinfo/devel
Re: root-doc subpackage slightly obese
On Thu, 2010-08-05 at 15:19 -0400, Orcan Ogetbil wrote: On Thu, Aug 5, 2010 at 3:11 PM, Jonathan Dieter wrote: Please note that I'm not saying don't package documentation that's ridiculously large, but rather, don't package automatically generated documentation that's ridiculously large. Is it generated by doxygen? In that case, doxy files usually have options to disable building certain portions of the documentation. For example, when building a library package, we don't want the full source documentation. We only want the documentation of the API the library is exposing. I don't know if root-doc or kdelibs-apidocs are generated using doxygen. If so, this sounds like it may be an easy fix. Jonathan signature.asc Description: This is a digitally signed message part -- devel mailing list devel@lists.fedoraproject.org https://admin.fedoraproject.org/mailman/listinfo/devel
Re: root-doc subpackage slightly obese
On Thu, Aug 05, 2010 at 03:19:46PM -0400, Orcan Ogetbil wrote: On Thu, Aug 5, 2010 at 3:11 PM, Jonathan Dieter wrote: On Thu, 2010-08-05 at 14:24 -0400, Toshio Kuratomi wrote: I don't think we could just say don't package documentation that's ridiculously large but perhaps we could make some sort of guideline about not duplicating formats on extra large docs. Is the case with root-docs (and/or kdelibs-apidocs) that we have docs in text + html + tex + pdf + your_format_here? The problem is that, at least for root-doc (not sure about kdelibs-apidocs), it's all html. Please note that I'm not saying don't package documentation that's ridiculously large, but rather, don't package automatically generated documentation that's ridiculously large. Is it generated by doxygen? In that case, doxy files usually have options to disable building certain portions of the documentation. For example, when building a library package, we don't want the full source documentation. We only want the documentation of the API the library is exposing. Yaah -- so if it's useful documentation, then I'd be against creating a rule that bans it. The next question would be whether it's useful or not Public vs private certainly sounds like one thing to look at. However, some libraries might want to ship information about their private interfaces for people who want to help hack on the library so it's not a 100% thing that I'd want to enforce with a Guideline Perhaps in these two specific cases it would be best to open bugs for the maintainers to look at whether some of the documentation in here isn't considered useful and could be left out. -Toshio pgpvCWxQkXeIr.pgp Description: PGP signature -- devel mailing list devel@lists.fedoraproject.org https://admin.fedoraproject.org/mailman/listinfo/devel
Re: root-doc subpackage slightly obese
Toshio Kuratomi wrote: I don't think we could just say don't package documentation that's ridiculously large but perhaps we could make some sort of guideline about not duplicating formats on extra large docs. Is the case with root-docs (and/or kdelibs-apidocs) that we have docs in text + html + tex + pdf + your_format_here? kdelibs-apidocs is only in one format (HTML). However, we may want to add a second format (QCH, which is basically an archive of HTML files) soon because that way we could get Qt Assistant, and with minimal code changes also KDevelop, to display that documentation. (It would be a separate subpackage.) Though shipping only the QCH might also be worth considering. Kevin Kofler -- devel mailing list devel@lists.fedoraproject.org https://admin.fedoraproject.org/mailman/listinfo/devel
Re: root-doc subpackage slightly obese
On Fri, Aug 06, 2010 at 01:45:08AM +0200, Kevin Kofler wrote: Toshio Kuratomi wrote: I don't think we could just say don't package documentation that's ridiculously large but perhaps we could make some sort of guideline about not duplicating formats on extra large docs. Is the case with root-docs (and/or kdelibs-apidocs) that we have docs in text + html + tex + pdf + your_format_here? kdelibs-apidocs is only in one format (HTML). However, we may want to add a second format (QCH, which is basically an archive of HTML files) soon because that way we could get Qt Assistant, and with minimal code changes also KDevelop, to display that documentation. (It would be a separate subpackage.) Though shipping only the QCH might also be worth considering. Depending on the technologies and applications involved I could see duplication being okay when one format is meant for people utilizing less /usr/share/doc/foo/* vs running /usr/bin/documentationviewer or /usr/bin/programmer-ide -Toshio pgp2oLKZvitgq.pgp Description: PGP signature -- devel mailing list devel@lists.fedoraproject.org https://admin.fedoraproject.org/mailman/listinfo/devel
Re: root-doc subpackage slightly obese
On 5 August 2010 21:49, Toshio Kuratomi a.bad...@gmail.com wrote: Yaah -- so if it's useful documentation, then I'd be against creating a rule that bans it. The next question would be whether it's useful or not Public vs private certainly sounds like one thing to look at. However, some libraries might want to ship information about their private interfaces for people who want to help hack on the library so it's not a 100% thing that I'd want to enforce with a Guideline Perhaps in these two specific cases it would be best to open bugs for the maintainers to look at whether some of the documentation in here isn't considered useful and could be left out. I have to agree with Toshio here - it would be a bad move to be banning sub-packaged docs. In the case of root I can say that the root docs sub-package is very useful. The problem here really isn't the documentation sub-package size itself, but rather what it does to the size of filelists.xml.gz. And the size of filelists.xml.gz seems to come up periodically, so I wonder if it's worth asking what can be done about that, if anything. Do documentation files really need to be included in file level dependency generation/resolution? Jonathan -- devel mailing list devel@lists.fedoraproject.org https://admin.fedoraproject.org/mailman/listinfo/devel
