Local documentation is not complete.

[kostyfisik]

I followed the instruction http://www.dealii.org/developer/readme.html#documentation however, the tutorial programs do need that dealii.org is online and you are online too to show everything correct. There are two problems: 1) Images in the tutorial are stored online.

Maybe it is possible to put all images into separate github repo (so it will not pollute the main repo), which should be cloned into examples/images to enable images in tutorial programs (doxygen images are already present)

2) Using MathJax for a local copy. The default behavior is to use *.png images for equations, which is not very convenient: sometimes after zooming in they become even less readable. So I compiled my local copy with MathJax (which is the default for online docs). However, it still needs internet connection (I have no one during the flight and for the first day as a visiting researcher, so this how the issue arised). I was lucky, as soon as most of MathJax scripts were in the browser cache, so it just freezes a little bit after loading the page (as soon as some parts of the MathJax were not in cache, I take a bit before it can recognize a failure). Probably some recent copy of MathJax can be provided with images...

[bangerth]

We did do 1/ a while back, but removed these files because they're big: all images together are 133 MB, and they do not compress well when packaged into a tar file.

For 2/ If you use mathjax, you need the style files which you get through the internet -- in other words, you need to be online.

[tjhei]

1) Images in the tutorial are stored online.

If you run contrib/utilities/makeofflinedoc.sh, it will download all images inside the tutorials. Alternatively, you could of course download the deal.II-offline.doc tarball (see https://github.com/dealii/dealii/releases/tag/v8.4.2 ). They are created using that script.

2) Using MathJax for a local copy.

just define DEAL_II_DOXYGEN_USE_MATHJAX.

[kostyfisik]

If image files are in the indiviudal repo (along with code-gallery, docker-files, release-papers and others in https://github.com/dealii ) size should not be a problem. You can download them only if you need them. However, this will be on obvious task for anyone how needs that. E.g. in some countries internet connection in small hotels can be rather slow (mine was 64kbit/s for St. Etienne, France). I was quite happy with repo I downloaded in advance.

For 2/ I know that it is possible to provide a failover for regular web-pages - if they fail to get scripts from CDN, the provide a local copy. Probably something like this can be integrated into the Doxygen. A six lines example to do this from link

<script src="http://ajax.aspnetcdn.com/ajax/jquery/jquery-2.0.0.min.js"></script>
<script>
if (typeof jQuery == 'undefined') {
    document.write(unescape("%3Cscript src='/js/jquery-2.0.0.min.js' type='text/javascript'%3E%3C/script%3E"));
}
</script>

[tjhei]

Probably something like this can be integrated into the Doxygen.

You can point doxygen to a local mathjax installation using MATHJAX_RELPATH I think. Never tried it though.

[bangerth]

We could do this, but it would be another dependency we have to keep up to date.

We used to do all of these things, but stopped when we realized that 95% of our users are online 90% of the time while they work, and these numbers are not going to fall in the future. I'm not sure I see the point in putting everything offline again.

[jppelteret]

I agree with @bangerth here. Especially given @tjhei's comment outlining an existing mechanism to download the images, I think its hard to justify what could be a lot of extra effort to achieve a marginal increase in coverage/quality of the offline docs. However, I do believe that we could perhaps better document the options for obtaining offline docs, which I see is something that you're now working on. Thanks :-)

[kostyfisik]

I checked contrib script, it works fine, so there is no need in a separate repo to have a full local tuorials copy. I will check the solution with local installation on MathJax and add it to the readme.

[bangerth]

@kostyfisik -- Has this issue been fully addressed by #3255? If so, can it be closed?