- changed status to open
- removed comment
Online Thorn Guide broken
Issue #1556
closed
Browsing the online documentation for the various thorns it turns out that the index at http://einsteintoolkit.org/documentation/ThornGuide/ThornGuide.html is broken for "Part F CactusElliptic" which points instead to "Part F CactusIO" and similarly for everything that follows. This makes the web page pretty much unusable ..
Keyword: broken
Keyword: index
Comments (31)
-
-
- removed comment
This problem was already reported in
#1511. It was suggested that the ThornGuide be removed in#1489, but I don't think anything has been done since then. I propose doing so, closing all four ThornGuide tickets (#882as well as the two mentioned and this one), and opening a new ticket to discuss alternatives for providing thorn documentation. -
- removed comment
If we do that, then we don't have any thorn documentation available on the ET web page, which is bad. I don't think we should remove the thorn guide until we have a replacement. I think all that is needed is a page which indexes the thorndoc. This should be created as part of the ThornDoc make target.
-
- removed comment
I don't think we came to the conclusion that the Thornguide should go. There is some good reasoning to having one document for all thorns, e.g., it makes it pretty easy to search for something. Shouldn't we be able to fix what is currently broken (apparently EinsteinExact)?
-
- removed comment
The problem is that adding/removing a thorn changes the chapter and section numbers of all subsequent thorns. Also, latex errors in one thorn make the whole document unavailable.
This is the main difference between ThornDoc and ThornGuide: ThornDoc builds all thorns independently, so that there are no confusing section numbers (have you ever tried to track down an error reported in "section E.4" if that section points to a different thorn every six months, or in the release and the development version?), and latex errors in one thorn don't affect unrelated thorns. I suggest to remove the ThornGuide and use the ThornDoc instead.
-
- removed comment
Errors should be fixed. If one thorn doesn't build (the main source), the executable will also not be built, and the thorn is then fixed. We should have the same standard for the documentation.
As for the section numbers - yes, that is a problem. Do you have a suggestion how to label/number thorns in a document containing multiple thorns, that doesn't show this problem?
-
- removed comment
We just do not use section numbers. Think Unix directory -- the files are not numbered, they just have names. In our documentation, the sections should similarly be labelled by arrangement and thorn; adding integer numbers is not necessary.
Documentation is slightly different from source code. When building a configuration, we explicitly choose which thorns to include (thorn list), and ignore all others. These other thorns thus may contain code that doesn't compile, and this is fine.
With documentation, we want to have as much documentation available as possible. Requiring a thorn list to build documentation is a bad idea, because it prevents people from building documentation for many thorns that are just fine. Also, while thorns' source code often depend on each other (inheritance etc.), this is not the case for documentation; thorn documentation can be built independently for each thorn. - Preventing all documentation from being built because a user has a single (maybe even unused) thorn with a latex error doesn't make sense. This is different from an executable. - Building documentation only for a specific set of thorns is too limiting; this prevents people e.g. from looking at thorn PETSc until they add it to their thorn list. This is not necessary.
-
- removed comment
Replying to [comment:3 hinder]:
If we do that, then we don't have any thorn documentation available on the ET web page, which is bad. I don't think we should remove the thorn guide until we have a replacement. I think all that is needed is a page which indexes the thorndoc. This should be created as part of the ThornDoc make target.
If we do that, then we end up with the same situation as we are currently in: wrongly indexed documentation on the ET webpage. My understanding was that the ThornGuide was a dead end (correct me if I'm wrong) so I was suggesting removing the ThornGuide make target and focusing on a better solution such as creating an index of the ThornDoc. In fact, even just replacing the HTML ThornGuide with ThornDoc and relying on the web server to produce an index would be an improvement. For example, see http://www.barrywardell.net/files/ThornDoc/ which just uses "DirectoryIndex documentation.html index.html index.php" in the .htaccess file and the following trivial php script in the base directory:
<?php $thorns = glob("*/*"); foreach($thorns as $thorn) { echo "<a href=$thorn>$thorn</a><br />"; } ?>This could obviously be made prettier with some basic CSS and improvements to the PHP script.
-
- removed comment
Wrongly-indexed documentation is better than none at all :) For now, I like your PHP script. Shall we add it to the web page? Once it has the ET stylesheet applied, it should be good enough I think.
-
- removed comment
Replying to [comment:9 hinder]:
Wrongly-indexed documentation is better than none at all :)
I agree. I wasn't suggesting removing the actual HTML files from the website, just removing the ThornGuide make target.
For now, I like your PHP script. Shall we add it to the web page? Once it has the ET stylesheet applied, it should be good enough I think.
I think that would be a good idea. Attached is a slightly improved version which also include arrangement documentation links and some basic HTML structue.
-
- removed comment
There are clearly different ways people use the documentation. There is HTML and pdf - both are used by different people. There is one file/page vs. hundreds. Also here different people prefer different ways. I mentioned that I think it is important to be able to search in just one document containing all thorns. I don't see how a directory page linking the different ThornDocs would help here. Also, this only applies to the HTML version.
Concerning the thornguide being configuration-specific: this is the default right now, and it has the advantage that you don't need to have a "clean" arrangements structure to get the thornguide for a specific thornlist - say the Einstein Toolkit. It also has the advantage that you typically only build documentation for thorns you actually care about, so errors in other thorns don't affect you. The only current immediate failure comes from
#1489.There could be a 'make thornguide' too, simply creating a temporary thornlist from all thorns.
-
- removed comment
Just to drive home my point: Please get rid of section numbers. They are confusing and they don't make sense.
"make ThornDoc" works just fine. This does not require a "clean" arrangements structure either. It just works, giving you documentation for all the thorns that you have (and which don't contain latex errors).
-
- removed comment
'make ThornDoc' gives you a gazillion pdf/html files. It's just not the same as the ThornGuide. It is nice that it works, but it doesn't produce one document at the end.
Getting rid of sections numbers does not seem to be a 5 minute change. Cactus assumes the thorn documentation can be compiled on it's own, using 'section' as highest structure. It then uses chapter for sorting them into arrangements and something Cactus specific (cactuspart) for the overall numbering. Getting the 'chapter' part not to show a numbering is a two-line change. Changing the 'cactuspart' structure would be a bit more involved - not terribly difficult, but also not a 'I do this while I have my coffee' issue.
-
- removed comment
-
- removed comment
It is part of the ThornGuide, and currently breaks it. Just tried. It includes a file which of course doesn't work if built outside of that directory. Either we don't allow that, or scan and copy files (and deal with identical file names somehow), or think of something else.
-
- removed comment
Barry and I have regenerated the ThornDoc to be current, and added a PHP index. You can see the results at http://einsteintoolkit.org/documentation/ThornDoc/. I suggest that the current link to the ThornGuide on the main page be replaced with a link to this.
-
- removed comment
This does not include all the information about a thorn you have in the ThornGuide. Compare
http://einsteintoolkit.org/documentation/ThornDoc/AEIThorns/ADMMass/documentation.html
to
http://einsteintoolkit.org/documentation/ThornGuide/ThornGuidech1.html#x3-2000A1
for exmaple.
-
- removed comment
Replying to [comment:17 knarf]:
This does not include all the information about a thorn you have in the ThornGuide. Compare
http://einsteintoolkit.org/documentation/ThornDoc/AEIThorns/ADMMass/documentation.html
to
http://einsteintoolkit.org/documentation/ThornGuide/ThornGuidech1.html#x3-2000A1
for exmaple.
I have update the ThornDoc build process to include this information. This requires the attached patches for the flesh. If they are acceptable, can someone with commit access please commit them?
Are there any other features still missing from the ThornDoc?
The only missing thing I'm aware of is a search feature. One straightforward option for this would be to use a Google Custom Search Engine. I have put an example of how this would work at http://www.barrywardell.net/files/ThornDoc/. One possible downside to this is that they may include ads in the search results. There is an ad-free version available which is free for registered non-profit organisations.
-
- removed comment
Replying to [comment:18 barry.wardell]:
I have update the ThornDoc build process to include this information. This requires the attached patches for the flesh. If they are acceptable, can someone with commit access please commit them?
Thanks for the patches. They look good, apart from some indentation problems (which in part come from tabs being present in the original file). I will test and commit them.
Are there any other features still missing from the ThornDoc?
The only missing thing I'm aware of is a search feature. One straightforward option for this would be to use a Google Custom Search Engine. I have put an example of how this would work at http://www.barrywardell.net/files/ThornDoc/. One possible downside to this is that they may include ads in the search results. There is an ad-free version available which is free for registered non-profit organisations.
If someone would fix EinsteinExact, and with that the ThornGuide, then we would have something that is automatically searchable, without any special tool, fees, applications or ads, online and offline.
Alternatively, we could use the html output from the ThornGuide, and generate one page, with the current TOC being at the top, using internal links. This would be trivially searchable. We could even provide both versions, of some system couldn't handle a page that long.
-
- removed comment
From patch 0002, file lib/sbin/ThornDoc I had to take out the line
sed -e 's+\\usepackage{../../../../doc/latex/cactus}+\\usepackage{../../../../../doc/latex/cactus}+g' |How was this working for you? Would it work without this replacement? It does for me, but I am now hesitant to commit.
-
- removed comment
I made this change because it also existed in the ThornDocHTML file, and was able to generate the ThornDoc files with it included. But now I realise that it should probably not be there. It was only necessary for the HTML version as the directory structure is nested one level deeper in that case.
-
- removed comment
Replying to [comment:21 barry.wardell]:
and was able to generate the ThornDoc files with it included.
Ok, so with the present patch as in trac, the ThornDoc also fails for you, while the ThornDocHTML succeeds?
-
- removed comment
Replying to [comment:22 knarf]:
Replying to [comment:21 barry.wardell]:
and was able to generate the ThornDoc files with it included.
Ok, so with the present patch as in trac, the ThornDoc also fails for you, while the ThornDocHTML succeeds?
In fact, it appears that both work for me but I think that is an artefact of how my Cactus tree is laid out (with certain symlinks). I think the patch is correct for a standard Cactus tree with the line you mentioned removed.
-
- removed comment
Replying to [comment:19 knarf]:
Alternatively, we could use the html output from the ThornGuide, and generate one page, with the current TOC being at the top, using internal links. This would be trivially searchable. We could even provide both versions, of some system couldn't handle a page that long.
I have made it so the documentation at http://einsteintoolkit.org/documentation/ThornDoc/ is also browsable as a single HTML page.
-
- removed comment
Patches are committed. Thanks for the single page - this should make searches trivial. It also means that the current ThornDoc on the web page is better than the ThornGuide. Can you please remove the link to the ThornGuide (and possibly also the ThornGuide itself, as it was shown to be wrong anyway)?
-
- removed comment
Is there a way to also include arrangement documentation (eg for Carpet and EinsteinExact) in the web-pages?
-
- removed comment
The arrangement documentation is listed at the top of the page.
-
- removed comment
Ah I see. Thank you. I had not checked the top of the list but only around "Carpet" and "EinsteinExact". Is there any possibility of making the arrangement labels links to the arrangement docs if they exist (this is where I looked)? The single page document does not include arrangement docs it seems.
-
- removed comment
Replying to [comment:25 knarf]:
Can you please remove the link to the ThornGuide (and possibly also the ThornGuide itself, as it was shown to be wrong anyway)?
Done.
Replying to [comment:28 rhaas]:
Ah I see. Thank you. I had not checked the top of the list but only around "Carpet" and "EinsteinExact". Is there any possibility of making the arrangement labels links to the arrangement docs if they exist (this is where I looked)? The single page document does not include arrangement docs it seems.
Both of these are now fixed.
-
- changed status to resolved
- removed comment
Thanks!
-
- edited description
- changed status to closed
- Log in to comment
- Assignee
- –
- Type
- Priority
- Status
- closed
- Component
- EinsteinToolkit website
- Milestone
- –
- Version
- –
- Votes
- 0
- Watchers
- 0
Unfortunately the documentation is in LaTeX, so we have to use a LaTeX to HTML conversion tool (tex4ht), and the results are not great. This online documentation should also either be automatically generated, or at the very least regenerated for each release, but I don't think this has been done for a few releases. I think we have talked about deprecating the "Thornguide" documentation target in favour of the "ThornDoc". There is a version of the ThornDoc at http://einsteintoolkit.org/documentation/ThornDoc/ (similarly slightly out of date I expect). All it lacks is an index.