From: Matthias Maier <tamiko@43-1.org>
Date: Sat, 16 Jun 2018 03:49:07 +0000 (-0500)
Subject: update documentation
X-Git-Tag: v9.1.0-rc1~1022^2~2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=844d880ee97c51285dc1829fdc03654b7fee25eb;p=dealii.git

update documentation
---

diff --git a/contrib/utilities/indent b/contrib/utilities/indent
index 54e2ced7b6..afa726ce42 100755
--- a/contrib/utilities/indent
+++ b/contrib/utilities/indent
@@ -15,20 +15,27 @@
 ## ---------------------------------------------------------------------
 
 #
-# This script indents all source files of deal.II according to our
-# usual code formatting standards. It is used to ensure that our
-# code base looks uniform, as uniformity helps make code easier to
-# read.
+# This script indents all source files of deal.II according to our usual
+# code formatting standards. It is used to ensure that our code base looks
+# uniform, as uniformity helps make code easier to read.
 #
 # While we're already touching every file, this script also makes
-# sure we set permissions correctly
+# sure we set permissions correctly and checks for correct unix-style line
+# endings.
 #
 # The script needs to be executed as
-#   ./contrib/utilities/indent
+#   $ ./contrib/utilities/indent
 # from the top-level directory of the source tree, or via
-#   make indent
+#   $ make indent
 # from a build directory.
 #
+# Note: If the script is invoked with REPORT_ONLY=true set,
+#   $ REPORT_ONLY=true ./contrib/utilities/indent
+# or,
+#   $ make REPORT_ONLY=true indent
+# then indentation errors will only be reported without any actual file
+# changes.
+#
 
 if [ ! -f contrib/utilities/indent_common.sh ]; then
   echo "*** This script must be run from the top-level directory of deal.II."
diff --git a/contrib/utilities/indent-branch b/contrib/utilities/indent-branch
index 46f1412d58..e2bed13546 100755
--- a/contrib/utilities/indent-branch
+++ b/contrib/utilities/indent-branch
@@ -17,13 +17,21 @@
 #
 # This script does the same thing as contrib/utilities/indent but only
 # reformats files which have changed (or have been added but neither
-# staged/commited) since the last merge commit to the master branch. It
-# should be run as
-#
-#    make indent-branch
+# staged/commited) since the last merge commit to the master branch.
 #
+# The script needs to be executed as
+#   $ ./contrib/utilities/indent-branch
+# from the top-level directory of the source tree, or via
+#   $ make indent-branch
 # from a build directory.
 #
+# Note: If the script is invoked with REPORT_ONLY=true set,
+#   $ REPORT_ONLY=true ./contrib/utilities/indent-branch
+# or,
+#   $ make REPORT_ONLY=true indent-branch
+# then indentation errors will only be reported without any actual file
+# changes.
+#
 
 if [ ! -f contrib/utilities/indent_common.sh ]; then
   echo "*** This script must be run from the top-level directory of deal.II."
diff --git a/doc/doxygen/headers/coding_conventions.h b/doc/doxygen/headers/coding_conventions.h
index 7cecc12ab0..2cedd9cd3b 100644
--- a/doc/doxygen/headers/coding_conventions.h
+++ b/doc/doxygen/headers/coding_conventions.h
@@ -50,14 +50,16 @@ on each of your files. This will make sure indentation is conforming to the
 style guidelines outlined in this page. Alternatively, you can run
 <code>
 <pre>
-  make indent
+  make indent-branch
 </pre>
 </code>
 in whatever directory you set up the library to be compiled in to indent all
-source files. If you want to make sure that the indenting is correct for all
-your commits, you might want to set up a pre-commit hook. One way to do so,
-is to copy ${SOURCE_DIR}/contrib/scripts/pre-commit-clang-format to
-${SOURCE_DIR}/.git/hooks/pre-commit and make sure it is executable.
+source files that have been changed recently. If you want to make sure that
+the indenting is correct for all your commits, you might want to set up a
+pre-commit hook. One way to do so, is to copy
+<code>${SOURCE_DIR}/contrib/scripts/pre-commit-clang-format</code> to
+<code>${SOURCE_DIR}/.git/hooks/pre-commit</code> and make sure it is
+executable.
 </p>
 
 <h3>Style issues</h3>
@@ -67,8 +69,8 @@ ${SOURCE_DIR}/.git/hooks/pre-commit and make sure it is executable.
   degrees of freedom, etc) should start with <code>n_*</code>. Example:
   SparsityPattern::n_nonzero_entries().</li>
 
-<li> %Function which set a bit or flag should start with <code>set_*</code>;
-  functions which clear bits of flags should be named <code>clear_*</code>.
+<li> %Functions which set a bit or flag should start with <code>set_*</code>;
+  functions which clear bits or flags should be named <code>clear_*</code>.
   Example: CellIterator::set_refine_flag().</li>
 
 <li> Traditional logical operators should be used instead of their English