remove compiled documentation from Cactus repository

Issue #1038 closed
Roland Haas created an issue

the current Cactus repository contains pdf versions of the Reference and User guides. Are these present to allow users without a working LaTeX installation to view the documentation (of the flesh, thorns tend to not include PDF files anyway)? We could instead point to the online HTML version on the ET website. This would reduce the number of times the tex file and pdf file are out of sync.

Keyword: documentation

Comments (14)

  1. Ian Hinder
    • removed comment

    I agree that these PDF files should be removed. Removing the PDF files from the repository does mean that you can't go back and see an older version of the built documentation, but it is rare to need this, and you can always build it in a checkout of the older version anyway. See also #1039.

    Let's see if someone comes up with a good reason to keep these files in the repository. If not, let's remove them.

  2. Erik Schnetter
    • removed comment

    We added the pdf files to make it easier for people to view the documentation.

    To reduce conflicts, we could add the built pdf files to releases only.

  3. Ian Hinder
    • removed comment

    Why is it easier to view the documentation from a downloaded Cactus tree than from a web browser? When I want to look at the documentation, I always go to the web version. Is this atypical? Maybe a decision like this should involve the users' mailing list.

  4. Bruno Mundim
    • removed comment

    A good argument to keep these pdf files is that you can search the whole document for keywords while you can't in the web version.

  5. Erik Schnetter
    • removed comment

    One does not always have web access while programming. If you are on a plane, or in a foreign country, then often all you got is what you have on your hard disk.

  6. Ian Hinder
    • removed comment

    Frank: That version is not always updated when people modify the source. If we had the docs hosted on the web site automatically updated, people could still always read it from a URL, and additionally it would always be guaranteed to be up to date.

    Bruno: We would generate both the HTML and the PDF, as we currently have on the web site. Searchability is important; we could investigate providing an easy way to search the HTML version, for example by having a custom google search box, or a javascript-based search index (similar to what is available for the simfactory user guide).

    Erik: In that case, you can build the docs using "make UserGuide", which normally takes only a few seconds. It is usually considered bad form to keep derived files in version control unless there is a compelling reason. I don't see this as a compelling reason.

  7. Erik Schnetter
    • removed comment

    When people download the distribution via the main advertised mechanism, readable documentation should be there, directly accessible. We can't expect people to figure how to type "make UsersGuide" to generate a PDF that then tells them how to build the users' guide.

    The case is similar to the configure script (which is auto-generated), or the Kranc-generated output. In all cases the question is how difficult it is for a non-expert to generate the respective output, and if it is too difficult, we provide the output. In the case of documentation, we want it to be really easy for people to read it, and it should be right there.

  8. Roland Haas reporter
    • removed comment

    I agree that having readable documentation is useful, it is not a given that all files are always up to date though (I think). I am not sure if the comparison to configure is a good one, most people have LaTeX installed and it usually works outof the box. Our autoconf scripts require an outdated version of autoconf that is not normally installed (even if autoconf itself was installed which is also no usually the case).

  9. Erik Schnetter
    • removed comment

    LaTeX is not installed by default e.g. on Mac OSX, or maybe on some supercomputers where people may be trying their first steps.

    Also, the question is not whether people can build the documentation, the question is how easy we can make it for people to begin reading the documentation.

    All the arguments above argue that it is too much work for maintainers to ensure to rebuild the documentation after changing it, or handling documentation conflicts. I don't buy either of this; everybody making changes to the documentation will run latex anyway, and svn will then automatically suggest committing the new pdf. Having to handle conflicts in the pdf files is also very rare, and is very easy (same as above, everybody will run latex anyway just to check whether the merged latex sources still work).

  10. Roland Haas reporter
    • removed comment

    Alright. It's certainly true that we should not make the user's live hard just since we (me) are sloppy committing all files. Since this essentially boils down to the maintainers being careful what we do (and actually commit all generated files): any objections to closing this with "wontfix"?

  11. Erik Schnetter
    • removed comment

    In our telecon on 2012-08-20, we decided to keep the generated PDFs in subversion.

  12. Log in to comment