[Users] Initial data documentation

[Bruno C. Mundim]

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.