As discussed in our telecon this morning, I wrote a wiki page about setting up an initial data thorn for <http:// docs.einsteintoolkit.org>. The last section (setting up and running with an example parameter file) is still missing.
I would be happy if someone took the liberty to proofread, correct, simplify, and possibly complete my explanations.
-erik
On 19 Apr 2010, at 22:06, Erik Schnetter wrote:
As discussed in our telecon this morning, I wrote a wiki page about setting up an initial data thorn for http:// docs.einsteintoolkit.org.
As requested, I have also written a very brief introduction to the ADMBase and SphericalSurfaces "toolkit standards". I would like to link to the thorn documentation so that people can read it on the web. ADMBase, as part of Cactus, has its documentation linked as a PDF from http://cactuscode.org/documentation/thorns/. I don't know how up-to-date this documentation is. SphericalSurface has no documentation link there, as it is not part of Cactus.
Maybe the Einstein Toolkit should host web-based documentation for all the thorns in it?
On 20/04/2010 12:07, Ian Hinder wrote:
Maybe the Einstein Toolkit should host web-based documentation for all the thorns in it?
I think it would be really useful to have web-based HTML documentation for everything in the Einstein Toolkit. This should be fairly straightforward to create from the LaTeX source. There is a useful package called tex4ht which does a pretty good job of converting LaTeX to HTML. As an example of how well it can do, I ran it with the CactusWave documentation and got quite good output: http://www.aei.mpg.de/~barry/documentation.html
On Apr 20, 2010, at 7:44 , Barry Wardell wrote:
On 20/04/2010 12:07, Ian Hinder wrote:
Maybe the Einstein Toolkit should host web-based documentation for all the thorns in it?
I think it would be really useful to have web-based HTML documentation for everything in the Einstein Toolkit. This should be fairly straightforward to create from the LaTeX source. There is a useful package called tex4ht which does a pretty good job of converting LaTeX to HTML. As an example of how well it can do, I ran it with the CactusWave documentation and got quite good output: http://www.aei.mpg.de/~barry/documentation.html
This is by far the best latex-to-html conversion I've ever seen. Before that, I would have said that pdf is the way to go, because it is impossible to create readable html except for plain text.
Barry, do you want to modify the script in Cactus which builds the individual thorn guides? (Look for the ThornDoc and ArrangementDoc make targets; these eventually lead to independent shell scripts in lib/sbin that process one thorn or arrangement at a time.) You would look whether tex4ht is installed, and if so, would produce html in addition to pdf. (These scripts are written in bash; perl would have been a better choice.)
We will then incorporate this into Cactus, either as separate make target or together with building the pdf documentation.
-erik
On 20/04/2010 19:15, Erik Schnetter wrote:
Barry, do you want to modify the script in Cactus which builds the individual thorn guides? (Look for the ThornDoc and ArrangementDoc make targets; these eventually lead to independent shell scripts in lib/sbin that process one thorn or arrangement at a time.) You would look whether tex4ht is installed, and if so, would produce html in addition to pdf. (These scripts are written in bash; perl would have been a better choice.)
We will then incorporate this into Cactus, either as separate make target or together with building the pdf documentation.
Hi Erik,
Attached is a patch for the Cactus makefiles which enables building of HTML versions of all documentation. It makes use of the two attached scripts, ThornDocHTML and ArrangmentsDocHTML, which should be in lib/sbin.
The HTML generation uses latex (not pdflatex), so figures must be in ps format. I have added automatic conversion using pdf2ps in ThornDocHTML and ArrangementDocHTML. This could also be added to the make targets if desired. For now, when building the Reference Manual, Users Guide and Maintainers Guide, you need to manually convert cactusbin2.pdf and whatever other pdf's there are to ps.
The new make targets added are: ReferenceManualHTML UsersGuideHTML MaintGuideHTML ThornDocHTML <config>-ThornDocHTML ArrangementDocHTML <arrangement>-ArrangementDocHTML <thorn>-ThornGuideHTML ThornGuideHTML
Everything seems to work quite well except for the Reference Guide, which has formatting problems that seem to be related to the use of FunctionDescriptionEntry in cactus.sty. I also wasn't able to test the ThornDocHTML since even regular ThornDoc wasn't working for me.
Regards, Barry
On Apr 22, 2010, at 8:34 , Barry Wardell wrote:
On 20/04/2010 19:15, Erik Schnetter wrote:
Barry, do you want to modify the script in Cactus which builds the individual thorn guides? (Look for the ThornDoc and ArrangementDoc make targets; these eventually lead to independent shell scripts in lib/sbin that process one thorn or arrangement at a time.) You would look whether tex4ht is installed, and if so, would produce html in addition to pdf. (These scripts are written in bash; perl would have been a better choice.)
We will then incorporate this into Cactus, either as separate make target or together with building the pdf documentation.
Hi Erik,
Attached is a patch for the Cactus makefiles which enables building of HTML versions of all documentation. It makes use of the two attached scripts, ThornDocHTML and ArrangmentsDocHTML, which should be in lib/sbin.
The HTML generation uses latex (not pdflatex), so figures must be in ps format. I have added automatic conversion using pdf2ps in ThornDocHTML and ArrangementDocHTML. This could also be added to the make targets if desired. For now, when building the Reference Manual, Users Guide and Maintainers Guide, you need to manually convert cactusbin2.pdf and whatever other pdf's there are to ps.
The new make targets added are: ReferenceManualHTML UsersGuideHTML MaintGuideHTML ThornDocHTML <config>-ThornDocHTML ArrangementDocHTML <arrangement>-ArrangementDocHTML <thorn>-ThornGuideHTML ThornGuideHTML
Everything seems to work quite well except for the Reference Guide, which has formatting problems that seem to be related to the use of FunctionDescriptionEntry in cactus.sty. I also wasn't able to test the ThornDocHTML since even regular ThornDoc wasn't working for me.
Barry
Thanks for the scripts.
This is bad; ThornDoc is probably the best way to get the thorns' documentation. What is the problem you are encountering? Did you try <thorn>-ThornDoc?
-erik
Do we need different targets for PDF and HTML? How about just generating all forms of documentation with the regular target?
On Apr 29, 2010, at 5:44 PM, Erik Schnetter wrote:
On Apr 22, 2010, at 8:34 , Barry Wardell wrote:
On 20/04/2010 19:15, Erik Schnetter wrote:
Barry, do you want to modify the script in Cactus which builds the individual thorn guides? (Look for the ThornDoc and ArrangementDoc make targets; these eventually lead to independent shell scripts in lib/sbin that process one thorn or arrangement at a time.) You would look whether tex4ht is installed, and if so, would produce html in addition to pdf. (These scripts are written in bash; perl would have been a better choice.)
We will then incorporate this into Cactus, either as separate make target or together with building the pdf documentation.
Hi Erik,
Attached is a patch for the Cactus makefiles which enables building of HTML versions of all documentation. It makes use of the two attached scripts, ThornDocHTML and ArrangmentsDocHTML, which should be in lib/sbin.
The HTML generation uses latex (not pdflatex), so figures must be in ps format. I have added automatic conversion using pdf2ps in ThornDocHTML and ArrangementDocHTML. This could also be added to the make targets if desired. For now, when building the Reference Manual, Users Guide and Maintainers Guide, you need to manually convert cactusbin2.pdf and whatever other pdf's there are to ps.
The new make targets added are: ReferenceManualHTML UsersGuideHTML MaintGuideHTML ThornDocHTML <config>-ThornDocHTML ArrangementDocHTML <arrangement>-ArrangementDocHTML <thorn>-ThornGuideHTML ThornGuideHTML
Everything seems to work quite well except for the Reference Guide, which has formatting problems that seem to be related to the use of FunctionDescriptionEntry in cactus.sty. I also wasn't able to test the ThornDocHTML since even regular ThornDoc wasn't working for me.
Barry
Thanks for the scripts.
This is bad; ThornDoc is probably the best way to get the thorns' documentation. What is the problem you are encountering? Did you try <thorn>-ThornDoc?
-erik
-- Erik Schnetter schnetter@cct.lsu.edu http://www.cct.lsu.edu/~eschnett/
Users mailing list Users@einsteintoolkit.org http://lists.einsteintoolkit.org/mailman/listinfo/users
On Fri, Apr 30, 2010 at 07:20:26AM -0400, Allen Gabrielle wrote:
Do we need different targets for PDF and HTML? How about just generating all forms of documentation with the regular target?
I think we should have different targets (although there could be one target building both), because htlatex is not generally installed.
Frank
On 30 Apr 2010, at 20:37, Frank Loeffler wrote:
On Fri, Apr 30, 2010 at 07:20:26AM -0400, Allen Gabrielle wrote:
Do we need different targets for PDF and HTML? How about just generating all forms of documentation with the regular target?
I think we should have different targets (although there could be one target building both), because htlatex is not generally installed.
I agree that we should have different targets.
On 30/04/2010 20:53, Ian Hinder wrote:
On 30 Apr 2010, at 20:37, Frank Loeffler wrote:
On Fri, Apr 30, 2010 at 07:20:26AM -0400, Allen Gabrielle wrote:
Do we need different targets for PDF and HTML? How about just generating all forms of documentation with the regular target?
I think we should have different targets (although there could be one target building both), because htlatex is not generally installed.
I agree that we should have different targets.
I also agree. The main reason I created separate targets is that the HTML generation takes significantly longer than PDF generation. This is because it needs to first create a dvi file from the tex and then it needs to create PNGs for anything that can't be reliably represented with plain HTML. You don't want to wait for it to generate HTML if all you want is a PDF.
On 29/04/2010 23:44, Erik Schnetter wrote:
Barry
Thanks for the scripts.
This is bad; ThornDoc is probably the best way to get the thorns' documentation. What is the problem you are encountering? Did you try <thorn>-ThornDoc?
I had a look at this again in more detail and it turned out that there were just a couple of thorns in my arrangements (not from Einstein Toolkit) which had documentation that my version of LaTeX was not able to compile. I removed them and now it works for me.
On Apr 22, 2010, at 8:34 , Barry Wardell wrote:
On 20/04/2010 19:15, Erik Schnetter wrote:
Barry, do you want to modify the script in Cactus which builds the individual thorn guides? (Look for the ThornDoc and ArrangementDoc make targets; these eventually lead to independent shell scripts in lib/sbin that process one thorn or arrangement at a time.) You would look whether tex4ht is installed, and if so, would produce html in addition to pdf. (These scripts are written in bash; perl would have been a better choice.)
We will then incorporate this into Cactus, either as separate make target or together with building the pdf documentation.
Hi Erik,
Attached is a patch for the Cactus makefiles which enables building of HTML versions of all documentation. It makes use of the two attached scripts, ThornDocHTML and ArrangmentsDocHTML, which should be in lib/sbin.
The HTML generation uses latex (not pdflatex), so figures must be in ps format. I have added automatic conversion using pdf2ps in ThornDocHTML and ArrangementDocHTML. This could also be added to the make targets if desired. For now, when building the Reference Manual, Users Guide and Maintainers Guide, you need to manually convert cactusbin2.pdf and whatever other pdf's there are to ps.
The new make targets added are: ReferenceManualHTML UsersGuideHTML MaintGuideHTML ThornDocHTML <config>-ThornDocHTML ArrangementDocHTML <arrangement>-ArrangementDocHTML <thorn>-ThornGuideHTML ThornGuideHTML
Everything seems to work quite well except for the Reference Guide, which has formatting problems that seem to be related to the use of FunctionDescriptionEntry in cactus.sty. I also wasn't able to test the ThornDocHTML since even regular ThornDoc wasn't working for me.
I didn't have time to look at these patches in the past days, and probably won't have time in the next few days. Is there anybody else who would want to test them?
-erik
Erik Schnetter wrote:
On Apr 22, 2010, at 8:34 , Barry Wardell wrote:
On 20/04/2010 19:15, Erik Schnetter wrote:
Barry, do you want to modify the script in Cactus which builds the individual thorn guides? (Look for the ThornDoc and ArrangementDoc make targets; these eventually lead to independent shell scripts in lib/sbin that process one thorn or arrangement at a time.) You would look whether tex4ht is installed, and if so, would produce html in addition to pdf. (These scripts are written in bash; perl would have been a better choice.)
We will then incorporate this into Cactus, either as separate make target or together with building the pdf documentation.
Hi Erik,
Attached is a patch for the Cactus makefiles which enables building of HTML versions of all documentation. It makes use of the two attached scripts, ThornDocHTML and ArrangmentsDocHTML, which should be in lib/sbin.
The HTML generation uses latex (not pdflatex), so figures must be in ps format. I have added automatic conversion using pdf2ps in ThornDocHTML and ArrangementDocHTML. This could also be added to the make targets if desired. For now, when building the Reference Manual, Users Guide and Maintainers Guide, you need to manually convert cactusbin2.pdf and whatever other pdf's there are to ps.
The new make targets added are: ReferenceManualHTML UsersGuideHTML MaintGuideHTML ThornDocHTML <config>-ThornDocHTML ArrangementDocHTML <arrangement>-ArrangementDocHTML <thorn>-ThornGuideHTML ThornGuideHTML
Everything seems to work quite well except for the Reference Guide, which has formatting problems that seem to be related to the use of FunctionDescriptionEntry in cactus.sty. I also wasn't able to test the ThornDocHTML since even regular ThornDoc wasn't working for me.
I didn't have time to look at these patches in the past days, and probably won't have time in the next few days. Is there anybody else who would want to test them?
-erik
I am not sure these patches were applied yet, but the current make target at ET didn't work for me. The ArrangementDocHTML produces:
%make ArrangementDocHTML ________________________________________________________________________ Creating arrangement documentation (HTML)... htlatex is /usr/bin/htlatex Created arrangement documentation (HTML) in doc/HTML/ArrangementDoc directory. Done.
but nothing was actually created there:
%ls doc/HTML/ArrangementDoc ls: cannot access doc/HTML/ArrangementDoc: No such file or directory
The ThornDocHTML target seems to work at first sign:
%make ThornDocHTML ________________________________________________________________________
Creating thorn documentation (HTML)...
-P: not found
htlatex is /usr/bin/htlatex
Processing thorn AEIThorns/AEILocalInterp...
Running htlatex...
Processing thorn CactusArchive/ADM...
Running htlatex... ... Processing thorn TAT/TATelliptic... Running htlatex... Created thorn documentation in doc/HTML/ThornDoc directory. Done.
despite the -P option for the shell built-in 'type' not being present in the the Kubuntu distro GNU bash, version 4.0.33. However, the results in /doc/HTML/ThornDoc does not look as nice as in the documentation link provided by Barry:
http://www.aei.mpg.de/~barry/ThornGuide/ThornGuide.html
So Barry: would it be possible for you to commit the scripts you used to build that page? Also are you using any special LaTeX package to make the equations look "right" when translating to html (besides htlatex)?
I would like to have the following broken link fixed:
http://einsteintoolkit.org/documentation/EinsteinToolkitThornGuide.pdf
at
http://einsteintoolkit.org/info/
but would rather use the html version of the documentation, even a temporary one until we figure out a way of doing it automatically. So any help would be appreciated.
Cheers... Bruno.
Hi Bruno,
On 17/06/2010 08:12, Bruno C. Mundim wrote:
I am not sure these patches were applied yet
Frank committed the latest version of this patch with some small changes to the Cactus svn repository on 2010-06-03.
, but the current make target at ET didn't work for me. The ArrangementDocHTML produces:
%make ArrangementDocHTML ________________________________________________________________________ Creating arrangement documentation (HTML)... htlatex is /usr/bin/htlatex Created arrangement documentation (HTML) in doc/HTML/ArrangementDoc directory. Done.
but nothing was actually created there:
%ls doc/HTML/ArrangementDoc ls: cannot access doc/HTML/ArrangementDoc: No such file or directory
This is most likely because there is no arrangement documentation in any of the ET arrangements. Note that the definition of arrangement documentation is different than you might be expecting: it refers to any documentation in the arrangements/<arrangement>/doc directories, not to a combined version of the documentation in arrangements/<arrangement>/*/doc.
The ThornDocHTML target seems to work at first sign:
%make ThornDocHTML ________________________________________________________________________ Creating thorn documentation (HTML)... -P: not found htlatex is /usr/bin/htlatex Processing thorn AEIThorns/AEILocalInterp... Running htlatex... Processing thorn CactusArchive/ADM... Running htlatex... ... Processing thorn TAT/TATelliptic... Running htlatex... Created thorn documentation in doc/HTML/ThornDoc directory. Done.
despite the -P option for the shell built-in 'type' not being present in the the Kubuntu distro GNU bash, version 4.0.33. However, the results in /doc/HTML/ThornDoc does not look as nice as in the documentation link provided by Barry:
http://www.aei.mpg.de/~barry/ThornGuide/ThornGuide.html
So Barry: would it be possible for you to commit the scripts you used to build that page? Also are you using any special LaTeX package to make the equations look "right" when translating to html (besides htlatex)?
The 'type -P ...' command was only for checking that htlatex is installed, so it's not critical to building. Is there a better, more platform independent way to check for the existence of htlatex?
There is a difference between ThornDoc and ThornGuide. The former generates individual documents for each thorn by compiling the arrangements/<arrangement>/<thorn>/doc/documentation.tex file. The latter creates a combined document by combining these files and also by processing the ccl files to provide documentation on the parameters, etc. In my opinion, the ThornGuide is better because it gives more extensive documentation, although there may be cases where ThornDoc is desirable. The link you give is for the ThornGuide. I also put the ThornDoc at:
http://www.aei.mpg.de/~barry/ThornDoc/
Is this still better that the output you are getting? Can you give an example of what's worse with the results in Kubuntu? I just used 'make ThornGuideHTML' and 'make ThornDocHTML' to produce those pages. I'm using MacOS 10.6 and the standard MacTeX latex distribution (TeX Live 2009). htlatex makes use of latex (*not* pdflatex) and tex4ht. The versions I have are:
$ latex --version pdfTeX 3.1415926-1.40.10-2.2 (TeX Live 2009) kpathsea version 5.0.0
$ tex4ht --version ---------------------------- tex4ht.c (2009-01-31-07:33 kpathsea)
I would like to have the following broken link fixed:
http://einsteintoolkit.org/documentation/EinsteinToolkitThornGuide.pdf
at
http://einsteintoolkit.org/info/
but would rather use the html version of the documentation, even a temporary one until we figure out a way of doing it automatically. So any help would be appreciated.
That would be great. If necessary, I can generate the html version and send you a tarball, although it would be nice to fix whatever is causing it not to work well for you.
Regards, Barry
On Jun 17, 2010, at 2:34 , Barry Wardell wrote:
Hi Bruno,
On 17/06/2010 08:12, Bruno C. Mundim wrote:
I am not sure these patches were applied yet
Frank committed the latest version of this patch with some small changes to the Cactus svn repository on 2010-06-03.
, but the current make target at ET didn't work for me. The ArrangementDocHTML produces:
%make ArrangementDocHTML ________________________________________________________________________ Creating arrangement documentation (HTML)... htlatex is /usr/bin/htlatex Created arrangement documentation (HTML) in doc/HTML/ArrangementDoc directory. Done.
but nothing was actually created there:
%ls doc/HTML/ArrangementDoc ls: cannot access doc/HTML/ArrangementDoc: No such file or directory
This is most likely because there is no arrangement documentation in any of the ET arrangements. Note that the definition of arrangement documentation is different than you might be expecting: it refers to any documentation in the arrangements/<arrangement>/doc directories, not to a combined version of the documentation in arrangements/<arrangement>/*/doc.
The current einsteintoolkit.th manifest provides two arrangement documentations, one for Carpet and one for McLachlan.
-erik
Hi,
On Thu, Jun 17, 2010 at 02:12:28AM -0400, Bruno C. Mundim wrote:
despite the -P option for the shell built-in 'type' not being present in the the Kubuntu distro GNU bash, version 4.0.33.
The -P option was introduced in bash in version 2.05b. The culprit is most likely not bash, but the ArrangementDocHTML script itself. It specifies /bin/sh as shell, which might be bash but does not have to be bash. Especially new distros replace /bin/sh with a more lightweight shell, e.g. dash.
Has anyone experience on how much we could rely on /bin/bash being present?
On the other hand, you could run something along the following lines to see if htlatex is installed:
which htlatex 2>/dev/null | grep -q htlatex || echo "htlatex not installed"
Frank
On Jun 17, 2010, at 8:18 , Frank Loeffler wrote:
Hi,
On Thu, Jun 17, 2010 at 02:12:28AM -0400, Bruno C. Mundim wrote:
despite the -P option for the shell built-in 'type' not being present in the the Kubuntu distro GNU bash, version 4.0.33.
The -P option was introduced in bash in version 2.05b. The culprit is most likely not bash, but the ArrangementDocHTML script itself. It specifies /bin/sh as shell, which might be bash but does not have to be bash. Especially new distros replace /bin/sh with a more lightweight shell, e.g. dash.
Has anyone experience on how much we could rely on /bin/bash being present?
I'm using /bin/bash in the ExternalLibraries setup scripts. I haven't had problems on any system. I think we can rely on it being present.
On the other hand, you could run something along the following lines to see if htlatex is installed:
which htlatex 2>/dev/null | grep -q htlatex || echo "htlatex not installed"
-erik
users@lists.einsteintoolkit.org
-
Allen Gabrielle -
Barry Wardell -
Bruno C. Mundim -
Erik Schnetter -
Frank Loeffler -
Ian Hinder