Update readme.html for #3254 (#3255)

* Use cmake to find local MathJax

diff --git a/cmake/setup_cached_variables.cmake b/cmake/setup_cached_variables.cmake
index a0aee028b6bee8237eaa546449cb4f370b5babe2..6ff2fad6ed46e1be593711147c7efef7d940713d 100644 (file)
--- a/cmake/setup_cached_variables.cmake
+++ b/cmake/setup_cached_variables.cmake
@@ -345,6 +345,12 @@ OPTION(DEAL_II_DOXYGEN_USE_MATHJAX
   )
 MARK_AS_ADVANCED(DEAL_II_DOXYGEN_USE_MATHJAX)
 
+OPTION(DEAL_II_DOXYGEN_USE_ONLINE_MATHJAX
+  "If set to ON, doxygen documentation is generated using online (from CDN) mathjax copy"
+  ON
+  )
+MARK_AS_ADVANCED(DEAL_II_DOXYGEN_USE_ONLINE_MATHJAX)
+
 SET(DEAL_II_CPACK_EXTERNAL_LIBS "opt" CACHE STRING
     "A relative path to tree of external libraries that will be installed in bundle package. The path is relative to the /Applications/${DEAL_II_CPACK_BUNDLE_NAME}.app/Contents/Resources directory. It defaults to opt, but you may want to use a different value, for example if you want to distribute a brew based package."
   )

diff --git a/doc/doxygen/CMakeLists.txt b/doc/doxygen/CMakeLists.txt
index 501d7ab930fd002d94eb3a3886cd7bd859e2a36a..0451e280c8c2c6fe28fc2634c85a209460767e1c 100644 (file)
--- a/doc/doxygen/CMakeLists.txt
+++ b/doc/doxygen/CMakeLists.txt
@@ -55,9 +55,35 @@ ADD_SUBDIRECTORY(code-gallery)
 #
 IF(DEAL_II_DOXYGEN_USE_MATHJAX)
   SET(_use_mathjax YES)
+  IF(NOT DEAL_II_DOXYGEN_USE_ONLINE_MATHJAX)
+    DEAL_II_FIND_PATH(MATHJAX_PATH MathJax.js
+      PATHS ${MATHJAX_ROOT}
+      $ENV{MATHJAX_ROOT}
+      "${CMAKE_PREFIX_PATH}/share/javascript/mathjax"
+      "${CMAKE_INSTALL_DATADIR}/javascript/mathjax"
+      "/usr/share/javascript/mathjax"
+      "/usr/share/yelp/mathjax"
+      DOC "Root path of MathJax.js"
+      )
+    IF(MATHJAX MATCHES "-NOTFOUND")
+      MESSAGE(FATAL_ERROR "MathJax was not found.")
+    ENDIF()
+  ENDIF()
+  IF(MATHJAX_PATH AND NOT DEAL_II_DOXYGEN_USE_ONLINE_MATHJAX)
+    SET(_mathjax_relpath ${MATHJAX_PATH})
+    MESSAGE(STATUS "Using local MathJax: " ${MATHJAX_PATH})
+    SET(MATHJAX_RELPATH_CONFIG "MATHJAX_RELPATH = ${MATHJAX_PATH}")
+  ELSE()
+    SET(_mathjax_relpath "https://cdn.mathjax.org/mathjax/latest")
+    MESSAGE(STATUS "Using web-based MathJax: " ${_mathjax_relpath})
+    SET(MATHJAX_RELPATH_CONFIG "")
+    MESSAGE(STATUS "Using default web-based MathJax")
+  ENDIF()
 ELSE()
   SET(_use_mathjax NO)
 ENDIF()
+ 
+
 CONFIGURE_FILE(
   ${CMAKE_CURRENT_SOURCE_DIR}/options.dox.in
   ${CMAKE_CURRENT_BINARY_DIR}/options.dox

diff --git a/doc/doxygen/options.dox.in b/doc/doxygen/options.dox.in
index 11b5e8c71f142ac806b571779ef0583b8adabd25..98ab862678e11c4dd6208893ac5e858a64a1453a 100644 (file)
--- a/doc/doxygen/options.dox.in
+++ b/doc/doxygen/options.dox.in
@@ -112,7 +112,7 @@ HTML_FILE_EXTENSION    = .html
 HTML_HEADER            = header.html
 HTML_FOOTER            = footer.html
 USE_MATHJAX            = @_use_mathjax@
-MATHJAX_RELPATH        = https://cdn.mathjax.org/mathjax/latest
+MATHJAX_RELPATH        = @_mathjax_relpath@
 MATHJAX_EXTENSIONS     = TeX/AMSmath TeX/AMSsymbols
 HTML_COLORSTYLE_HUE    = 220
 HTML_COLORSTYLE_SAT    = 200

diff --git a/doc/readme.html b/doc/readme.html
index 128ac71e445e82e9be34a98dfe7c579e0241477c..7ebe1aebb6b51cf445d9145ecc6161f163818eb2 100644 (file)
--- a/doc/readme.html
+++ b/doc/readme.html
@@ -316,18 +316,38 @@
       so, invoke <code>cmake</code> in the build instructions above as follows:
     </p>
 
-<pre>
-  cmake -DDEAL_II_COMPONENT_DOCUMENTATION=ON -DCMAKE_INSTALL_PREFIX=/path/install/dir ../deal.II
-</pre>
-
-<p>
-  For this to succeed, you will need <a href="http://www.perl.org/"
-                                       target="_top">Perl 5.x</a>,
-  <a href="http://www.doxygen.org/" target="_top">doxygen</a>
-  and <code>dot</code> (which is part of
-  the <a href="http://www.graphviz.org" target="_top">GraphViz</a>
-  package) to be installed.
-</p>
+    <pre>
+      cmake -DDEAL_II_COMPONENT_DOCUMENTATION=ON -DCMAKE_INSTALL_PREFIX=/path/install/dir ../deal.II
+    </pre>
+    
+    <p>
+      For this to succeed, you will need <a href="http://www.perl.org/"
+                                           target="_top">Perl 5.x</a>,
+      <a href="http://www.doxygen.org/" target="_top">doxygen</a>
+      and <code>dot</code> (which is part of
+      the <a href="http://www.graphviz.org" target="_top">GraphViz</a>
+      package) to be installed.
+    </p>
+  
+    <p>
+      The documentation contains links to pictures (e.g., for the
+      tutorial programs) that are by default stored online at the
+      dealii.org domain. If you want to use the documentation
+      completely offline, you can run
+      the <code>contrib/utilities/makeofflinedoc.sh</code> script in
+      an installed documentation directory to download all images.
+    </p>
+    
+    <p> Finally, the default for locally installed documentation is to
+      render formulas as images. You can force formulas to be
+      displayed via the MathJax system by
+      adding <code>-DDEAL_II_DOXYGEN_USE_MATHJAX=ON</code> to the
+      CMake call above. These formulas are then rendered natively by the
+      browser. With <code>-DDEAL_II_DOXYGEN_USE_ONLINE_MATHJAX=OFF<code>
+      CMake will try to find a local installation of MathJax scripts,
+      otherwise the online version of the scripts will be used in the
+      documentation.
+    </p>
 
     <p>
       Upon calling <code>make</code> and <code>make install</code>, this will