From 4fa8abb31572b587764b0167164ac95c89f8ea8f Mon Sep 17 00:00:00 2001
From: Wolfgang Bangerth <bangerth@math.tamu.edu>
Date: Thu, 4 Apr 2002 08:30:37 +0000
Subject: [PATCH] General updates, and minor things.

git-svn-id: https://svn.dealii.org/trunk@5636 0785d39b-7218-0410-832d-ea1e28bc413d
---
 deal.II/doc/platforms/ibm_aix_xlc.html |   2 +-
 deal.II/doc/publications/toc.html      |   4 +-
 deal.II/doc/readme.html                | 186 +++++++++++++++----------
 3 files changed, 112 insertions(+), 80 deletions(-)

diff --git a/deal.II/doc/platforms/ibm_aix_xlc.html b/deal.II/doc/platforms/ibm_aix_xlc.html
index 86df550d37..4514695723 100644
--- a/deal.II/doc/platforms/ibm_aix_xlc.html
+++ b/deal.II/doc/platforms/ibm_aix_xlc.html
@@ -125,7 +125,7 @@
     </p>
 
     <p>
-    At this point, I gave up. In summary, there may have only be half
+    At this point, I gave up. In summary, there may have only been half
     a dozen bugs in the compiler that were triggered several hundred
     times, but as long as these are not fixed in the compiler itself,
     I see no way to use xlC for deal.II. Nevertheless, as gcc also
diff --git a/deal.II/doc/publications/toc.html b/deal.II/doc/publications/toc.html
index f9e03d0703..eea15976fb 100644
--- a/deal.II/doc/publications/toc.html
+++ b/deal.II/doc/publications/toc.html
@@ -72,7 +72,7 @@
          Methods for the Compressible Euler Equations
          </strong>
          <br>
-         Preprint 2001-42 (SFB 359), IWR Heidelberg, Dez 2001.<br>
+         Preprint 2001-42 (SFB 359), IWR Heidelberg, Dec 2001.<br>
 	 Submitted for publication 2001.
 	 <br>
 	 (<a href="2001/hh-2.html" target="body">Abstract</a>)
@@ -85,7 +85,7 @@
          Compressible Fluid Flows
          </strong>
          <br>
-	 Proceedings of ENUMATH, 2001.
+	 Proceedings of ENUMATH 2001.
 	 <br>
 	 Submitted for publication 2001.
 	 <br>
diff --git a/deal.II/doc/readme.html b/deal.II/doc/readme.html
index 276a12b389..d0d74132c8 100644
--- a/deal.II/doc/readme.html
+++ b/deal.II/doc/readme.html
@@ -36,9 +36,9 @@
     developed and tested on Unix or Unix-like systems only. It can be
     used positively on
     <ul>
-      <li>Linux ELF on i386 with gcc 2.95.x, gcc 3.0.x and Intel ICC;
+      <li>Linux ELF on i386 with gcc 2.95.x, gcc 3.x and Intel ICC;
       <li>Sun Solaris 2.5, 2.6, and 7 on Sparc, with gcc 2.95.x
-          and gcc 3.0.x; 
+          and gcc 3.x; 
       <li>Sun Solaris 8 on i386, with gcc 2.95.x;
       <li>IBM AIX 4.2, with gcc 2.95.x (with some restrictions on
           the use of shared libraries).
@@ -80,10 +80,10 @@
     libraries you need to have the following programs installed:
     <ul>
       <li> <p>
-           A fairly complete C++ compiler. We use 
+           A fairly complete C++ compiler. We usually use 
            <a href="http://gcc.gnu.org" target="_top">gcc2.95 or
-           gcc3.0</a> but other compilers might work as well. 
-	   DEC's/Compaq's cxx compiler also works. egcs1.x 
+           gcc3.x</a> but also some others. Various working compilers
+           are listed above. egcs1.x 
 	   and older gcc versions will not work, however. Also, Sun
            Workshop C++ 5.0 will not work since it does not support
            template member functions, and IBM C Set++ 3.0 will not
@@ -91,18 +91,18 @@
            appended .h. Version 5.0 does not work since they do not
            allow the declaration of explicit specializations and a
            larger number of other techniques that are used in the
-           library. 
+           library, see the link in the list above. 
 	   </p>
 
 	   <p>
 	   Note that we have supported egcs 1.1.x in previous releases
-           of the library (up to <acronym>deal.II</acronym> 3.0.x), but
-           due to some missing feature in the support of Standard C++,
-           we now only support later versions of gcc for releases of
-           <acronym>deal.II</acronym> after version 3.0.x. Beyond
-           that, we frequently test to compile
-           <acronym>deal.II</acronym> with newer gcc snapshots, so we
-           expect it to work with the upcoming release of gcc 3.0.
+           of the library (up to <acronym>deal.II</acronym> 3.0.x),
+           but due to some missing feature in the support of Standard
+           C++, we now only support later versions of gcc for releases
+           of <acronym>deal.II</acronym> after version 3.0.x. Beyond
+           that, we frequently compile <acronym>deal.II</acronym> with
+           newer gcc snapshots, to ensure that the library will
+           compile with upcoming releases.
 	   </p>
 
 	   <p>
@@ -115,16 +115,19 @@
            Perl: any Perl 5.x version should work.
 	   </p>
 
-      <li> <p>
-           Make: we use <a href="http://www.gnu.org" target="_top">GNU make</a>,
-           version 3.75. We also use GNU make 3.78 which has much
-           better support for parallel builds, so you may want to
-           consider this version if you have a multiprocessor
+      <li> <p> 
+           Make: we use <a href="http://www.gnu.org"
+           target="_top">GNU make</a>, version 3.78 or 3.79 which also
+           has rather good support for parallel builds, so you may
+           want to consider this version if you have a multiprocessor
            system. GNU make 3.77 had a serious flaw in the
            <code>$(wildcard ...)</code> function which prevented us
            from compiling some parts of the library (most of our
-           Makefiles use a workaround, though). Other make programs
-           (i.e. non-GNU) will fail to work.
+           Makefiles use a workaround, though). Older GNU make
+           versions are likely to work, but since they are hardly
+           installed on systems today, we don't regularly test
+           this. Other make programs (i.e. non-GNU) will usually fail
+           to work.
 	   </p>
 
       <li> <p>
@@ -155,7 +158,7 @@
 
       <li> <p>
            The library generates output in formats readable by
-           GNUPLOT, 
+           <a href="http://www.ucc.ie/gnuplot/gnuplot-faq.html" target="_top">GNUPLOT</a>, 
 	   <a href="http://www-xdiv.lanl.gov/XCM/gmv/" target="_top">GMV
  	                              (general mesh viewer)</a>, 
 	   <a href="http://www.amtec.com" target="_top">Tecplot</a> (ASCII and binary), 
@@ -184,7 +187,11 @@
     base/source/data_out_base.cc to see how output formats are
     implemented), as only a simple intermediate format needs to be
     converted into a graphics format, without references to cells,
-    nodes, types of finite elements, and the like.
+    nodes, types of finite elements, and the like. Since your
+    preferred output format is likely to be similar to one for which
+    we already have a backend, adaptation is usually simple. In case
+    you write such a function, we would be happy to integrate it into
+    the library.
     </p>
 
 
@@ -192,6 +199,7 @@
     <a name="installation">
     <h2>Installation</h2>
 
+    <p>
     The whole library usually comes as a .tar.gz file, that is a
     tarred file archive which is compressed with gzip. After unpacking
     it with gunzip and tar (or <tt>tar xzf</tt> if you use GNU tar), you will
@@ -202,11 +210,12 @@
     which sets some paths and finds out what compiler you
     use. ./configure supports several flags which are discussed
     further down <a href="#configuration-options">below</a>. 
+    </p>
 
     <p>
-
     The most important result of <code>./configure</code> is the
-    creation of the file <code>common/Make.global_options</code>. This
+    creation of the files <code>common/Make.global_options</code> and
+    <code>base/include/base/config.h</code>. The first
     file contains compiler options, paths, etc which you may want to
     use in the <a href="development/index.html" target="_top">Makefiles
     of your own projects</a>. It is definitely a good
@@ -216,35 +225,41 @@
     out about the supported flags, take a look at the file. Also,
     information about Makefiles can be found in the section on
     <a href="development/index.html" target="_top">development</a>.
+    </p>
 
     <p>
+    The second generated file contains a number of preprocessor
+    definitions, that are mostly used to indicate the features and
+    bugs of the compiler in use.
+    </p>
 
+    <p>
     After configuring, type `make', to obtain the following help (this
-    output may change slightly over time, just try it):
+    output may change slightly over time, just try it): 
 
     <pre><code>
-    ======================================================================
-    =Global Makefile for the deal.II libraries                           =
-    ======================================================================
-    =Possible Targets                                                    =
-    =  baseg lacg: debug libraries base and lac                          =
-    =  base lac: debug and optimized libraries base and lac              =
-    =  1dg 2dg 3dg: (1) and deal.II debug version for specified dimension=
-    =  1d 2d 3d: (2) and deal.II for specified dimension                 =
-    =  contrib: make additional libraries in contrib, if there are any   =
-    =  all: base, lac, 1d, 2d and 3d, contrib                            =
-    =  debug: baseg, lacg, 1dg, 2dg and 3dg, contrib                     =
-    =  online-doc: generate the documentation in HTML format             =
-    =  TODO: create a TODO file from TODO lines in the source files      =
-    =  TAGS: create a TAGS file from include and source files            =
-    =  clean: removes all object files, libraries, etc in all subdirs    =
-    =                                                                    =
-    =The following additional parameters may be specified to make:       =
-    =  PAR=-jn where n is the number of parallel processes for parallel  =
-    =          builds. If you use GNU make 3.78 or higher, you can       =
-    =          call 'make -jn' directly. This parameter is no more       =
-    =          necessary then.                                           =
-    ======================================================================
+    ========================================================================
+    =              Global Makefile for the deal.II libraries               =
+    ========================================================================
+    =                                                                      =
+    = The following targets exist:                                         =
+    =    baseg lacg : debug libraries "base" and "lac"                     =
+    =    base lac   : debug and optimized libraries "base" and "lac"       =
+    =    1dg 2dg 3dg: deal.II debug version for specified dimension        =
+    =    1d 2d 3d   : deal.II debug and optimized for specified dimension  =
+    =                                                                      =
+    =    contrib    : additional libraries in contrib, if there are any    =
+    =                                                                      =
+    =    all        : base, lac, 1d, 2d and 3d, contrib                    =
+    =    debug      : baseg, lacg, 1dg, 2dg and 3dg, contrib               =
+    =    optimized  : base, lac, 1d, 2d, and 3d optimized libraries only   =
+    =                                                                      =
+    =    online-doc : generate the documentation in HTML format            =
+    =    TODO       : create a "TODO" file from the source files           =
+    =    TAGS       : create a TAGS file from include and source files     =
+    =                                                                      =
+    =    clean      : removes all object files, libraries, etc in subdirs  =
+    ========================================================================
     </code></pre>
 
     <p>
@@ -258,16 +273,15 @@
     </p>
 
     <p>
-    In case you have a multi-processor machine, you can call `make
-    PAR=-j4 target-name' to let `make' call multiple instances of the
-    compiler (in this case four). Since the make files are written in
-    a way to minimize cross-dependencies, this speeds up compilation
-    by about the factor given after `-j', at least if you have as many
-    processors. If you have GNU make 3.78 or higher, it is simpler to
-    directly call `make -j4 target-name'. Note, however, that
-    parallel makes will sometimes fail when compiling the library for
-    the first time (this is due to a bug in `make'); in that case,
-    simply re-run `make', or run it without `-jN'.
+    In case you have a multi-processor machine, you can call `make -j4
+    target-name' to let `make' call multiple instances of the compiler
+    (in this case four). Since the make files are written in a way to
+    minimize cross-dependencies, this speeds up compilation by about
+    the factor given after `-j', at least if you have as many
+    processors. Note, however, that parallel makes will sometimes fail
+    when compiling the library for the first time (this is due to a
+    bug in `make'); in that case, simply re-run `make', or run it
+    without `-jN'.
     </p>
 
     <p>
@@ -361,8 +375,11 @@
     Heidelberg. You can access all documentation through <a
     href="documentation.html" target="body">this page</a>. (For
     obvious reasons, the only document that you don't have locally is
-    the News page, and the pages that convert the CVS logs into
-    HTML. Access them through the 
+    the News page, and a few of the pages in the "Development"
+    section, as they are re-generated nightly and carry the present
+    development status of the library, rather than the status of the
+    particular version of the library you have on your harddisk.
+    You can access these pages through the 
     <a href="http://www.dealii.org" target="_top">global 
     homepage</a>.)
     </p>
@@ -392,6 +409,16 @@
       ./configure
     </pre>
 
+    <p>
+    The paths to these compilers are stored in the
+    <code>common/Make.global_options</code> files, so the compilers
+    are always used when compiling the library even if the environment
+    variables are no more set later (for example if you are working
+    within another window, or have unset the variables for other
+    purposes).
+    </p>
+
+
     <h4>Selecting optional behavior</h4>
     You can give several flags to ./configure:
     <ul>
@@ -403,13 +430,14 @@
       start-up time, so this is the default. However, some systems
       might not support shared libraries, in which case you should
       call ./configure with the parameter
-      <code>--disable-shared</code>. (Since on AIX we could not get
-      shared libraries right immediately, they are disabled by default
-      on this system. The same applies to DEC Alpha stations running
-      Linux and OSF1, and CygWin Windows systems. Probably, there is a
-      simple work-around, but since we can't regularly test there, we
-      did not try very hard. If anyone would like to look into this,
-      we would be pleased to offer advice.)
+      <code>--disable-shared</code>. (They are disabled by default on
+      those systems for which we could not make them work. This
+      applies to AIX, DEC Alpha stations running Linux and OSF1,
+      CygWin Windows systems, and some other systems as
+      well. Probably, there are simple solutions, but since we can't
+      regularly test on these systems, we did not try very hard. If
+      anyone would like to look into this, we would be pleased to
+      offer advice.)
       </p>
 
       <p>
@@ -499,7 +527,6 @@
     </ul>
 
     <p>
-
     Please note that running ./configure stores the paths to some
     programs, such as the compilers or the Perl interpreter. The
     compiler which will be used when compiling the library (or your
@@ -512,18 +539,18 @@
     storing the absolute paths of compilers, we can at least catch
     those problems where different compiler revisions are located in
     different directories.
+    </p>
 
     <p>
-
     If you want to use a new compiler version, you will therefore have
     to re-run ./configure with the new compiler being in the $PATH
     environment variable.
+    </p>
 
     <p>
-
     It is in general a good idea to run `make clean'
     before re-configuring.
-
+    </p>
 
 
     <a name="compiler-flags">
@@ -570,7 +597,11 @@
 
     <p>
     We would like to hear about necessary or useful modifications so
-    that we can include them into the distribution.
+    that we can include them into the distribution. If you feel that
+    certain flags should be included always (for example because this
+    results in significantly better optimizations), then it might be
+    interesting to modify the <code>aclocal.m4</code> file in the
+    top-level directory and send us your changes.
     </p>
 
 
@@ -619,6 +650,7 @@
     <a name="problems">
     <h2>Problems, questions, mailing lists</h2>
 
+    <p>
     Some information beyond what is covered in the documentation of
     the library may be found on the
     <a href="http://www.dealii.org" target="_top">homepage of
@@ -632,9 +664,9 @@
     and of which
     <a href="http://www.dealii.org/mail/maillist.html" target="body">
     previous mails</a> are also archived online.
+    </p>
 
-    <p>
-    
+    <p>    
     You can <B>subscribe</B> to this list by writing email to <a
     href="mailto:list-server@dealii.org"><b>list-server</b>@<b>dealii.org</b></a>
     with the text (not in the subject!)
@@ -647,24 +679,24 @@
     </pre>
     The list server also understands the command <TT>help</TT> given
     on a line by itself.
+    </p>
   
     <p>
-
     For specific problems, send email to either <a
     href="mailto:wolfgang.bangerth@dealii.org">Wolfgang
     Bangerth</a>, <a
     href="mailto:ralf.hartmann@dealii.org">Ralf
     Hartmann</a> or <a
     href="mailto:kanschat@dealii.org">Guido Kanschat</a>.
+    </p>
 
     <p>
-
     We are interested in any feedback, whether positive or negative,
     in order to determine the directions of future work on the
     library. We are also very much interested in incorporating any
     work and bug fixes by third parties into the library. Of course,
     you will be credited for this on our home page.
-
+    </p>
 
 
     <a name="license">
@@ -684,7 +716,7 @@
     The basics of the license are in short:
     <ul>
       <li>
-        The library comes free of charge for all users, but
+         The library comes free of charge for all users, but
          we keep a copyright in it. We will grant everyone access to
          the library and its source code, provided they keep to the
          <a href="license.html" target="body">license</a>.
-- 
2.39.5