From cd697583f3ffd8496d1ee3d3a23ee3fa7875b54c Mon Sep 17 00:00:00 2001
From: Martin Quinson <martin.quinson@ens-rennes.fr>
Date: Mon, 25 Jan 2021 11:06:16 +0100
Subject: [PATCH] Various doc improvements

---
 docs/bin/extract_logs_hierarchy.pl  |  6 ++++--
 docs/source/Configuring_SimGrid.rst | 10 ++++++++++
 docs/source/outcomes.rst            |  4 ++--
 3 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/docs/bin/extract_logs_hierarchy.pl b/docs/bin/extract_logs_hierarchy.pl
index a6f3dfe8b4..85083d2c50 100755
--- a/docs/bin/extract_logs_hierarchy.pl
+++ b/docs/bin/extract_logs_hierarchy.pl
@@ -1,7 +1,6 @@
 #!/usr/bin/env perl
 
-# Copyright (c) 2008-2021. The SimGrid Team.
-# All rights reserved.
+# Copyright (c) 2008-2021. The SimGrid Team. All rights reserved.
 
 # This program is free software; you can redistribute it and/or modify it
 # under the terms of the license (GNU LGPL) which comes with this package.
@@ -15,6 +14,9 @@ print ".. Generated file, do not edit \n\n";
 print ".. _logging_categories:\n\n";
 print "Existing categories\n";
 print "===================\n\n";
+print "This is the list of all categories existing in the SimGrid implementation. "
+  ."Some of them only exist with specific compile-time options, while your implementation may add new ones. "
+  ."Please add \`\`--help-log-categories\`\` to the command-line of a SimGrid simulator to see the exact list of categories usable with it.\n\n";
 
 # Search for calls to macros defining new channels, and prepare the tree representation
 my %ancestor;
diff --git a/docs/source/Configuring_SimGrid.rst b/docs/source/Configuring_SimGrid.rst
index b739bf3298..6f8a2e5a2c 100644
--- a/docs/source/Configuring_SimGrid.rst
+++ b/docs/source/Configuring_SimGrid.rst
@@ -1647,6 +1647,16 @@ Let's consider a more complex example: ``--log="root.app:file:all.log s4u.app:fi
 ``iface.log`` file; the logging of the xbt toolbox will be sent to both the ``xbt.log`` file and the ``all.log`` file (because xbt additivity was enabled); and every other loggings
 will only be sent to ``all.log``.
 
+Other options
+.............
+
+``--help-logs`` displays a complete help message about logging in SimGrid.
+
+``--help-log-categories`` displays the actual hierarchy of log categories for this binary.
+
+``--log=no_loc`` hides the source locations (file names and line numbers) from the messages. This is useful to make tests reproducible.
+
+
 .. |br| raw:: html
 
    <br />
diff --git a/docs/source/outcomes.rst b/docs/source/outcomes.rst
index b05e12c21e..a27ebca15f 100644
--- a/docs/source/outcomes.rst
+++ b/docs/source/outcomes.rst
@@ -13,8 +13,8 @@ should use SimGrid's logging facilities, that are inspired from `Log4J <https://
 severity and their topic. There  is four main concepts in SimGrid's logging mechanism:
 
 The **category** of a message represents its topic. These categories are organized as a hierarchy, loosely corresponding to SimGrid's modules architecture. `Existing categories
-<xbt_log_cat>`_ are documented online, but some of them may be disabled depending on the compilation options. Use ``--help-logs`` on the command line to see the categories actually
-provided a given simulator.
+<logging_categories>`_ are documented online, but some of them may be disabled depending on the compilation options. Use ``--help-log-categories`` on the command line to see 
+the categories actually provided a given simulator.
 
 The message **priority** represents its severity. It can be one of ``trace``, ``debug``, ``verb``, ``info``, ``warn``, ``error`` and ``critical``. Every category has a configured
 threshold, and only the messages with a higher severity are displayed (the others are not even evaluated). For example, you may want to see every debugging message of the Host
-- 
2.20.1