docs: cleanup (#1041)

README.rst

@@ -46,8 +46,8 @@ their usage, please refer to the `user guide <#user-guide>`__.
 .. pull-quote::
    [!IMPORTANT]
 
-   The above example requires further Bazel or CMake setup for
-   `use in own projects <#usage-in-projects>`__.
+   The above example requires further `Bazel <#bazel>`__ or
+   `CMake <#usage-in-projects>`__ setup for use in own projects.
 
 
 .. contents:: Table of Contents
@@ -221,32 +221,72 @@ Severity Levels
 ~~~~~~~~~~~~~~~
 
 You can specify one of the following severity levels (in increasing
-order of severity): ``INFO``, ``WARNING``, ``ERROR``, and ``FATAL``.
+order of severity):
+
+1. ``INFO``,
+2. ``WARNING``,
+3. ``ERROR``, and
+4. ``FATAL``.
+
 Logging a ``FATAL`` message terminates the program (after the message is
-logged). Note that messages of a given severity are logged not only in
-the logfile for that severity, but also in all logfiles of lower
-severity. E.g., a message of severity ``FATAL`` will be logged to the
-logfiles of severity ``FATAL``, ``ERROR``, ``WARNING``, and ``INFO``.
+logged).
+
+.. pull-quote::
+   [!NOTE]
+
+   Messages of a given severity are logged not only to corresponding severity
+   logfile but also to other logfiles of lower severity. For instance, a message
+   of severity ``FATAL`` will be logged to logfiles of severity ``FATAL``,
+   ``ERROR``, ``WARNING``, and ``INFO``.
 
 The ``DFATAL`` severity logs a ``FATAL`` error in debug mode (i.e.,
 there is no ``NDEBUG`` macro defined), but avoids halting the program in
 production by automatically reducing the severity to ``ERROR``.
 
-Unless otherwise specified, glog writes to the filename
-``/tmp/\<program name\>.\<hostname\>.\<user name\>.log.\<severity level\>.\<date\>-\<time\>.\<pid\>``
-(e.g.,
-``/tmp/hello_world.example.com.hamaji.log.INFO.20080709-222411.10474``).
-By default, glog copies the log messages of severity level ``ERROR`` or
-``FATAL`` to standard error (``stderr``) in addition to log files.
+Unless otherwise specified, glog uses the format
+
+::
+
+    <tmp>/<program name>.<hostname>.<user name>.log.<severity level>.<date>-<time>.<pid>
+
+for log filenames written to a directory designated as ``<tmp>`` and determined
+according to the following rules.
+
+**Windows**
+    glog uses the
+    `GetTempPathA <https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-gettemppatha>`__
+    API function to retrieve the directory for temporary files with a fallback to
+
+    1. ``C:\TMP\``
+    2. ``C:\TEMP\``
+
+    (in the order given.)
+
+**non-Windows**
+    The directory is determined by referencing the environment variables
+
+    1. ``TMPDIR``
+    2. ``TMP``
+
+    if set with a fallback to ``/tmp/``.
+
+The default path to a log file on Linux, for instance, could be
+
+::
+
+    /tmp/hello_world.example.com.hamaji.log.INFO.20080709-222411.10474
+
+By default, glog echos ``ERROR`` and ``FATAL`` messages to standard error in
+addition to log files.
 
 Setting Flags
 ~~~~~~~~~~~~~
 
 Several flags influence glog’s output behavior. If the `Google gflags library
 <https://github.com/gflags/gflags>`__ is installed on your machine, the build
 system will automatically detect and use it, allowing you to pass flags on the
-command line. For example, if you want to turn the flag :cmd:`--logtostderr` on,
-you can start your application with the following command line:
+command line. For example, if you want to activate :cmd:`--logtostderr`, you can
+start your application with the following command line:
 
 .. code:: bash
 
@@ -262,10 +302,14 @@ environment variables, prefixing the flag name with ``GLOG_``, e.g.,
 The following flags are most commonly used:
 
 ``logtostderr`` (``bool``, default=\ ``false``)
-   Log messages to ``stderr`` instead of logfiles. Note: you can set
-   binary flags to ``true`` by specifying ``1``, ``true``, or ``yes``
-   (case insensitive). Also, you can set binary flags to ``false`` by
-   specifying ``0``, ``false``, or ``no`` (again, case insensitive).
+   Log messages to ``stderr`` instead of logfiles.
+
+   .. pull-quote::
+      [!TIP]
+
+      You can set boolean flags to :cpp:`true` by specifying ``1``, :cpp:`true`,
+      or ``yes``. To set boolean flags to :cpp:`false`, specify ``0``,
+      ``false``, or ``no``. In either case the spelling is case-insensitive.
 
 ``stderrthreshold`` (``int``, default=2, which is ``ERROR``)
    Copy log messages at or above this level to stderr in addition to
@@ -282,20 +326,20 @@ The following flags are most commonly used:
    default logging directory.
 
 ``v`` (``int``, default=0)
-   Show all ``VLOG(m)`` messages for ``m`` less or equal the value of
-   this flag. Overridable by :cmd:`--vmodule`. See `the section about
-   verbose logging <#verbose-logging>`__ for more detail.
+   Show all ``VLOG(m)`` messages for ``m`` less or equal the value of this flag.
+   Overridable by :cmd:`--vmodule`. Refer to `verbose logging <#verbose-logging>`__
+   for more detail.
 
 ``vmodule`` (``string``, default="")
    Per-module verbose level. The argument has to contain a
-   comma-separated list of <module name>=<log level>. <module name> is a
+   comma-separated list of ``<module name>=<log level>``. ``<module name>`` is a
    glob pattern (e.g., ``gfs*`` for all modules whose name starts with
    "gfs"), matched against the filename base (that is, name ignoring
-   .cc/.h./-inl.h). <log level> overrides any value given by :cmd:`--v`.
-   See also `the section about verbose logging <#verbose-logging>`__.
+   .cc/.h./-inl.h). ``<log level>`` overrides any value given by :cmd:`--v`.
+   See also `verbose logging <#verbose-logging>`__ for more details.
 
-There are some other flags defined in logging.cc. Please grep the source
-code for ``DEFINE_`` to see a complete list of all flags.
+Additional flags are defined in `flags.cc <src/flags.cc>`__. Please see the
+source for their complete list.
 
 You can also modify flag values in your program by modifying global
 variables ``FLAGS_*`` . Most settings start working immediately after
@@ -335,8 +379,12 @@ logging is most useful for informational messages.
    LOG_EVERY_N(INFO, 10) << "Got the " << google::COUNTER << "th cookie";
 
 The above line outputs a log messages on the 1st, 11th, 21st, ... times
-it is executed. Note that the special ``google::COUNTER`` value is used
-to identify which repetition is happening.
+it is executed.
+
+.. pull-quote::
+   [!NOTE]
+
+   The placeholder ``google::COUNTER`` identifies the reccuring repetition.
 
 You can combine conditional and occasional logging with the following
 macro.
@@ -353,11 +401,11 @@ output to the first n occurrences:
 
    LOG_FIRST_N(INFO, 20) << "Got the " << google::COUNTER << "th cookie";
 
-Outputs log messages for the first 20 times it is executed. Again, the
+Outputs log messages for the first 20 times it is executed. The
 ``google::COUNTER`` identifier indicates which repetition is happening.
 
 Other times, it is desired to only log a message periodically based on a time.
-So for example, to log a message every 10ms:
+For instance, to log a message every 10ms:
 
 .. code:: cpp
 
@@ -450,21 +498,32 @@ constructor initializer lists.
        Something* ptr_;
    };
 
-Note that you cannot use this macro as a C++ stream due to this feature.
-Please use ``CHECK_EQ`` described above to log a custom message before
-aborting the application.
+
+.. pull-quote::
+   [!WARNING]
+
+   Due to the argument forwarding, ``CHECK_NOTNULL`` cannot be used to
+   simultaneously stream an additional custom message. To provide a custom
+   message, one can use the macro ``CHECK_EQ`` prior to the failing check.
 
 If you are comparing C strings (:cpp:`char *`), a handy set of macros performs
-case sensitive as well as case insensitive comparisons - ``CHECK_STREQ``,
-``CHECK_STRNE``, ``CHECK_STRCASEEQ``, and ``CHECK_STRCASENE``. The CASE versions
-are case-insensitive. You can safely pass :cpp:`nullptr` pointers for this macro. They
-treat :cpp:`nullptr` and any non-:cpp:`nullptr` string as not equal. Two :cpp:`nullptr`\
-s are equal.
+both case sensitive and insensitive comparisons - ``CHECK_STREQ``,
+``CHECK_STRNE``, ``CHECK_STRCASEEQ``, and ``CHECK_STRCASENE``. The
+``CHECK_*CASE*`` macro variants are case-insensitive. You can safely pass
+:cpp:`nullptr` pointers to this macro. They treat :cpp:`nullptr` and any
+non-:cpp:`nullptr` string as not equal. Two :cpp:`nullptr`\ s are equal.
+
+.. pull-quote::
+   [!NOTE]
+
+   Both arguments may be temporary objects which are destructed at the end of
+   the current "full expression", such as
 
-Note that both arguments may be temporary strings which are destructed
-at the end of the current "full expression" (e.g.,
-:cpp:`CHECK_STREQ(Foo().c_str(), Bar().c_str())` where ``Foo`` and ``Bar``
-return C++’s :cpp:`std::string`).
+   .. code:: cpp
+
+      CHECK_STREQ(Foo().c_str(), Bar().c_str());
+
+   where ``Foo`` and ``Bar`` return :cpp:`std::string`.
 
 The ``CHECK_DOUBLE_EQ`` macro checks the equality of two floating point
 values, accepting a small error margin. ``CHECK_NEAR`` accepts a third
@@ -486,12 +545,19 @@ controls which verbose messages are logged:
 
 With ``VLOG``, the lower the verbose level, the more likely messages are to be
 logged. For example, if :cmd:`--v==1`, ``VLOG(1)`` will log, but ``VLOG(2)``
-will not log. This is opposite of the severity level, where ``INFO`` is 0, and
-``ERROR`` is 2. :cmd:`--minloglevel` of 1 will log ``WARNING`` and above. Though
-you can specify any integers for both ``VLOG`` macro and :cmd:`--v` flag, the
-common values for them are small positive integers. For example, if you write
-``VLOG(0)``, you should specify :cmd:`--v=-1` or lower to silence it. This is
-less useful since we may not want verbose logs by default in most cases. The
+will not log.
+
+.. pull-quote::
+   [!CAUTION]
+
+   The ``VLOG`` behavior is opposite of the severity level logging, where
+   ``INFO``, ``ERROR``, etc. are defined in increasing order and thus
+   :cmd:`--minloglevel` of 1 will only log ``WARNING`` and above.
+
+Though you can specify any integers for both ``VLOG`` macro and :cmd:`--v` flag,
+the common values for them are small positive integers. For example, if you
+write ``VLOG(0)``, you should specify :cmd:`--v=-1` or lower to silence it. This
+is less useful since we may not want verbose logs by default in most cases. The
 ``VLOG`` macros always log at the ``INFO`` log level (when they log at all).
 
 Verbose logging can be controlled from the command line on a per-module
@@ -501,20 +567,21 @@ basis:
 
    --vmodule=mapreduce=2,file=1,gfs*=3 --v=0
 
-will:
+Specifying these options will specficially:
 
-(a) Print ``VLOG(2)`` and lower messages from mapreduce.{h,cc}
-(b) Print ``VLOG(1)`` and lower messages from file.{h,cc}
-(c) Print ``VLOG(3)`` and lower messages from files prefixed with "gfs"
-(d) Print ``VLOG(0)`` and lower messages from elsewhere
+1. Print ``VLOG(2)`` and lower messages from mapreduce.{h,cc}
+2. Print ``VLOG(1)`` and lower messages from file.{h,cc}
+3. Print ``VLOG(3)`` and lower messages from files prefixed with "gfs"
+4. Print ``VLOG(0)`` and lower messages from elsewhere
 
-The wildcarding functionality shown by (c) supports both ’*’ (matches 0
-or more characters) and ’?’ (matches any single character) wildcards.
-Please also check the section about `command line flags <#setting-flags>`__.
+The wildcarding functionality 3. supports both ``*`` (matches 0
+or more characters) and ``?`` (matches any single character) wildcards.
+Please also refer to `command line flags <#setting-flags>`__ for more
+information.
 
-There’s also ``VLOG_IS_ON(n)`` "verbose level" condition macro. This
-macro returns true when the :cmd:`--v` is equal or greater than ``n``. To
-be used as
+There’s also ``VLOG_IS_ON(n)`` "verbose level" condition macro. This macro
+returns ``true`` when the :cmd:`--v` is equal to or greater than ``n``. The
+macro can be used as follows:
 
 .. code:: cpp
 
@@ -546,22 +613,20 @@ Custom Log Prefix Format
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 glog supports changing the format of the prefix attached to log messages by
-receiving a user-provided callback to be used to generate such strings.
+receiving a user-provided callback that generates such strings.
 
 For each log entry, the callback will be invoked with a ``LogMessageInfo``
 struct containing the severity, filename, line number, thread ID, and time of
 the event. It will also be given a reference to the output stream, whose
 contents will be prepended to the actual message in the final log line.
 
-For example:
+For example, the following function outputs a prefix that matches glog's default
+format. The third parameter ``data`` can be used to access user-supplied data
+which unless specified defaults to :cpp:`nullptr`.
 
 .. code:: cpp
 
-    /* This function writes a prefix that matches glog's default format.
-     * (The third parameter can be used to receive user-supplied data, and is
-     * nullptr by default.)
-     */
-    void CustomPrefix(std::ostream &s, const LogMessageInfo &l, void*) {
+    void CustomPrefix(std::ostream& s, const LogMessageInfo& l, void* /*data*/) {
        s << l.severity[0]
        << setw(4) << 1900 + l.time.year()
        << setw(2) << 1 + l.time.month()
@@ -579,11 +644,15 @@ For example:
     }
 
 
-To enable the use of ``CustomPrefix()``, simply give glog a pointer to it
-during initialization: ``InitGoogleLogging(argv[0], &CustomPrefix);``.
+To enable the use of a custom prefix, use the
+
+.. code:: cpp
 
-Optionally, ``InitGoogleLogging()`` takes a third argument of type  ``void*``
-to pass on to the callback function.
+    InitGoogleLogging(argv[0], &CustomPrefix);
+
+overload to pass a pointer to the corresponding :cpp:`CustomPrefix` function during
+initialization. :cpp:`InitGoogleLogging()` takes a third optional argument of
+type  :cpp:`void*` that allows supplying user data to the callback.
 
 Failure Signal Handler
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -641,19 +710,21 @@ by :cpp:`InstallFailureFunction`.
      google::InstallFailureFunction(&YourFailureFunction);
    }
 
-By default, glog tries to dump stacktrace and makes the program exit
-with status 1. The stacktrace is produced only when you run the program
-on an architecture for which glog supports stack tracing (as of
-September 2008, glog supports stack tracing for x86 and x86_64).
+By default, glog tries to dump the stacktrace and calls :cpp:`std::abort`. The
+stacktrace is generated only when running the application on a system supported
+by glog. Currently, glog supports x86, x86_64, PowerPC architectures,
+``libunwind``, and the Debug Help Library (``dbghelp``) on Windows for
+extracting the stack trace.
+
 
 Raw Logging
 ~~~~~~~~~~~
 
 The header file ``<glog/raw_logging.h>`` can be used for thread-safe logging,
 which does not allocate any memory or acquire any locks. Therefore, the macros
 defined in this header file can be used by low-level memory allocation and
-synchronization code. Please check `src/glog/raw_logging.h.in
-<src/glog/raw_logging.h.in>`__ for detail.
+synchronization code. Please check
+`src/glog/raw_logging.h <src/glog/raw_logging.h>`__ for detail.
 
 Google Style ``perror()``
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -771,9 +842,9 @@ anymore for functions defined in ``glog/logging.h`` .
 If you don’t need ``ERROR`` defined by ``windows.h``, there are a couple
 of more workarounds which sometimes don’t work:
 
--  ``#define WIN32_LEAN_AND_MEAN`` or ``NOGDI`` **before** you
-   ``#include windows.h``.
--  ``#undef ERROR`` **after** you ``#include windows.h`` .
+-  :cpp:`#define WIN32_LEAN_AND_MEAN` or :cpp:`NOGDI` **before**
+   :cpp:`#include <windows.h>`.
+-  :cpp:`#undef ERROR` **after** :cpp:`#include <windows.h>`.
 
 See `this
 issue <http://code.google.com/p/google-glog/issues/detail?id=33>`__ for
@@ -815,19 +886,19 @@ Using :cmd:`-static` is rare, though, so unless you know this will affect you it
 probably won’t.
 
 If you cannot or do not wish to install libunwind, you can still try to
-use two kinds of stack-unwinder: 1. glibc built-in stack-unwinder and 2.
-frame pointer based stack-unwinder.
-
-1. As we already mentioned, glibc’s unwinder has a deadlock issue.
-   However, if you don’t use :cpp:`InstallFailureSignalHandler()` or you
-   don’t worry about the rare possibilities of deadlocks, you can use
-   this stack-unwinder. If you specify no options and ``libunwind``
-   isn’t detected on your system, the configure script chooses this
-   unwinder by default.
-
-2. The frame pointer based stack unwinder requires that your
-   application, the glog library, and system libraries like libc, all be
-   compiled with a frame pointer. This is *not* the default for x86-64.
+use two kinds of stack-unwinder:
+
+glibc built-in stack-unwinder
+    As we already mentioned, glibc’s unwinder has a deadlock issue. However, if
+    you don’t use :cpp:`InstallFailureSignalHandler()` or you don’t worry about
+    the rare possibilities of deadlocks, you can use this stack-unwinder. If you
+    specify no options and ``libunwind`` isn’t detected on your system, the
+    configure script chooses this unwinder by default.
+
+frame pointer based stack-unwinder
+    The frame pointer based stack unwinder requires that your application, the
+    glog library, and system libraries like libc, all be compiled with a frame
+    pointer. This is *not* the default for x86-64.
 
 
 How to Contribute