[Users] Initial data documentation

[Barry Wardell]

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