thorn guide on et website links to pdf pages

Issue #2022 closed
Roland Haas created an issue

This is a continuation #2010 which was about the thorn guide being missing. This one is about the link behind "Thorn Guide" on http://einsteintoolkit.org/documentation.html, namely http://einsteintoolkit.org/thornguide/ points to an auto-generated index page of a directory of pdf files. Instead of the correct HTML page for a table of content pointing to html pages of documentation.

Likely requires web server access to fix.

Keyword:

Comments (17)

  1. Roland Haas reporter
    • removed comment

    This is actually worse than that. I only see thorns up to what is in CactusWave and nothing beyond that (alphabetically). This really should be fixed soon.

  2. Frank Löffler
    • changed status to resolved
    • removed comment

    This has been fixed. The ThornDoc now links to the thorn html pages.

    For this, the documentation has been regenerated using the current release. The other guides now also point to this new location.

    For reference: the documentation is to be updated/copied 'by hand' to the webserver at the moment. Better solutions exist, but this was the fastest way to have a working documentaiton. I could imagine using a repository for this, but since this is essentially generated files, this isn't ideal.

    I tried generating the documentation on the webserver itself, but the htlatex version available there is too old to handle it.

    The ideal solution would be to have a major upgrade of the server OS (anyway...), and then to generate new documentation on-the-fly if something changes within the release branch of the toolkit - so there would need to be some logic that filters out those changes from those on other branches.

    For now the documentation works and maintenance cost is minimal (re-run HTML generation locally and rsync that over to the webserver), so I'm closing this ticket.

    For reference too, this is the location on the webserver: /var/www/einstein/documentation

  3. Ian Hinder
    • removed comment

    There is a Jenkins job which generates the documentation after any change to the toolkit. See https://build-test.barrywardell.net/job/EinsteinToolkitDoc/. This is for the master branch, but we could also create one for the release. Following a successful build, we can run any hook we like.

    The generated documentation is available in a 13 MB file at https://build-test.barrywardell.net/job/EinsteinToolkitDoc/lastSuccessfulBuild/artifact/doc/HTML.tar.gz. Given that the file is so small, it is probably best to just copy the whole file after every build, rather than having a complicated rsync setup. Jenkins could POST to a URL on the web server once a new set of documentation is available, and the web server could then wget the HTML file and deploy it.

    For reference, the current Jenkins documentation build job takes about 30 minutes to run.

  4. Roland Haas reporter
    • removed comment

    Thank you Frank, Ian, Barry. I am re-opening to have the conversation in life ticket and not a closed one so that it shows up as a changed ticket.

    Using the auto-generated one seems like a good idea. Comments on the current list of thorn guides (http://einsteintoolkit.org/documentation/ThornGuide.php yes its a php link):

    • the are errors in the HTML: the closing </li> tag is missing
    • the layout looks quite strange to me with lots of empty space, see eg the attached screenshot. I don't know if his is "new" or was already the case for the old website (cannot check since I don't have a php enable web-server at hand).

    [[Image(https://trac.einsteintoolkit.org/raw-attachment/ticket/2022/183540.png, 100%)]] [[Image(https://trac.einsteintoolkit.org/raw-attachment/ticket/2022/183544.png, 100%)]]

  5. Roland Haas reporter
    • changed status to open
    • removed comment

    The attached html page does do the proper column wrap, keeping docs for each arrangement together (not with bootstrap which makes this hard).

  6. Frank Löffler
    • removed comment

    Replying to [comment:7 rhaas]:

    Thank you Frank, Ian, Barry. I am re-opening to have the conversation in life ticket and not a closed one so that it shows up as a changed ticket.

    Using the auto-generated one seems like a good idea. Comments on the current list of thorn guides (http://einsteintoolkit.org/documentation/ThornGuide.php yes its a php link):

    • the are errors in the HTML: the closing </li> tag is missing
    • the layout looks quite strange to me with lots of empty space, see eg the attached screenshot. I don't know if his is "new" or was already the case for the old website (cannot check since I don't have a php enable web-server at hand).

    Yes, I am aware of the 'uneven' lists. The only way I could imagine breaking this up it by breaking the lists of individual arrangements - but I don't think this would be better, because then you can easily end up with the arrangement name out-of-screen and to the bottom of a corresponding thorn name. The reason why you didn't see this in the old list was that the old list was just that: one long list. I could easily do that, and in fact had it like that first, but I personally found it better to get more 'value for screen space', and broke the list into arrangements, which then are placed next to each other. This is done sorted alphabetically, but the number of columns dynamically, which is why you might end up with a setup that looks a bit odd depending on the current list of thorns and your browser width. Improvements are welcome, the script is in git.

  7. Roland Haas reporter
    • removed comment

    Replying to [comment:9 knarf]:

    Replying to [comment:7 rhaas]:

    Thank you Frank, Ian, Barry. I am re-opening to have the conversation in life ticket and not a closed one so that it shows up as a changed ticket.

    Using the auto-generated one seems like a good idea. Comments on the current list of thorn guides (http://einsteintoolkit.org/documentation/ThornGuide.php yes its a php link):

    • the are errors in the HTML: the closing </li> tag is missing
    • the layout looks quite strange to me with lots of empty space, see eg the attached screenshot. I don't know if his is "new" or was already the case for the old website (cannot check since I don't have a php enable web-server at hand).

    Yes, I am aware of the 'uneven' lists. The only way I could imagine breaking this up it by breaking the lists of individual arrangements - but I don't think this would be better, because then you can easily end up with the arrangement name out-of-screen and to the bottom of a corresponding thorn name. The reason why you didn't see this in the old list was that the old list was just that: one long list. I could easily do that, and in fact had it like that first, but I personally found it better to get more 'value for screen space', and broke the list into arrangements, which then are placed next to each other. This is done sorted alphabetically, but the number of columns dynamically, which is why you might end up with a setup that looks a bit odd depending on the current list of thorns and your browser width. Improvements are welcome, the script is in git.

    I am providing an improvement in https://trac.einsteintoolkit.org/attachment/ticket/2022/ThornGuide.php.html which is pure css and works fine if one eg drops the file into a local checkout of the ET website git repo. I lets the browser wrap the lines based on giving it a column width as a number of "em"s ie roughly how many characters are in the column.

  8. Frank Löffler
    • removed comment

    The 'uneven' line breaks are fixed now. So are the missing </li>. This leaves the empty space because of different numbers of thorns in arrangements. I don't think there is a good solution to fix this (and keep alphabetical sorting and columns).

  9. Frank Löffler
    • removed comment

    Replying to [comment:10 rhaas]:

    Replying to [comment:9 knarf]: I am providing an improvement in https://trac.einsteintoolkit.org/attachment/ticket/2022/ThornGuide.php.html which is pure css and works fine if one eg drops the file into a local checkout of the ET website git repo. I lets the browser wrap the lines based on giving it a column width as a number of "em"s ie roughly how many characters are in the column.

    That's an interesting solution. It would require you to 'guess' the number of 'ems', but since this is 'ems' it shouldn't be too bad in most cases. The main difference here is the sorting. This sorts up-down first, then left-right. The current version sorts left-right, then up-down. Which is I guess a question of taste.

  10. Roland Haas reporter
    • removed comment

    I would say that having to guess the number of ems is no worse than having to guess the number of columns that will fit eg bootsrap's "large" media setting or its "small" setting. As for sorting, I have no particular preference, what the browser does is what a typesetter would do on a piece of paper when there are multiple columns. So it is more or less what it has do given that the content could be actual prose text and not just a lost unsorted list.

  11. Roland Haas reporter
    • removed comment

    I would still prefer the solution with fewer empty space. Objections? If not I'll apply it on Wednesday.

  12. Log in to comment