[Einstein Toolkit] #1038: remove compiled documentation from Cactus repository

List overview All Threads
Download

newer

older

[Einstein Toolkit] #1056: do not...

[Einstein Toolkit] #1055: Don't...

Einstein Toolkit

11 Aug 2012 11 Aug '12

4:39 p.m.

#1038: remove compiled documentation from Cactus repository ---------------------------+------------------------------------------------ Reporter: rhaas | Owner: Type: enhancement | Status: new Priority: optional | Milestone: Component: Cactus | Version: Keywords: documentation | ---------------------------+------------------------------------------------ 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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1038 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Show replies by date

Einstein Toolkit

12 Aug 12 Aug

3:36 a.m.

#1038: remove compiled documentation from Cactus repository --------------------------+------------------------------------------------- Reporter: rhaas | Owner: Type: enhancement | Status: new Priority: optional | Milestone: Component: Cactus | Version: Resolution: | Keywords: documentation --------------------------+-------------------------------------------------

Comment (by hinder):

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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1038#comment:1 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

9:22 a.m.

Comment (by eschnett):

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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1038#comment:2 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

12:26 p.m.

Comment (by hinder):

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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1038#comment:3 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

13 Aug 13 Aug

9:16 a.m.

Comment (by knarf):

One incentive might have been that you can always look at, e.g., http://svn.cactuscode.org/flesh/trunk/doc/UsersGuide.pdf to see the current state of the documentation, using a web browser and without downloading anything else.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1038#comment:4 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

9:21 a.m.

Comment (by bmundim):

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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1038#comment:5 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

9:41 a.m.

Comment (by eschnett):

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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1038#comment:6 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

10:14 a.m.

Comment (by hinder):

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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1038#comment:7 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

10:30 a.m.

Comment (by eschnett):

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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1038#comment:8 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

10:54 a.m.

Comment (by rhaas):

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).

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1038#comment:9 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

11:37 a.m.

Comment (by eschnett):

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).

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1038#comment:10 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

12:03 p.m.

Comment (by rhaas):

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"?

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1038#comment:11 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

20 Aug 20 Aug

10:15 a.m.

Comment (by eschnett):

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

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1038#comment:12 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

22 Aug 22 Aug

12:28 p.m.

#1038: remove compiled documentation from Cactus repository --------------------------+------------------------------------------------- Reporter: rhaas | Owner: Type: enhancement | Status: closed Priority: optional | Milestone: Component: Cactus | Version: Resolution: wontfix | Keywords: documentation --------------------------+------------------------------------------------- Changes (by rhaas):

* status: new => closed * resolution: => wontfix

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1038#comment:13 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

5161

Age (days ago)

5172

Last active (days ago)

trac@lists.einsteintoolkit.org

13 comments

1 participants

tags (0)

participants (1)

Einstein Toolkit