[Einstein Toolkit] #1556: Online Thorn Guide broken

List overview All Threads
Download

newer

older

[Einstein Toolkit] #1511: links in...

[Einstein Toolkit] #1522: Improve...

Einstein Toolkit

13 Mar 2014 13 Mar '14

6:55 a.m.

#1556: Online Thorn Guide broken ----------------------------------------+----------------------------------- Reporter: joachim.frieben@… | Owner: Type: defect | Status: new Priority: major | Milestone: Component: EinsteinToolkit website | Version: Keywords: broken index | ----------------------------------------+----------------------------------- 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 ..

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Show replies by date

Einstein Toolkit

13 Mar 13 Mar

7:54 a.m.

#1556: Online Thorn Guide broken -----------------------------------------+---------------------------------- Reporter: joachim.frieben@… | Owner: Type: defect | Status: confirmed Priority: major | Milestone: Component: EinsteinToolkit website | Version: Resolution: | Keywords: broken index -----------------------------------------+---------------------------------- Changes (by hinder):

* status: new => confirmed

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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:1 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

8:32 a.m.

Comment (by barry.wardell):

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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:2 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

8:46 a.m.

Comment (by 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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:3 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

8:55 a.m.

Comment (by knarf):

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)?

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:4 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

9:01 a.m.

Comment (by eschnett):

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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:5 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

9:15 a.m.

Comment (by knarf):

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?

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:6 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

9:35 a.m.

Comment (by eschnett):

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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:7 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

9:42 a.m.

Comment (by barry.wardell):

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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:8 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

9:49 a.m.

Comment (by hinder):

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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:9 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

10:04 a.m.

Comment (by barry.wardell):

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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:10 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

10:10 a.m.

Comment (by knarf):

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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:11 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

10:16 a.m.

Comment (by eschnett):

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).

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:12 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

10:35 a.m.

Comment (by knarf):

'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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:13 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

11:06 a.m.

Comment (by barry.wardell):

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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:14 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

11:09 a.m.

Comment (by knarf):

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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:15 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

1:02 p.m.

Comment (by hinder):

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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:16 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

2:05 p.m.

Comment (by knarf):

This does not include all the information about a thorn you have in the ThornGuide. Compare

http://einsteintoolkit.org/documentation/ThornDoc/AEIThorns/ADMMass/document...

http://einsteintoolkit.org/documentation/ThornGuide/ThornGuidech1.html#x3-20...

for exmaple.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:17 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

14 Mar 14 Mar

9:24 a.m.

Comment (by barry.wardell):

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/document...

...

to

http://einsteintoolkit.org/documentation/ThornGuide/ThornGuidech1.html#x3-20...

...

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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:18 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

9:47 a.m.

Comment (by knarf):

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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:19 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

9:54 a.m.

Comment (by knarf):

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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:20 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

9:57 a.m.

Comment (by barry.wardell):

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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:21 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

9:58 a.m.

Comment (by 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?

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:22 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

10:20 a.m.

Comment (by barry.wardell):

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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:23 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

10:22 a.m.

Comment (by barry.wardell):

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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:24 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

10:31 a.m.

Comment (by knarf):

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)?

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:25 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

10:38 a.m.

Comment (by rhaas):

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

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:26 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

10:43 a.m.

Comment (by hinder):

The arrangement documentation is listed at the top of the page.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:27 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

10:58 a.m.

Comment (by 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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:28 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

1:07 p.m.

Comment (by barry.wardell):

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.

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:29 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

Einstein Toolkit

1:11 p.m.

#1556: Online Thorn Guide broken -----------------------------------------+---------------------------------- Reporter: joachim.frieben@… | Owner: Type: defect | Status: closed Priority: major | Milestone: Component: EinsteinToolkit website | Version: Resolution: fixed | Keywords: broken index -----------------------------------------+---------------------------------- Changes (by knarf):

* status: confirmed => closed * resolution: => fixed

Comment:

Thanks!

-- Ticket URL: https://trac.einsteintoolkit.org/ticket/1556#comment:30 Einstein Toolkit http://einsteintoolkit.org The Einstein Toolkit

4591

Age (days ago)

4592

Last active (days ago)

trac@lists.einsteintoolkit.org

30 comments

1 participants

tags (0)

participants (1)

Einstein Toolkit