Online Thorn Guide broken

Create issue
Issue #1556 closed
anonymous created an issue

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)

  1. Ian Hinder
    • changed status to open
    • removed comment

    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.

  2. Barry Wardell
    • 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 (#882 as well as the two mentioned and this one), and opening a new ticket to discuss alternatives for providing thorn documentation.

  3. Ian Hinder
    • 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.

  4. Frank Löffler
    • 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)?

  5. Erik Schnetter
    • 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.

  6. Frank Löffler
    • 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?

  7. Erik Schnetter
    • 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.

  8. Barry Wardell
    • 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.

  9. Ian Hinder
    • 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.

  10. Barry Wardell
    • 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.

  11. Frank Löffler
    • 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.

  12. Erik Schnetter
    • 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).

  13. Frank Löffler
    • 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.

  14. Barry Wardell
    • removed comment

    Replying to [comment:11 knarf]:

    The only current immediate failure comes from #1489.

    I didn't think #1489 was an issue. My understanding was that the problem there was that arrangement documentation is not included in the ThornGuide.

  15. Frank Löffler
    • 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.

  16. Barry Wardell
    • 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.

  17. Frank Löffler
    • 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.

  18. Frank Löffler
    • 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.

  19. Barry Wardell
    • 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.

  20. Frank Löffler
    • 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?

  21. Barry Wardell
    • 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.

  22. Barry Wardell
    • 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.

  23. Frank Löffler
    • 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)?

  24. Roland Haas
    • removed comment

    Is there a way to also include arrangement documentation (eg for Carpet and EinsteinExact) in the web-pages?

  25. Roland Haas
    • 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.

  26. Barry Wardell
    • 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.

  27. Log in to comment