]> https://gitweb.dealii.org/ - dealii.git/commitdiff
improve html
authorGuido Kanschat <dr.guido.kanschat@gmail.com>
Wed, 28 Aug 2013 04:43:09 +0000 (04:43 +0000)
committerGuido Kanschat <dr.guido.kanschat@gmail.com>
Wed, 28 Aug 2013 04:43:09 +0000 (04:43 +0000)
git-svn-id: https://svn.dealii.org/trunk@30513 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/doc/development/cmake-internals.html
deal.II/doc/development/cmake.html
deal.II/doc/development/cmakelists.html
deal.II/doc/development/writing-documentation.html
deal.II/doc/documentation.html
deal.II/doc/readme.html

index 903af06bfa0e455ab933ad7e29a4c699c87f89b0..fbfdbab628f8986df7b770576d7761dd6bf0195f 100644 (file)
     <meta name="keywords" content="deal.II">
   </head>
 
-  <body>
-
-
-    <h1><acronym>Build system internals</h1>
-
-    <p>
-      This page provides details about the CMake build system. Files
-      processed by the top level <code>CMakeLists.txt</code> script are
-      listed in the TOC in chronological order.
-    </p>
-
-    <p>
-    <table class="tutorial" width="50%">
-      <tr><th colspan="2"><b><small>Table of contents</small></b></th></tr>
-      <tr><td valign="top">
-         <ul>
-           <li><a href="#codingstyle">Coding convention</a>
-          </ul>
-          </br><b>Configuration:</b>
-         <ul>
-           <li><a href="#setup"><code>./CMakeLists.txt</code> and
-              <code>./cmake/setup_*.cmake</code></a>
-           <li><a href="#checks"><code>./cmake/checks/check_*.cmake</code></a>
-            <li><a href="#findmodules"><code>./cmake/modules/Find*.cmake</code></a>
-           <li><a href="#configure"><code>./cmake/configure/configure_*.cmake</code></a>
-           <li><a href="#variables">Global variables controlling the build process</a>
-          </ul>
-          </br><b>Target definition and installation</b>
-         <ul>
-           <li><a href="#config.h.in"><code>./include/deal.II/base/config.h.in</code></a>
-            <li><a href="#source"><code>./source/CMakeLists.txt</code></a>
-            <li><a href="#projectconfig"><code>./cmake/config/CMakeLists.txt</code></a>
-          </ul>
-       </td>
-      </tr>
-    </table>
-    </p>
-
-    <a name="codingstyle"></a>
-    <h3> Coding convention </h3>
-    <p>
-      Coding conventions are always a matter of choice. Nevertheless, the
-      following rules should be considered:
-      <ul>
-        <li>
-          Statements and keywords are written in all caps.
-        <li>
-          Indenting is done by two spaces; the usual indenting rules apply.
-        <li>
-          The <code>ELSE()</code>, <code>ENDIF()</code>,
-          <code>ENDFOREACH()</code>, etc. statements shall not repeat the
-          corresponding condition in <code>IF()</code>,
-          <code>FOREACH()</code>, etc.
-        <li>
-          To emphasize a comment it may be enclosed by a leading and
-          trailing empty comment line.
-      </ul>
-      An example:
-      <pre>
-
-    FOREACH(_build ${DEAL_II_BUILD_TYPES})
-      #
-      # Set an appropriate keyword depending on target and build type:
-      #
-      IF(NOT "${CMAKE_BUILD_TYPE}" STREQUAL "DebugRelease")
-        SET(_keyword "general")
-      ELSE()
-        IF(_build MATCHES DEBUG)
-          SET(_keyword "debug")
-        ELSE()
-          SET(_keyword "optimized")
-        ENDIF()
-      ENDIF()
-    ENDFOREACH()
-      </pre>
-      <ul>
-        <li>
-          Line break is at 78 characters and should be obeyed whenever
-          reasonable.
-        <li>
-          Long statements should be broken into several lines at reasonable
-          places. Additional lines for a statement are indented by 2
-          spaces.
-        <li>
-          Multiline statements must end with the closing bracket at a
-          single line:
-      </ul>
-      <pre>
-
-    LIST(APPEND CONFIG_LIBRARIES
-      ${_keyword}
-      ${CONFIG_LIBRARIES_${_build}}
-      )
-
-    SET_TARGET_PROPERTIES(${DEAL_II_BASE_NAME}${DEAL_II_${build}_SUFFIX}
-      PROPERTIES
-      VERSION ${VERSION}
-      SOVERSION ${VERSION}
-      LINK_FLAGS "${DEAL_II_LINKER_FLAGS_${build}}"
-      COMPILE_DEFINITIONS "${DEAL_II_DEFINITIONS};${DEAL_II_DEFINITIONS_${build}}"
-      COMPILE_FLAGS "${DEAL_II_CXX_FLAGS_${build}}"
-      )
-      </pre>
-      CMake operates almost always with variables in global state. To guard
-      against accidental overwrite of variables the following naming
-      conventions must be followed at all times:
-      <ul>
-        <li>
-          Global (configuration) variables are written in all caps. When
-          introducing a new one, ensure that the name isn't already used
-          somewhere else. Unrelated global variables must never be
-          overwritten.
-        <li>
-          Global variables can be prefixed by <code>DEAL_II_</code>.
-          (Global variables defined by CMake are usually prefixed by
-          <code>CMAKE_</code>.)
-        <li>
-          Local variables should always be named in all lowercase with a
-          leading "_". Local variables cannot be assumed to remain valid.
-          The may get overwritten at any time.
-      </ul>
-    </p>
-
-
-    <a name="setup"></a>
-    <h3> <code>./CMakeLists.txt</code> and <code>./cmake/setup_*.cmake</code> </h3>
-
-    <p>
-      The very first configuration steps after some initial setup in
-      <code>./CMakeLists.txt</code> takes place in some
-      <code>./cmake/setup_*.cmake</code> files:
-      <ul>
-        <li> <code>setup_cached_variables.cmake</code>:
-          This sets up all cached variables prior to the call to
-          <code>PROJECT(deal.II)</code>. For details see the comment at the
-          top. Furthermore, some bookkeeping for compiler and linker flags
-          takes place, see <a href="cmake.html#configurebuild">the section
-          about compile flags</a>.
-        <li> <code>setup_deal_ii.cmake</code>:
-          This file is included immediately after the call to
-          <code>PROJECT(deal.II)</code> and will set up all <i>magic
-          numbers</i> such as names, definitions, relative and absolute
-          paths used in the build system. Most of the definitions are
-          guarded with the help of the <code>SET_IF_EMPTY</code> macro so
-          that it is possible to override the values from the command line.
-        <li> <code>setup_compiler_flags.cmake</code>
-          sets up a suitable set of default compile flag for a known
-          compiler by including the appropriate
-          <code>setup_compiler_flags_*.cmake</code> file. When adding new
-          flags or compiler support, please respect the following note
-          <pre>
+<body>
+<h1><acronym>Build system internals</h1>
+
+<p>
+  This page provides details about the CMake build system. Files
+  processed by the top level <code>CMakeLists.txt</code> script are
+  listed in the TOC in chronological order.
+</p>
+
+<div class="toc">
+  <ol>
+    <li><a href="#codingstyle">Coding convention</a></li>
+    <li>Configuration
+      <ol>
+       <li><a href="#setup"><code>./CMakeLists.txt</code> and
+           <code>./cmake/setup_*.cmake</code></a></li>
+       <li><a href="#checks"><code>./cmake/checks/check_*.cmake</code></a></li>
+        <li><a href="#findmodules"><code>./cmake/modules/Find*.cmake</code></a></li>
+       <li><a href="#configure"><code>./cmake/configure/configure_*.cmake</code></a></li>
+       <li><a href="#variables">Global variables controlling the build process</a></li>
+      </ol>
+    </li>
+    <li>Target definition and installation
+      <ol>
+       <li><a href="#config.h.in"><code>./include/deal.II/base/config.h.in</code></a></li>
+        <li><a href="#source"><code>./source/CMakeLists.txt</code></a></li>
+        <li><a href="#projectconfig"><code>./cmake/config/CMakeLists.txt</code></a></li>
+      </ol>
+    </li>
+</div>
+
+<a name="codingstyle"></a>
+<h2> Coding convention </h2>
+<p>
+  Coding conventions are always a matter of choice. Nevertheless, the
+  following rules should be considered:
+  <ul>
+    <li>
+      Statements and keywords are written in all caps.
+    <li>
+      Indenting is done by two spaces; the usual indenting rules apply.
+    <li>
+      The <code>ELSE()</code>, <code>ENDIF()</code>,
+      <code>ENDFOREACH()</code>, etc. statements shall not repeat the
+      corresponding condition in <code>IF()</code>,
+      <code>FOREACH()</code>, etc.
+    <li>
+      To emphasize a comment it may be enclosed by a leading and
+      trailing empty comment line.
+  </ul>
+  An example:
+<pre class="cmake">
+FOREACH(_build ${DEAL_II_BUILD_TYPES})
+#
+# Set an appropriate keyword depending on target and build type:
+#
+  IF(NOT "${CMAKE_BUILD_TYPE}" STREQUAL "DebugRelease")
+    SET(_keyword "general")
+  ELSE()
+    IF(_build MATCHES DEBUG)
+      SET(_keyword "debug")
+    ELSE()
+      SET(_keyword "optimized")
+    ENDIF()
+  ENDIF()
+ENDFOREACH()
+</pre>
+
+<ul>
+  <li>
+    Line break is at 78 characters and should be obeyed whenever
+    reasonable.
+  <li>
+    Long statements should be broken into several lines at reasonable
+    places. Additional lines for a statement are indented by 2
+    spaces.
+  <li>
+    Multiline statements must end with the closing bracket at a
+    single line:
+</ul>
+<pre class="cmake">
+LIST(APPEND CONFIG_LIBRARIES
+  ${_keyword}
+  ${CONFIG_LIBRARIES_${_build}}
+)
+
+SET_TARGET_PROPERTIES(${DEAL_II_BASE_NAME}${DEAL_II_${build}_SUFFIX}
+  PROPERTIES
+  VERSION ${VERSION}
+  SOVERSION ${VERSION}
+  LINK_FLAGS "${DEAL_II_LINKER_FLAGS_${build}}"
+  COMPILE_DEFINITIONS "${DEAL_II_DEFINITIONS};${DEAL_II_DEFINITIONS_${build}}"
+  COMPILE_FLAGS "${DEAL_II_CXX_FLAGS_${build}}"
+)
+</pre>
+
+<p>
+  CMake operates almost always with variables in global state. To
+  guard against accidental overwrite of variables the following naming
+  conventions must be followed at all times:
+</p>
+
+<ul>
+  <li>
+    Global (configuration) variables are written in all caps. When
+    introducing a new one, ensure that the name isn't already used
+    somewhere else. Unrelated global variables must never be
+    overwritten.
+  <li>
+    Global variables can be prefixed by <code>DEAL_II_</code>.
+    (Global variables defined by CMake are usually prefixed by
+    <code>CMAKE_</code>.)
+  <li>
+    Local variables should always be named in all lowercase with a
+    leading "_". Local variables cannot be assumed to remain valid.
+    The may get overwritten at any time.
+</ul>
+</p>
+
+<h2>Configuration</h2>
+
+<a name="setup"></a>
+<h3> <code>./CMakeLists.txt</code> and <code>./cmake/setup_*.cmake</code> </h3>
+
+<p>
+  The very first configuration steps after some initial setup in
+  <code>./CMakeLists.txt</code> takes place in some
+  <code>./cmake/setup_*.cmake</code> files:
+  <ul>
+    <li> <code>setup_cached_variables.cmake</code>:
+      This sets up all cached variables prior to the call to
+      <code>PROJECT(deal.II)</code>. For details see the comment at the
+      top. Furthermore, some bookkeeping for compiler and linker flags
+      takes place, see <a href="cmake.html#configurebuild">the section
+        about compile flags</a>.
+    <li> <code>setup_deal_ii.cmake</code>:
+      This file is included immediately after the call to
+      <code>PROJECT(deal.II)</code> and will set up all <i>magic
+        numbers</i> such as names, definitions, relative and absolute
+      paths used in the build system. Most of the definitions are
+      guarded with the help of the <code>SET_IF_EMPTY</code> macro so
+      that it is possible to override the values from the command line.
+    <li> <code>setup_compiler_flags.cmake</code>
+      sets up a suitable set of default compile flag for a known
+      compiler by including the appropriate
+      <code>setup_compiler_flags_*.cmake</code> file. When adding new
+      flags or compiler support, please respect the following note
+
+<pre>
 
     #
     # (./cmake/setup_compiler_flags.cmake)
     #   ./cmake/checks/check_01_system_features.cmake
     #   ./cmake/checks/check_02_compiler_bugs.cmake
     #
-          </pre>
-      </ul>
-    </p>
+</pre>
+  </ul>
+</p>
 
 
-    <a name="checks"></a>
-    <h3> <code>./cmake/checks/check_*.cmake</code> </h3>
+<a name="checks"></a>
+<h3> <code>./cmake/checks/check_*.cmake</code> </h3>
 
-    <p>
-      The next step in the configuration process is to include all
-      checks residing under <code>./cmake/checks</code>. Currently
-      there are:
-      <pre>
+<p>
+  The next step in the configuration process is to include all
+  checks residing under <code>./cmake/checks</code>. Currently
+  there are:
 
+<pre>
+    
     ./cmake/checks/check_01_compiler_features.cmake
       - Search for support for compiler dependent features such as stack
         trace support, demangler support, etc.
 
     ./cmake/checks/check_02_compiler_bugs.cmake
       - Check for compiler bugs
-      </pre>
-      <ul>
-        <li>
-          A check usually consists of a call to one of the macros below
-          that will set up a global variable. Please stick to the naming
-          convention <code>HAVE_&lt;..&gt;</code>, resp.
-          <code>DEAL_II_(HAVE|USE)_&lt;..&gt;</code>. <b>It is forbidden to
-          use a variable name starting with
-          <code>DEAL_II_WITH_&lt;..&gt;</code> because this prefix is
-          exclusively reserved for the feature mechanism described
-          below.</b> For some tests it might be necessary to manipulate <a
-          href="#variables">global variables</a>.
-        <li>
-          A platform check should have a prominent comment explaining what
-         it does and why it is there, and should state author and year.
-        <li>
-          There are a number of readily available platform check macros:
-        <pre>
+
+</pre>
+
+<ul>
+  <li>
+    A check usually consists of a call to one of the macros below
+    that will set up a global variable. Please stick to the naming
+    convention <code>HAVE_&lt;..&gt;</code>, resp.
+    <code>DEAL_II_(HAVE|USE)_&lt;..&gt;</code>. <b>It is forbidden to
+      use a variable name starting with
+      <code>DEAL_II_WITH_&lt;..&gt;</code> because this prefix is
+      exclusively reserved for the feature mechanism described
+      below.</b> For some tests it might be necessary to manipulate
+    <a href="#variables">global variables</a>.
+  <li>
+    A platform check should have a prominent comment explaining what
+    it does and why it is there, and should state author and year.
+  <li>
+    There are a number of readily available platform check macros:
+    
+<pre>
 
     CHECK_CXX_SOURCE_COMPILES(source variable)
       - Checks whether it is possible to compile _and_ link the code snippet
 
     CHECK_CXX_COMPILER_FLAG(flag variable)
       - Sets the variable to 1 if the compiler understands the flag.
-         </pre>
 
-       <li> Necessary compiler flags can easily set in the string variable
-         <code>CMAKE_REQUIRED_FLAGS</code>. There are two small macros
-         that do this job nicely:
-         <pre>
+</pre>
+
+  <li> Necessary compiler flags can easily set in the string variable
+    <code>CMAKE_REQUIRED_FLAGS</code>. There are two small macros
+    that do this job nicely:
 
+<pre>
+  
     PUSH_TEST_FLAG("-Werror")
     CHECK_CXX_SOURCE_COMPILES(...)
     POP_TEST_FLAG()
-         </pre>
+</pre>
 
-        <li> Necessary include directories and libraries necessary for
-        linkage can be set in the list variables
-        <code>CMAKE_REQUIRED_INCLUDES</code> and
-        <code>CMAKE_REQUIRED_LIBRARIES</code>. It is best to append these
-        lists and later on reset <code>CMAKE_REQUIRED_*</code> (including
-        <code>CMAKE_REQUIRED_FLAGS</code>) to their default values:
-         <pre>
+  <li> Necessary include directories and libraries necessary for
+    linkage can be set in the list variables
+    <code>CMAKE_REQUIRED_INCLUDES</code> and
+    <code>CMAKE_REQUIRED_LIBRARIES</code>. It is best to append these
+    lists and later on reset <code>CMAKE_REQUIRED_*</code> (including
+    <code>CMAKE_REQUIRED_FLAGS</code>) to their default values:
+    
+<pre>
 
     LIST(APPEND CMAKE_REQUIRED_INCLUDES &lt;a list of includes&gt;)
     LIST(APPEND CMAKE_REQUIRED_LIBRARIES &lt;a list of libraries&gt;)
     CHECK_CXX_SOURCE_COMPILES(...)
     RESET_CMAKE_REQUIRED()
-         </pre>
-      </ul>
-    </p>
-
-
-
-    <a name="findmodules"></a>
-    <h3> <code>./cmake/modules/Find*.cmake</code> </h3>
-
-    <p>
-      These are find modules for the <code>configure_*.cmake</code> files
-      and the <code>CONFIGURE_FEATURE</code> macro as will explained later.
-      It is crucial that a find module behaves correctly. Therefore, the
-      following rules are mandatory:
-      <ul>
-        <li>
-          The <i>sole</i> purpose of a find module is to find an external
-          library (no deal.II specific dependency checking, no
-          compatibility checking).
-        <li>
-          It should do so by appropriate <code>FIND_LIBRARY</code> and
-          <code>FIND_PATH</code> calls. The results of this calls should be the
-          only cached variables.
-        <li>
-          <code>FIND_PACKAGE_HANDLE_STANDARD_ARGS</code> should be used for
-          setting <code>FEATURE_FOUND</code> as this already respects the
-          <code>QUIET</code> and <code>REQUIRED</code> keywords.
-        <li>
-          A <code>WARNING</code>, <code>SEND_ERROR</code> or
-          <code>FATAL_ERROR</code> must be avoided (the only exception is
-          the <code>REQUIRED</code> keyword).
-        <li>
-          If successful, the following uncached variables might be set:
-          <pre>
-
+</pre>
+</ul>
+</p>
+
+<a name="findmodules"></a>
+<h3> <code>./cmake/modules/Find*.cmake</code> </h3>
+
+<p>
+  These are find modules for the <code>configure_*.cmake</code> files
+  and the <code>CONFIGURE_FEATURE</code> macro as will explained later.
+  It is crucial that a find module behaves correctly. Therefore, the
+  following rules are mandatory:
+  <ul>
+    <li>
+      The <i>sole</i> purpose of a find module is to find an external
+      library (no deal.II specific dependency checking, no
+      compatibility checking).
+    <li>
+      It should do so by appropriate <code>FIND_LIBRARY</code> and
+      <code>FIND_PATH</code> calls. The results of this calls should be the
+      only cached variables.
+    <li>
+      <code>FIND_PACKAGE_HANDLE_STANDARD_ARGS</code> should be used for
+      setting <code>FEATURE_FOUND</code> as this already respects the
+      <code>QUIET</code> and <code>REQUIRED</code> keywords.
+    <li>
+      A <code>WARNING</code>, <code>SEND_ERROR</code> or
+      <code>FATAL_ERROR</code> must be avoided (the only exception is
+      the <code>REQUIRED</code> keyword).
+    <li>
+      If successful, the following uncached variables might be set:
+
+<pre>
+       
     FEATURE_FOUND
     FEATURE_LIBRARIES
     FEATURE_INCLUDE_DIRS
     FEATURE_VERSION_MAJOR
     FEATURE_VERSION_MINOR
     FEATURE_VERSION_SUBMINOR
-          </pre>
-          There are obviously valid exceptions from this rule, though.
-        <li>
-          Only "local" variables "<code>_&lt;all lowercase&gt;</code>" or
-          "global" variables prefixed by <code>FEATURE_</code> may be
-          altered. Do not set <code>DEAL_II_*</code> or <code>CMAKE_*</code>
-          variables directly!
-        <li>
-          A hint with <code>FEATURE_DIR</code> can be set up for
-          convenience. It is best to start the <code>Find</code> module by
-          <pre>
-
-    SET_IF_EMPTY(FEATURE_DIR "$ENV{FEATURE_DIR}")
-          </pre>
-          and use <code>FEATURE_DIR</code> as a hint. If the external
-          library could be found, hide it via
-          <code>MARK_AS_ADVANCED</code>, if the external library could not
-          be found, set a cache value:
-          <pre>
-
-    SET(FEATURE_DIR "" CACHE PATH "An optional hint to a FEATURE directory")
-          </pre>
-      </ul>
+</pre>
 
+There are obviously valid exceptions from this rule, though.
+    <li>
+      Only "local" variables "<code>_&lt;all lowercase&gt;</code>" or
+      "global" variables prefixed by <code>FEATURE_</code> may be
+      altered. Do not set <code>DEAL_II_*</code> or <code>CMAKE_*</code>
+      variables directly!
+    <li>
+      A hint with <code>FEATURE_DIR</code> can be set up for
+      convenience. It is best to start the <code>Find</code> module by
 
+<pre>
 
-    <a name="configure"></a>
-    <h3> <code>./cmake/configure/configure_*.cmake</code> </h3>
+    SET_IF_EMPTY(FEATURE_DIR "$ENV{FEATURE_DIR}")
+</pre>
+
+and use <code>FEATURE_DIR</code> as a hint. If the external
+library could be found, hide it via
+<code>MARK_AS_ADVANCED</code>, if the external library could not
+be found, set a cache value:
+<pre>
+  
+    SET(FEATURE_DIR "" CACHE PATH "An optional hint to a FEATURE directory")
+</pre>
+  </ul>
 
-    <p>
-      The final step in the configuration phase is the setup of features
-      (which refer to external or bundled libraries
-      <acronym>deal.II</acronym> can optionally interface with.)
 
-    </p>
+  <a name="configure"></a>
+  <h3> <code>./cmake/configure/configure_*.cmake</code> </h3>
+  
+<p>
+  The final step in the configuration phase is the setup of features
+  (which refer to external or bundled libraries
+  <acronym>deal.II</acronym> can optionally interface with.)
+  
+</p>
 
     <p>
       At bare minimum <code>configure_&lt;feature&gt;.cmake</code>
       </ul>
     </p>
 
-
+    
+    <h2>Target definition and installation</h2>
     <a name="config.h.in"></a>
     <h3> <code>./include/deal.II/base/config.h.in</code> </h3>
 
index 8139fdc11090a2a07426a1dc1314f99f3fc441b2..2683cc1d7ed7f17eb55a0c3ce65a85e0d68edbb3 100644 (file)
       <acronym>deal.II</acronym> CMake build system.
     </p>
 
-    <p>
-    <table class="tutorial" width="50%">
-      <tr><th colspan="2"><b><small>Table of contents</small></b></th></tr>
-      <tr><td valign="top">
-         <ul>
-           <li><a href="#operating">Operating cmake</a>
-              <ul>
-                <li><a href="#operatingmanip">Manipulating the cache</a>
-                <li><a href="#operatingccmake"><code>ccmake</code> and special build targets </a>
-                <li><a href="#operatingshortcuts">Shortcuts</a>
-              </ul>
-           <li><a href="#configure">Configuration options</a>
-             <ul>
-               <li><a href="#configurefeature">Feature configuration</a>
-               <li><a href="#configureautoconf">Autoconfiguration</a>
-               <li><a href="#configureext">External library locations</a>
-               <li><a href="#configureoverride">Manual override</a>
-               <li><a href="#configurecomp">Component selection</a>
-               <li><a href="#configurebuild">Build configuration</a>
-               <li><a href="#compiler">Selecting a compiler</a>
-               <li><a href="#configureinstall">Installation</a>
-             </ul>
-           <li><a href="#advanced">Initial cache file and advanced options</a>
-           <li><a href="#compiling">Compiling only certain parts</a>
-         </ul>
-       </td>
-      </tr>
-    </table>
-    </p>
-
+    <div class="toc">
+      <ol>
+       <li><a href="#operating">Operating cmake</a>
+          <ol>
+            <li><a href="#operatingmanip">Manipulating the cache</a></li>
+            <li><a href="#operatingccmake"><code>ccmake</code> and special build targets </a></li>
+            <li><a href="#operatingshortcuts">Shortcuts</a></li>
+         </ol>
+       </li>
+       <li><a href="#configure">Configuration options</a>
+         <ol>
+           <li><a href="#configurefeature">Feature configuration</a></li>
+           <li><a href="#configureautoconf">Autoconfiguration</a></li>
+           <li><a href="#configureext">External library locations</a></li>
+           <li><a href="#configureoverride">Manual override</a></li>
+           <li><a href="#configurecomp">Component selection</a></li>
+           <li><a href="#configurebuild">Build configuration</a></li>
+           <li><a href="#compiler">Selecting a compiler</a></li>
+           <li><a href="#configureinstall">Installation</a></li>
+         </ol>
+       </li>
+       <li><a href="#advanced">Initial cache file and advanced options</a></li>
+       <li><a href="#compiling">Compiling only certain parts</a></li>
+      </ol>
+    </div>
+    
     <a name="operating"></a>
-    <h3>Operating cmake</h3>
+    <h2>Operating cmake</h2>
 
     <p>
       When configuring <acronym>deal.II</acronym> by
     </p>
 
     <a name="operatingmanip"></a>
-    <h4> Manipulating the cache </h4>
+    <h3> Manipulating the cache </h3>
 
     <p>
       A cached variable can be set on the command line via
     </p>
 
     <a name="operatingccmake"></a>
-    <h4> <code>ccmake</code> and special build targets </h4>
+    <h3> <code>ccmake</code> and special build targets </h3>
 
     <p>
       A very convenient way to alter the configuration is to use the graphical
     </p>
 
     <a name="operatingshortcuts"></a>
-    <h4> Shortcuts </h4>
+    <h3> Shortcuts </h3>
 
     <p>
       All variables starting with <code>WITH_</code> will be automatically
     </p>
 
     <a name="configure"></a>
-    <h3>Configuration options</h3>
+    <h2>Configuration options</h2>
 
     <p>
       The various configuration options of the
 
 
     <a name="configurefeature"></a>
-    <h4>Feature configuration</h4>
+    <h3>Feature configuration</h3>
 
     <p>
       <acronym>deal.II</acronym> provides (optional) interfaces to quite
 
 
     <a name="configureautoconf"></a>
-    <h4> Autoconfiguration </h4>
+    <h3> Autoconfiguration </h3>
 
     <p>
       As long as <code>DEAL_II_WITH_&lt;FEATURE&gt;</code> is
 
 
     <a name="configureext"></a>
-    <h4> External library locations </h4>
+    <h3> External library locations </h3>
 
     <p>
       External libraries will be searched depending on hints in the following
     </p>
 
     <a name="configureoverride"></a>
-    <h4> Manual override </h4>
+    <h3> Manual override </h3>
     <p><b>Warning:</b> Do not do this unless absolutely necessary!</p>
     <p>
       It is possible to override the CMake find mechanism for external
 
 
     <a name="configurecomp"></a>
-    <h4> Component selection </h4>
+    <h3> Component selection </h3>
 
     <p>
       The following options control which components of
 
 
     <a name="configurebuild"></a>
-    <h4> Build configuration </h4>
+    <h3> Build configuration </h3>
 
     <p>
       The <code>cmake</code> variable <code>CMAKE_BUILD_TYPE</code>
 
 
     <a name="compiler"></a>
-    <h4> Selecting a compiler </h4>
+    <h3> Selecting a compiler </h3>
 
     </p>
       Compilers can be switched either by command line or by setting
 
 
     <a name="configureinstall"></a>
-    <h4> Installation </h4>
+    <h3> Installation </h3>
 
     <p>
       the location,
 
 
     <a name="advanced"></a>
-    <h3>Initial cache file and advanced options</h3>
+    <h2>Initial cache file and advanced options</h2>
 
     A sample configuration file for preloading the CMake cache with
     <pre>
 
 
     <a name="compiling"></a>
-    <h3> Compiling only certain parts </h3>
+    <h2> Compiling only certain parts </h2>
     <p>
 
     <p>
index d0a7a833f9c0f20752eca7e0ca27f94d24b7b5b4..44fb38ae3f9133cd4ef7a0558fd18adaf3bf7c97 100644 (file)
     <meta name="keywords" content="deal.II">
   </head>
   
-  <body>
-    
-    <h1>How to use CMake to configure your projects with <acronym>deal.II</acronym></h1>
-    
-    <div class="toc">
+<body>
+<h1>How to use CMake to configure your projects with <acronym>deal.II</acronym></h1>
+
+<div class="toc">
+  <ol>
+    <li><a href="#cmakesimple">Simple <code>CMakeLists.txt</code></a>
       <ol>
-        <li><a href="#cmakesimple">Simple <code>CMakeLists.txt</code></a>
-         <ol>
-           <li><a href="#cmakesimple.multiple">Adding multiple executable targets</a>
-           <li><a href="#cmakesimple.libs">Adding libraries and common source files</a>
-           <li><a href="#cmakesimple.run">Adding a "run" target</a>
-         </ol>
-        <li><a href="#cmakeauto">Autopilot style <code>CMakeLists.txt</code>            <li><a href="#cmakeadvanced">Advanced <code>CMakeLists.txt</code></a>
-              <ol>
-               <li> TODO, see list</li>
-              </ol>
-            <li><a href="#dealiiconfig"><code>deal.IIConfig.cmake</code></a>
-            <li><a href="#legacy">Legacy
-               <code>Make.global_options</code></a>
+       <li><a href="#cmakesimple.multiple">Adding multiple executable targets</a></li>
+       <li><a href="#cmakesimple.libs">Adding libraries and common source files</a></li>
+       <li><a href="#cmakesimple.run">Adding a "run" target</a></li>
       </ol>
-    </div>
-
-    <p>
-      <code>cmake</code> is the configuration and build tool we use
-      in <acronym>deal.II</acronym>. Its advantage is not only that it makes
-      configuration of <acronym>deal.II</acronym> itself simpler across
-      platforms (compared to the older <code>autoconf/make</code> combination)
-      but also that it <i>exports</i> information about the deal.II
-      configuration that makes it particularly simple for projects
-      using <acronym>deal.II</acronym> to configure and link against it.
-    </p>
-
-    <p>
-      <code>cmake</code> is controlled by input files that by convention are
-      called <code>CMakeLists.txt</code>, listing both configuration commands
-      as well as dependencies between source files and targets.
-      This page presents some <code>CMakeLists.txt</code> examples for
-      potential use in your projects. (A detailed description of the
-      <acronym>deal.II</acronym> project configuration is given in the
-      <a href="cmake.html" target="body">deal.II CMake ReadMe</a>.)
-    </p>
-
-    <a name="cmakesimple"></a>
-    <h2>Simple CMakeLists.txt</h2>
-
-    <p>
-      In this section, we start out with a
-      minimal <code>CMakeLists.txt</code> based on
-      the <code>DEAL_II_SETUP_TARGET</code> macro. This method gives
-      full control of what's happening and is easily extensible to
-      more complex projects, as exemplified in the subsections here an
-      later in the section on <a href="cmakeadvanced">advanced
-      topics</a>. Here is a full example
-      (<a href="CMakeLists.txt.sample3" target="_top">plain text</a>
-      version):
-      
-      <p class="todo"> Fix plain text after finalizing!</p>
+    </li>
+    <li><a href="#cmakeadvanced">Advanced <code>CMakeLists.txt</code></a>
+      <ol>
+       <li> TODO, see list</li>
+      </ol>
+    </li>
+    <li><a href="#cmakeauto">Autopilot style <code>CMakeLists.txt</code></li>
+    <li><a href="#dealiiconfig"><code>deal.IIConfig.cmake</code></a></li>
+    <li><a href="#legacy">Legacy <code>Make.global_options</code></a></li>
+  </ol>
+</div>
+
+<p>
+  <code>cmake</code> is the configuration and build tool we use
+  in <acronym>deal.II</acronym>. Its advantage is not only that it makes
+  configuration of <acronym>deal.II</acronym> itself simpler across
+  platforms (compared to the older <code>autoconf/make</code> combination)
+  but also that it <i>exports</i> information about the deal.II
+  configuration that makes it particularly simple for projects
+  using <acronym>deal.II</acronym> to configure and link against it.
+</p>
+
+<p>
+  <code>cmake</code> is controlled by input files that by convention are
+  called <code>CMakeLists.txt</code>, listing both configuration commands
+  as well as dependencies between source files and targets.
+  This page presents some <code>CMakeLists.txt</code> examples for
+  potential use in your projects. (A detailed description of the
+  <acronym>deal.II</acronym> project configuration is given in the
+  <a href="cmake.html" target="body">deal.II CMake ReadMe</a>.)
+</p>
+
+<a name="cmakesimple"></a>
+<h2>Simple CMakeLists.txt</h2>
+
+<p>
+  In this section, we start out with a
+  minimal <code>CMakeLists.txt</code> based on
+  the <code>DEAL_II_SETUP_TARGET</code> macro. This method gives
+  full control of what's happening and is easily extensible to
+  more complex projects, as exemplified in the subsections here an
+  later in the section on <a href="cmakeadvanced">advanced
+    topics</a>. Here is a full example
+  (<a href="CMakeLists.txt.sample3" target="_top">plain text</a>
+  version):
+  
+<p class="todo"> Fix plain text after finalizing!</p>
 
 <pre class="cmake">
 CMAKE_MINIMUM_REQUIRED(VERSION 2.8.8)
@@ -75,21 +76,58 @@ CMAKE_MINIMUM_REQUIRED(VERSION 2.8.8)
 FIND_PACKAGE(deal.II 8.0 REQUIRED
   HINTS ${DEAL_II_DIR} ../ ../../ $ENV{DEAL_II_DIR}
 )
-
 DEAL_II_INITIALIZE_CACHED_VARIABLES()
+
 PROJECT(myproject CXX)
 
 ADD_EXECUTABLE(mycode mycode.cc)
 DEAL_II_SETUP_TARGET(mycode)
 </pre>
 
-      <p class="todo"> Explain the code!</p>
+<p>
+  The first line of this code makes sure that a sufficiently high
+  version of CMake is installed. 2.8.8 is the minimal version required
+  to set up <acronym>deal.II</acronym>, therefore it is safe to use this
+  number here.
+</p>
+
+<p>
+  Next, we find our deal.II installation, in this case requiring at
+  least version 8.0, which is the first version using
+  CMake. The <code>HINTS</code> are a list of directories where the
+  install directory of deal.II is likely to be found. Here, we check
+  whether we are in a subdirectory (first and second level) of the
+  deal.II installation and otherwise use the
+  variable <code>DEAL_II_DIR</code>.
+  <q class="todo">Matthias, what is the difference between the first
+  and the last entry?</q>  This list can be changed according to your
+  preferences. After finding the deal.II project, we fetch its chached
+  variables. You can inspect these for instance
+  with <code>ccmake</code>.
+</p>
+
+<p>
+  Every <code>CMAkeLists.txt</code> must contain a project definition,
+  which we do next. <q class="todo">Matthias, I have been happy
+  without the CXX...?</q>
+</p>
+
+<p>
+  Finally, the last two lines define the executable that is to be
+  produced and its source code.
+</p>
+
+
+<p class="todo"> Explain the macros or link to explanation below</p>
+
+<a name="cmakesimple.multiple"></a>
+<h3>Adding multiple executable targets</h3>
+
+<p>
+  In order to specify multiple executable targets, simply repeat
+  the last two lines of the simple <code>CMakeLists.txt</code>:
+</p>
 
-    <a name="cmakesimple.multiple"></a>
-    <h3>Adding multiple executable targets</h3>
-    
-    <p>In order to specify multiple executable targets, simply repeat
-    the last two lines of the simple <code>CMakeLists.txt</code>:</p>
 <pre class="cmake">
 ADD_EXECUTABLE(mycode2 mycode2.cc)
 DEAL_II_SETUP_TARGET(mycode2)
@@ -157,19 +195,78 @@ ADD_CUSTOM_TARGET(run COMMAND mycode
 </pre>
 
 
-    <a name="cmakesauto"></a>
-    <h2>Autopilot style CMakeLists.txt</h2>
+<a name="cmakeadvanced"></a>
+<h2> Advanced <code>CMakeLists.txt</code></h2>
 
-    <p>
-      If you want a make interface similar to the deal.II library and
-      its tutorial, namely maker targets for debug and release
-      versions, running the code and cleaning, the easiest way to
-      write a <code>CMakeLists.txt</code> file may be to use
-      an "autopilot" style macro. Here is a minimalistic example for the
-      step-1 tutorial program (<a href="CMakeLists.txt.sample1"
-        target="_top">plain text</a> version) that can be used for simple
-      projects:
-    </p>
+<pre class="todo">
+  
+  A Subsection for each of the following:
+  
+  - control statements (if and foreach)
+  
+  - file glob to pick up sources
+  
+  - DEAL_II_SETUP_TARGET and DEAL_II_INITIALIZE_CACHED_VARIABLES
+  revisited
+  
+  - add include dirs and compile definitions to a directory or target
+  
+  - provide a ./run folder and target
+  
+  - custom targets to switch between release and debug
+  
+  - installation
+</pre>
+
+<a name="extfinding"></a>
+<h3> Finding the deal.II library </h3>
+
+<p>
+  Finding the <acronym>deal.II</acronym> library should be no more than
+  <pre>
+    
+    FIND_PACKAGE(deal.II REQUIRED)
+  </pre>
+  in your CMakeLists.txt file.  You may have to hint for the location
+  of the <code>deal.IIConfig.cmake</code> file.  Either by directly
+  specifying <code>deal.II_DIR</code> to point to the path were the
+  <code>deal.IIConfig.cmake</code> file is located:
+  
+<p class="todo"> is deal.II_DIR still accurate? We use different
+above. BTW, that is an <b>UGLY</b> variable name.</p>
+  
+<pre>    
+cmake -Ddeal.II_DIR=/path/to/the/config/file &lt;...&gt;
+
+</pre>
+  or by specifying a search path via <code>CMAKE_PREFIX_PATH</code>,
+  e.g.
+  <pre>
+    
+    cmake -DCMAKE_PREFIX_PATH=~/workspace/local
+  </pre>
+  In this case <code>deal.IIConfig.cmake</code> will be searched
+  for in
+  <pre>
+    
+    ~/workspace/local/
+    ~/workspace/local/lib/cmake/deal.II/
+  </pre>
+</p>
+
+<a name="cmakesauto"></a>
+<h2>Autopilot style CMakeLists.txt</h2>
+
+<p>
+  If you want a make interface similar to the deal.II library and
+  its tutorial, namely maker targets for debug and release
+  versions, running the code and cleaning, the easiest way to
+  write a <code>CMakeLists.txt</code> file may be to use
+  an "autopilot" style macro. Here is a minimalistic example for the
+  step-1 tutorial program (<a href="CMakeLists.txt.sample1"
+                             target="_top">plain text</a> version) that can be used for simple
+  projects:
+</p>
 
 <pre class="cmake">
 FIND_PACKAGE(deal.II 8.0 REQUIRED
@@ -263,81 +360,19 @@ SET(TARGET_RUN
 )
 </pre>
 
-    <a name="cmakeadvanced"></a>
-    <h2> Advanced <code>CMakeLists.txt</code></h2>
 
-    <pre class="todo">
+<a name="dealiiconfig"></a>
+<h2>  <code>deal.IIConfig.cmake</code> </h2>
 
-      A Subsection for each of the following:
-
-      - Common code for several targets. Library or adding to target definition
-
-      - control statements (if and foreach)
-
-      - file glob to pick up sources
-
-      - DEAL_II_SETUP_TARGET and DEAL_II_INITIALIZE_CACHED_VARIABLES
-        revisited
-
-      - add include dirs and compile definitions to a directory or target
-
-      - provide a ./run folder and target
-
-      - custom targets to switch between release and debug
-
-      - installation
-    </pre>
-
-    <a name="extfinding"></a>
-    <h3> Finding the deal.II library </h3>
-
-    <p>
-    Finding the <acronym>deal.II</acronym> library should be no more than
-      <pre>
-
-    FIND_PACKAGE(deal.II REQUIRED)
-      </pre>
-      in your CMakeLists.txt file.  You may have to hint for the location
-      of the <code>deal.IIConfig.cmake</code> file.  Either by directly
-      specifying <code>deal.II_DIR</code> to point to the path were the
-      <code>deal.IIConfig.cmake</code> file is located:
-
-      <p class="todo"> is deal.II_DIR still accurate? We use different above
-
-      <pre>
-
-    cmake -Ddeal.II_DIR=/path/to/the/config/file &lt;...&gt;
-      </pre>
-      or by specifying a search path via <code>CMAKE_PREFIX_PATH</code>,
-      e.g.
-      <pre>
-
-    cmake -DCMAKE_PREFIX_PATH=~/workspace/local
-      </pre>
-      In this case <code>deal.IIConfig.cmake</code> will be searched
-      for in
-      <pre>
-
-    ~/workspace/local/
-    ~/workspace/local/lib/cmake/deal.II/
-      </pre>
-    </p>
-
-
-    <a name="dealiiconfig"></a>
-    <h2>  <code>deal.IIConfig.cmake</code> </h2>
-
-    <p>
-      Importing the deal.IIConfig.cmake file via <code>FIND_PACKAGE</code>
-      will set the following variables and macros; all of the form
-      <code>DEAL_II_*</code>:
-      <pre>
-
-      <p class="todo"> A long list with detailed explanation...</p>
-
-      </pre>
-
-    </p>
+<p>
+  Importing the deal.IIConfig.cmake file via <code>FIND_PACKAGE</code>
+  will set the following variables and macros; all of the form
+  <code>DEAL_II_*</code>:
+</p>
+<pre class="todo">  
+A long list with detailed explanation...  
+</pre>
+  
 
 
 
index 4ab4d3e3187ed0d405ea63d094ab80b158510c26..e9b037dffd16016ad820feaef3ac4dfab4608cca 100644 (file)
 
     <li> <em>Typewriter font:</em>
          <p>In order to use typewriter font for instance for function
-         arguments or variables, use the <code>&lt;tt&gt;</code> HTML
+         arguments or variables, use the <code>&lt;code&gt;</code> HTML
          tag. For a single word, you can also use the form <code>@p
-         one_word_without_spaces</code>.</p>
+         one_word_without_spaces</code>. The <code>&lt;tt&gt;</code> is obsolete in HTML5</p>
 
          <p>
          If you refer to member variables and member functions
index 941beef63ef6dad71bb3b73814d4cb78c8657d5d..40baede90b1a91214369383e3b1f65ea06bbc0ec 100644 (file)
     <meta name="keywords" content="deal.II">
     <meta name="svn_id" content="$Id$">
   </head>
-  <body>
-
-
-
-
-    <h2>Online documentation</h2>
-
-    <table class="tutorial" width="40%">
-      <tr><th colspan="2"><b><small>Table of contents</small></b></th></tr>
-      <tr><td valign="top">
-         <ul>
-           <li> <a href="#readme.html">ReadMe</a></li>
-           <li> <a href="#tutorials">Tutorials</a></li>
-           <li> <a href="#API">Programming interface</a></li>
-           <li> <a href="#dev">Development information</a></li>
-           <li> <a href="#reports">Reports</a></li>
-           <li> <a href="#publications">Publications</a></li>
-           <li> <a href="#license">Copyright and licence</a></li>
-         </ul>
-       </td>
-      </tr>
-    </table>
-
-
-    <p>
-      <acronym>deal.II</acronym> comes with quite extensive online
-      documentation, which falls into several categories. They are
-      listed below.
-    </p>
-
-
-    <h3><a href="readme.html">ReadMe</a></h3>
-
-    <p>
-      First, there is the <a href="readme.html" target="body">README file</a> of
-      the library. It gives information on system requirements,
-      installation, and copyright.
-    </p>
-
-    <h3><a href="tutorials">Tutorials</a></h3>
-
-    <p>
-      The <a href="doxygen/tutorial/index.html"
-            target="_top">tutorial</a> is
-      for new users of the library. It explains the basic elements of
-      finite element programs based on the library, and provides small
-      example programs. You can also reach the tutorial link from the menu bar
-      at the left.
-    </p>
-
-    <p>
-      Note that along with the rest of the documentation, the local HTML pages
-      of the tutorials need to be generated first. Please follow the
-      instructions in the
-      <a href="readme.html" target="body">ReadMe file</a> on how to do
-      this.
-    </p>
-
-
-    <h3><a href="API">Programming interface</a></h3>
-
-    <p>
-      The <a href="doxygen/deal.II/index.html" target="_top">programming
-       interface/manual</a> pages are what you will need most often as a
-      reference of all classes, functions and variables in the library. They
-      are extensively documented (presently more than 5000 pages if
-      printed), and generated by <a href="http://www.doxygen.org/"
-                                   target="_top">Doxygen</a>. There is also a quick link to these pages from
-      the menu bar at the left.
-    </p>
-
-    <p>
-      The documentation uses many of the features of Doxygen. In particular,
-      the link takes you straight to a page that lists <i>modules</i>, a way
-      to group classes with similar purposes. This may be what you are probably
-      interested in when you are not yet familiar with the library. If you
-      already know your way around and want to look up the signature of a
-      particular member function, for example, you may go to the class view or
-      choose any of the other ways in which Doxygen allows you to navigate
-      through the documentation.
-    </p>
-
-    <p>
-      Just as for the tutorials, the API docs need to be generated first,
-      if you download <acronym>deal.II</acronym>. Please follow the
-      instructions in the
-      <a href="readme.html" target="body">ReadMe file</a> on how to do
-      this.
-    </p>
-
-
-    <h3><a name="dev">Development information</a></h3>
-
-    <p>
-      If you plan to <a href="development/index.html"
-                       target="_top">develop your own applications</a> using
-      <acronym>deal.II</acronym>, it might be worth to take a look
-      at <a href="development/index.html" target="_top">this
-       page</a>.
-    </p>
-
-
-    <h3><a name="reports">Reports</a></h3>
-
-    <p>
-      There are a number of papers that describe the overall design or
-      individual aspects of <acronym>deal.II</acronym>. Please refer to the
-      papers listed at the top of the <a href="publications/index.html"
-                                        target="body">publications page</a> for full references. In addition,
-      there are the following reports:
-      <ul>
-        <li> <p>
-            A publication on the
-           <a href="reports/dimension-independent/index.html"
-               target="body">basics of dimension independent
-              programming</a> in <acronym>deal.II</acronym> (by Wolfgang
-            Bangerth). This explains some of the fundamentals of the
-            library's design, though rather briefly due to the page
-            limit imposed for the publication.
-         </p>
-
-         <p>
-           This publication appeared in
-            the proceedings of the 16th IMACS World Congress,
-            Lausanne, Switzerland, 2000. See the
-           <a href="publications/index.html" target="body">publications</a>
-           page for the full reference as well as a way to obtain a
-            reprint of the original paper as a postscript or PDF file.
-         </p>
-
-       <li> <p>
-            A brief report about the classes involved in the
-           <a href="reports/class-hierarchies/index.html"
-               target="body">iterators and accessors</a>
-           used to access cells in the triangulations and the data
-           thereon, such as their geometry, the number of the
-           degrees of freedom, data values, etc. You may want to
-            read this object or parts of it if you want to know what
-            information is available from iterators (by Wolfgang
-            Bangerth).
-         </p>
-
-        <li> <p>
-           A brief report on <a href="reports/mapping_q/index.html"
-                                target="body">mapping</a> functions of higher polynomial
-           degrees (by Ralf Hartmann). These allow the realisation
-           of higher order boundary approximations. This report
-           gives the theoretical background of the
-           <code>MappingQ</code> class.
-         </p>
-
-        <li> <p>
-            A report on
-           <a href="reports/assemble/assemble.pdf"
-               target="body">assembling matrices</a> (by Wolfgang
-            Bangerth). This report looks in particular at how
-            matrices are assembled for vector-valued problems, and
-            how things change if vector-valued finite elements are
-            used for which the shape functions have more than one
-            non-zero vector component, such as Nedelec or
-            Raviart-Thomas elements. There are printable
-            versions of the report
-           <a href="reports/assemble/assemble.ps"
-               target="body">in postscript</a> and
-           <a href="reports/assemble/assemble.pdf"
-               target="body">PDF format</a>.
-         </p>
-
-        <li> <p>
-            A very detailed report on
-           <a href="reports/nedelec/nedelec.pdf"
-               target="body">Nedelec elements</a> (by Anna
-            Schneebeli, University of Basel, Switzerland). It
-            explains the construction and application of Nedelec
-            edge elements for H-curl spaces, as used, for example,
-            in the numerical solution of the Maxwell equations. It
-            also gives numerical results obtained with deal.II.
-           There is also a <a href="reports/nedelec/nedelec.ps"
-                              target="body">postscript version of the report</a>.
-         </p>
-
-        <li> <p>
-            A report on the
-           <a href="reports/codimension-one/desimone-heltai-manigrasso.pdf"
-               target="body">codimension one</a> capabilities
-           of the library (by Antonio DeSimone, Luca Heltai
-           and Cataldo Manigrasso, SISSA, Trieste, Italy). It
-            explains in detail how to use the
-           library for the solution of problems defined on codimension
-           one manifolds, such as, for example, Boundary Element Methods.
-      </ul>
-
-
-    <h3><a name="publications">Publications</a></h3>
+<body>
+
+<h1>Online documentation</h1>
+
+<div class="toc">
+  <ol>
+    <li> <a href="#readme.html">ReadMe</a></li>
+    <li> <a href="#tutorials">Tutorials</a></li>
+    <li> <a href="#API">Programming interface</a></li>
+    <li> <a href="#dev">Development information</a></li>
+    <li> <a href="#reports">Reports</a></li>
+    <li> <a href="#publications">Publications</a></li>
+    <li> <a href="#license">Copyright and licence</a></li>
+  </ol>
+</div>
+
+<p>
+  <acronym>deal.II</acronym> comes with quite extensive online
+  documentation, which falls into several categories. They are
+  listed below.
+</p>
+
+<h2><a href="readme.html">ReadMe</a></h2>
+
+<p>
+  First, there is the <a href="readme.html" target="body">README file</a> of
+  the library. It gives information on system requirements,
+  installation, and copyright.
+</p>
+
+<h2><a href="tutorials">Tutorials</a></h2>
+
+<p>
+  The <a href="doxygen/tutorial/index.html"
+        target="_top">tutorial</a> is
+  for new users of the library. It explains the basic elements of
+  finite element programs based on the library, and provides small
+  example programs. You can also reach the tutorial link from the menu bar
+  at the left.
+</p>
+
+<p>
+  Note that along with the rest of the documentation, the local HTML pages
+  of the tutorials need to be generated first. Please follow the
+  instructions in the
+  <a href="readme.html" target="body">ReadMe file</a> on how to do
+  this.
+</p>
+
+
+<h2><a href="API">Programming interface</a></h2>
+
+<p>
+  The <a href="doxygen/deal.II/index.html" target="_top">programming
+    interface/manual</a> pages are what you will need most often as a
+  reference of all classes, functions and variables in the library. They
+  are extensively documented (presently more than 5000 pages if
+  printed), and generated by <a href="http://www.doxygen.org/"
+                               target="_top">Doxygen</a>. There is also a quick link to these pages from
+  the menu bar at the left.
+</p>
+
+<p>
+  The documentation uses many of the features of Doxygen. In particular,
+  the link takes you straight to a page that lists <i>modules</i>, a way
+  to group classes with similar purposes. This may be what you are probably
+  interested in when you are not yet familiar with the library. If you
+  already know your way around and want to look up the signature of a
+  particular member function, for example, you may go to the class view or
+  choose any of the other ways in which Doxygen allows you to navigate
+  through the documentation.
+</p>
+
+<p>
+  Just as for the tutorials, the API docs need to be generated first,
+  if you download <acronym>deal.II</acronym>. Please follow the
+  instructions in the
+  <a href="readme.html" target="body">ReadMe file</a> on how to do
+  this.
+</p>
+
+
+<h2><a name="dev">Development information</a></h2>
+
+<p>
+  If you plan to <a href="development/index.html"
+                   target="_top">develop your own applications</a> using
+  <acronym>deal.II</acronym>, it might be worth to take a look
+  at <a href="development/index.html" target="_top">this
+    page</a>.
+</p>
+
+
+<h2><a name="reports">Reports</a></h2>
+
+<p>
+  There are a number of papers that describe the overall design or
+  individual aspects of <acronym>deal.II</acronym>. Please refer to the
+  papers listed at the top of the <a href="publications/index.html"
+                                    target="body">publications page</a> for full references. In addition,
+  there are the following reports:
+  <ul>
+    <li>
+      <p>
+       A publication on the
+       <a href="reports/dimension-independent/index.html"
+           target="body">basics of dimension independent
+          programming</a> in <acronym>deal.II</acronym> (by Wolfgang
+       Bangerth). This explains some of the fundamentals of the
+       library's design, though rather briefly due to the page
+       limit imposed for the publication.
+      </p>
+      
+      <p>
+       This publication appeared in
+       the proceedings of the 16th IMACS World Congress,
+       Lausanne, Switzerland, 2000. See the
+       <a href="publications/index.html" target="body">publications</a>
+       page for the full reference as well as a way to obtain a
+       reprint of the original paper as a postscript or PDF file.
+      </p>
+    </li>
+    
+    <li>
+      A brief report about the classes involved in the
+      <a href="reports/class-hierarchies/index.html"
+         target="body">iterators and accessors</a>
+      used to access cells in the triangulations and the data
+      thereon, such as their geometry, the number of the
+      degrees of freedom, data values, etc. You may want to
+      read this object or parts of it if you want to know what
+      information is available from iterators (by Wolfgang
+      Bangerth).
+    </li>
+    
+    <li>
+      A brief report on <a href="reports/mapping_q/index.html"
+                          target="body">mapping</a> functions of higher polynomial
+      degrees (by Ralf Hartmann). These allow the realisation
+      of higher order boundary approximations. This report
+      gives the theoretical background of the
+      <code>MappingQ</code> class.
+    </li>
+
+    <li>
+      A report on
+      <a href="reports/assemble/assemble.pdf"
+         target="body">assembling matrices</a> (by Wolfgang
+      Bangerth). This report looks in particular at how
+      matrices are assembled for vector-valued problems, and
+      how things change if vector-valued finite elements are
+      used for which the shape functions have more than one
+      non-zero vector component, such as Nedelec or
+      Raviart-Thomas elements. There are printable
+      versions of the report
+      <a href="reports/assemble/assemble.ps"
+         target="body">in postscript</a> and
+      <a href="reports/assemble/assemble.pdf"
+         target="body">PDF format</a>.
+    </li>
+    
+    <li>
+      A very detailed report on
+      <a href="reports/nedelec/nedelec.pdf"
+         target="body">Nedelec elements</a> (by Anna
+      Schneebeli, University of Basel, Switzerland). It
+      explains the construction and application of Nedelec
+      edge elements for H-curl spaces, as used, for example,
+      in the numerical solution of the Maxwell equations. It
+      also gives numerical results obtained with deal.II.
+      There is also a <a href="reports/nedelec/nedelec.ps"
+                        target="body">postscript version of the report</a>.
+    </li>
+    
+    <li>
+      A report on the
+      <a href="reports/codimension-one/desimone-heltai-manigrasso.pdf"
+         target="body">codimension one</a> capabilities of the library
+         (by Antonio DeSimone, Luca Heltai and Cataldo Manigrasso,
+         SISSA, Trieste, Italy). It explains in detail how to use the
+         library for the solution of problems defined on codimension
+         one manifolds, such as, for example, Boundary Element
+         Methods.
+      </li>
+  </ul>
+
+
+    <h2><a name="publications">Publications</a></h2>
 
     <p>
       A <a href="publications/index.html" target="body">list of
       <acronym>deal.II</acronym> can be found on
       <a href="publications/index.html" target="body">this</a> page.
     </p>
-
-
-    <h3><a name="license">Copyright and License</a></h3>
-
-    <p> <acronym>deal.II</acronym> is copyright of the
-      <a href="authors.html" target="body">deal.II authors</a>.
-      It is a joint effort of the current maintainers, Wolfgang
-      Bangerth, Timo Heister, Guido Kanschat, and quite a number of
-      contributors.  <acronym>deal.II</acronym> is distributed under an
+    
+    
+    <h2><a name="license">Copyright and License</a></h2>
+    
+    <p>
+      <acronym>deal.II</acronym> is copyright of the
+      <a href="authors.html" target="body">deal.II authors</a>.  It is
+      a joint effort of the current maintainers, Wolfgang Bangerth,
+      Timo Heister, Guido Kanschat, and quite a number of
+      contributors.  <acronym>deal.II</acronym> is distributed under
+      an
       <a href="http://www.opensource.org" target="_top">OpenSource</a>
       license. The full text of the license can be found in
       <a href="license.html"><tt>license.html</tt></a>.
     </p>
 
-    <h3>Contact</h3>
+    <h2>Contact</h2>
 
     <p>We have a <a href="mail.html">discussion group</a> for discussion
       of issues of general interest to users and developers of
       <acronym>deal.II</acronym>.</p>
-
+    
     <p>More specific questions may be sent to the authors
       immediately at the address <tt>firstName.lastname</tt><i> at
       </i> <tt>dealii.org</tt>.</p>
                                                                 alt="Valid HTML 4.01!" height="31" width="88"></a>
       </p>
     </div>
-  </body>
+</body>
 </html>
index b08a508c308c7455df6e5ae4953f6c98d032d18b..d9e5f3927f7c2f692f6cd059cb61d1119129ff22 100644 (file)
     </h2>
 
 
-    <h1>Installation instructions and further information
-      on <acronym>deal.II</acronym> </h1>
-
-    <table class="tutorial" width="60%">
-      <tr><th colspan="2"><b><small>Table of contents</small></b></th></tr>
-      <tr><td valign="top">
-         <ul>
-           <li> <a href="#prerequisites">System requirements</a>
-             <ul>
-               <li> <a href="#supported">Supported platforms</a>
-               <li> <a href="#additional-software">Additional software requirements</a>
-             </ul>
-           <li> <a href="#installation">Installation</a>
-             <ul>
-               <li>  <a href="#unpacking">Unpacking</a>
-               <li>  <a href="#configuration">Configuring and building the library</a>
-               <li>  <a href="#documentation">Configuring and building the documentation</a>
-               <li>  <a href="#configuration-options">Configuration options</a>
-                 <ul>
-                   <li> <a href="#optional">Selecting optional behavior</a>
-                   <li> <a href="#optional-software">Optional interfaces to
-                       other software packages</a>
-                   <li> <a href="#conf-details">More information on configuring
-                       and building the library</a>
-                 </ul>
-             </ul>
-           <li> <a href="#problems">Problems, questions, mailing lists</a>
-           <li> <a href="#license">License</a>
-         </ul>
-       </td>
-      </tr>
-    </table>
-
+<h1>Installation instructions and further information
+  on <acronym>deal.II</acronym> </h1>
+
+<div class="toc">
+  <ol>
+    <li> <a href="#prerequisites">System requirements</a>
+      <ol>
+       <li> <a href="#supported">Supported platforms</a>
+       <li> <a href="#additional-software">Additional software requirements</a>
+      </ol>
+    <li> <a href="#installation">Installation</a>
+      <ol>
+       <li>  <a href="#unpacking">Unpacking</a>
+       <li>  <a href="#configuration">Configuring and building the library</a>
+       <li>  <a href="#documentation">Configuring and building the documentation</a>
+       <li>  <a href="#configuration-options">Configuration options</a>
+         <ol>
+           <li> <a href="#optional">Selecting optional behavior</a>
+           <li> <a href="#optional-software">Optional interfaces to
+               other software packages</a>
+           <li> <a href="#conf-details">More information on configuring
+               and building the library</a>
+         </ol>
+      </ol>
+    <li> <a href="#problems">Problems, questions, mailing lists</a>
+    <li> <a href="#license">License</a>
+  </ol>
+</div>
 
     <a name="prerequisites"></a>
     <h2>System requirements</h2>

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.