GNOME Bugzilla – Bug 103777
yelp-pregenerate should place generated docs in /var/cache
Last modified: 2004-12-22 21:47:04 UTC
With Yelp 2.1.x, yelp-pregenerate places the hgenerated .html docs in the same directory where the source .xml files are installed. This is quite messy, and clobbers /usr quite easily, as well as having problems with ro /usr filesystems, etc. I wish yelp-pregenerate would generate its stuff into /var/cache/yelp. Yelp could read the html files from there and if missing, xml files from /usr.
This sounds like a good solution. Adding Narayana who wrote the yelp-pregenerate code to the CC-line.
Ok, I have two possible solutions to this: 1) have a --with-cache-dir=... to configure which configures both Yelp and yelp-pregenerate to read/write the cache from a certain directory. 2) have a --with-cache-dir option to the running program that you will have to start both yelp and yelp-pregenerate with. 3) have a environment variable $YELP_CACHE_DIR which points the both there. I think we need at least one way of doing this run-time. Perhaps a combination of all three where env. variable is used if it's found, otherwise start-flag then configure flag and last as it is now. Would that cover it all?
Soon good for me.
Yeah, having the 3 would be excellent.
Could someone explain in more detail the problem with putting it in the same directory as the .xml?
FHS ?
John: It's somewhat cluttering to put files not part of the package system in /usr or if they are part of the package it could go into /usr but then we loose the thing we wanted (whatever that was :) to achive by not installing HTML help.
Also users doesn't have the right to write in /usr
It's not thought to be run by the user but part of the package installation.
generated files shouldn't go in /usr If you use some tools who check system integrity like tripwire, they will return errors. Quotting FHS 5.2 /var/cache is intended for cached data from applications. Such data is locally generated as a result of time-consuming I/O or calculation.
Besides, not everyone has root access to install yelp. I guess this could also help GARNOME-like installs.
We seem to be talking past one another, with different ideas about when yelp-pregenerate is used. Is yelp-pregenerate a) Run by the packager when the package is built? b) Run by the user when the package is installed? c) Run by the user when the app or yelp is actually used?
a) Run by the packager when the package is built? Then we lose the yelp purpose (packaging only xml files and generate page on the fly) in that case yelp can be removed. a html browser can read that pages. b) Run by the user when the package is installed? Yes, but not by the user, by the package installer (dpkg script) and only in /var/cache c) Run by the user when the app or yelp is actually used? Not needed if b) is already done. Anyway yelp isn't intented for that. BTW I see that yelp-pregenerate generate all html files even if these files exist, then this will take a lot of time each time a new package is installed. Another problem arise when a package is removed, generated pages aren't removed in the cache.
> Then we lose the yelp purpose (packaging only xml files and generate > page on the fly) in that case yelp can be removed. a html browser can > read that pages. hmm .. Yelp wouldn't be rendered useless if we shipped the HTML files. It's a bit more than just a HTML view and a db2html script. > b) Run by the user when the package is installed? Yes, by the installation scripts (in post_install I guess). Could also be done as a cron-job, started by root when he's finished with the installation, done by the installation procedure once the installation is finished. I really don't know what people figured when adding this. > c) Run by the user when the app or yelp is actually used? No, since the user had to be able to write to where the cache files are put this can't be done. > BTW I see that yelp-pregenerate generate all html files even if > these You can either run yelp-pregenerate on only the files you installed in you packages.
To Christian's comment: > Then we lose the yelp purpose (packaging only xml files and generate > page on the fly) That was not Yelp's purpose. Yelp's purpose was always to be a lightweight help browser without the overhead of a full web browser. You can also read the xml now through gnome2-db2html using Galeon.
So we clearly have the cart before the horse here. Before we decide how to handle caching, the people responsible for adding the pregenerate capability need to explain how they intend to use it. Until we answer that question, we're all just talking past one another. The original impetus for this came from Sun's conclusion that on-the-fly rendering wasn't quick enough, but I'd like to hear from the original designer about what use they intended. Narayana? (As an aside, I'll point out that the KDE folks ran up against this same issue, deciding that on-the-fly rendering wasn't quick enough using essentially the same toolkit. Their solution was a pregeneration very similar to yelp-pregenerate, done at package build time and installed into their docs directory rather than a cache directory.)
yes, this would be much easier but people complained that this was really ugly since then docs wouldn't get updated if we installed a new stylesheet (not sure if this is really a problem).
Sorry for late the response. The implementation was done based on the discussions through the following mail chain: http://mail.gnome.org/archives/gnome-doc-list/2002-June/msg00064.html yelp-pregenerate is just a tool which converts an XML file or list of XML files into HTML files. It can take different options depending on the user requirements. How to use this tool? I don't really know how different distributors package GNOME. So I can not comment much here. Basic design was done based on the following assumptions: - If there is a single package for installing GNOME, have a post-install script which calls yelp-pregenerate to generate HTMLs for all the help XML files installed. And optionally, have a post-remove script, which removes the generated HTML files when the package is removed. - If there is a different package for each product/component, have a post-install script for each package, which calls yelp-pregenerate. And optionally, have a post-remove script also. OR, - Let the system administrator run the yelp-pregenerate manually(or using a script) once all the packages are installed. Where we store them? After the discussion, it was decided that there will be a system-wide cache, with write permissions to root ONLY. Accordingly, the generated HTMLs are being stored in the same dir where the corresponding XML files reside. This cache will be generated by post-install scripts or the system administrator manually. If an ordinary user wants to generate HTMLs he needs to request the administrator. (Per-user cache was ruled out as it takes lot of system resources to have generated htmls for each user. And every user can not be given write access to the system wide cache) How yelp uses generated HTML files: - When user launches help, gnome-help will try to load the generated HTML file after making sure that the HTML file is newer than the XML file. Else, it will load the XML itself, which needs conversion to HTML later at run-time, which takes time. - Also when there is a new style-sheet, the HTML files need to be re-generated. This will be taken care of by the administrator. - When the user finds that help loading still takes time because of old HTML files, he/she needs to request the administrator to re-generate the HTMLs required. Hope this will answer most of the questions. Sorry for the late response once again.
Narayana - Is this used in any packages yet? I'd like to see how the installation is done.
Hmm... I am not very sure who are all using yelp-pregenerate. I have checked it on RedHat8.0 with gnome-2.0. When I launch yelp, it is not taking pre-generated help files. Instead, XML to HTML conversion is happening at run time. In SUN builds, I have observed that they are shipping both XML and HTML pages with each package, which has help files.
What's the status of this bug? Any improvement for Yelp 2.4?
Pregeneration is gone on 2.5, so this isn't really applicable anymore. With the speed improvements, pregenerating the HTML really isn't necessary.