From: Reinhold Kainhofer <reinhold@kainhofer.com>
Date: Thu, 18 Aug 2011 23:22:00 +0000 (+0200)
Subject: Loglevels: Document distinction between PROGRESS and INFO
X-Git-Tag: release/2.15.9-1~9^2~36
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=f40abd6c55ade9dba9be72ddb415f23a58bb003e;p=lilypond.git

Loglevels: Document distinction between PROGRESS and INFO
---

diff --git a/Documentation/contributor/programming-work.itexi b/Documentation/contributor/programming-work.itexi
index f11406f5fd..9dea92d151 100644
--- a/Documentation/contributor/programming-work.itexi
+++ b/Documentation/contributor/programming-work.itexi
@@ -726,7 +726,7 @@ the console should be:
 @item WARN: Only error messages and warnings
 @item BASIC_PROGRESS: Warnings, errors and basic progress (success, etc.)
 @item PROGRESS: Warnings, errors and full progress messages
-@item INFO: Warnings, errors, progress and more detailed information
+@item INFO: Warnings, errors, progress and more detailed information (default)
 @item DEBUG: All messages, including vull debug messages (very verbose!)
 @end itemize
 
@@ -754,21 +754,32 @@ only prints out the message, but no location.
 @end itemize
 
 There are also Scheme functions to access all of these logging functions from
-scheme. In addition, the Grob class contains some convenience wrappers for
+scheme.  In addition, the Grob class contains some convenience wrappers for
 even easier access to these functions.
 
 The message and debug functions in @code{warn.hh} also have an optional 
 argument @code{newline}, which specifies whether the message should always
-start on a new line or continue a previous message. 
+start on a new line or continue a previous message.
 By default, @code{progress_indication} does NOT start on a new line, but rather
-continue the previous output. All other functions by default start their 
-output on a new line.
+continue the previous output.  They also do not have a particular input
+position associated, so there are no progress functions in the Input class.
+All other functions by default start their output on a new line.
 
-@unnumberedsubsec All logging functions at a glance
+The error functions come in three different flavors: fatal error messages,
+programming error messages and normal error messages.  Errors written
+by the @code{error ()} function will cause LilyPond to exit immediately,
+errors by @code{Input::error ()} will continue the compilation, but
+return a non-zero return value of the lilypond call (i.e. indicate an 
+unsuccessful program execution).  All other errors will be printed on the 
+console, but not exit LilyPond or indicate an unsuccessful return code.
+Their only differences to a warnings are the displayed text and that
+they will be shown with loglevel @code{ERROR}.
+
+If the Scheme option @code{warning-as-error} is set, any warning will be
+treated as if @code{Input::error} was called.
 
-Currently, there are no particular message functions for the INFO loglevel, 
-so it is basically identical to PROGRESS.
 
+@unnumberedsubsec All logging functions at a glance
 
 @multitable @columnfractions 0.16 0.42 0.42
 @headitem
@@ -780,15 +791,19 @@ so it is basically identical to PROGRESS.
 @tab @code{Input::error (msg)}, @code{Input::programming_error (msg)}
 
 @item WARN
-@tab @code{warning (msg)} @c WARN
-@tab @code{Input::warning (msg)} @c WARN
+@tab @code{warning (msg)}
+@tab @code{Input::warning (msg)}
 
 @item BASIC
 @tab @code{successful (msg)}
 @tab -
 
 @item PROGRESS
-@tab @code{progress_indication (msg)}, @code{message (msg)}
+@tab @code{progress_indication (msg)}
+@tab -
+
+@item INFO
+@tab @code{@code{message (msg)}
 @tab @code{Input::message (msg)}
 
 @item DEBUG
@@ -815,6 +830,10 @@ so it is basically identical to PROGRESS.
 
 @item PROGRESS
 @tab -
+@tab -
+
+@item INFO
+@tab -
 @tab @code{(ly:music-message music msg)}
 
 @item DEBUG
@@ -840,14 +859,17 @@ so it is basically identical to PROGRESS.
 @tab -
 
 @item PROGRESS
-@tab (ly:progress msg args), (ly:message msg args)
+@tab @code{(ly:progress msg args)}
+@tab -
+
+@item INFO
+@tab @code{(ly:message msg args)}
 @tab @code{(ly:input-message input msg args)}
 
 @item DEBUG
 @tab @code{(ly:debug msg args)}
 @tab -
 
-
 @end multitable
 
 
diff --git a/Documentation/usage/running.itely b/Documentation/usage/running.itely
index 35be41f9db..147bc84c67 100644
--- a/Documentation/usage/running.itely
+++ b/Documentation/usage/running.itely
@@ -353,9 +353,12 @@ Warnings and error messages, no progress.
 @item BASIC_PROGRESS
 Basic progress messages (success), warnings and errors.
 
-@item PROGRESS (default)
+@item PROGRESS
 All progress messages, warnings and errors.
 
+@item INFO (default)
+Progress messages, warnings, errors and further execution information.
+
 @item DEBUG
 All possible messages, including verbose debug output.
 @end table
diff --git a/flower/include/warn.hh b/flower/include/warn.hh
index 31ca381cb4..7d381f1f08 100644
--- a/flower/include/warn.hh
+++ b/flower/include/warn.hh
@@ -28,7 +28,6 @@
 #define LOG_WARN 1<<1
 #define LOG_BASIC 1<<2  // undocumented basic_progress, i.e. input file name and success
 #define LOG_PROGRESS 1<<3
-// Currently, there is no separation between progress and other info messages:
 #define LOG_INFO 1<<4
 #define LOG_DEBUG 1<<8
 
@@ -38,7 +37,6 @@
 #define LOGLEVEL_WARN (LOGLEVEL_ERROR | LOG_WARN)
 #define LOGLEVEL_BASIC (LOGLEVEL_WARN | LOG_BASIC)
 #define LOGLEVEL_PROGRESS (LOGLEVEL_BASIC | LOG_PROGRESS)
-// Currently, there is no separation between progress and other info messages:
 #define LOGLEVEL_INFO (LOGLEVEL_PROGRESS | LOG_INFO)
 #define LOGLEVEL_DEBUG (LOGLEVEL_INFO | LOG_DEBUG)
 
diff --git a/flower/warn.cc b/flower/warn.cc
index 43eab1add7..870420380e 100644
--- a/flower/warn.cc
+++ b/flower/warn.cc
@@ -37,9 +37,7 @@ using namespace std;
   and print the message only if that's the case
 */
 
-/* Define the loglevel (default is PROGRESS); for now, PROGRESS=INFO for a
-   all relevant output, so be on the safe side and use INFO as default, just
-   in case some output is generated with INFO */
+/* Define the loglevel (default is INFO) */
 int loglevel = LOGLEVEL_INFO;
 
 bool
@@ -86,7 +84,7 @@ set_loglevel (string level)
         set_loglevel (l);
       else
         {
-          non_fatal_error (_f ("unknown log level `%s', using default (PROGRESS)", 
+          non_fatal_error (_f ("unknown log level `%s', using default (INFO)", 
                                level));
           set_loglevel (LOGLEVEL_INFO);
         }
diff --git a/lily/main.cc b/lily/main.cc
index 33eb30af68..5b5ea18d08 100644
--- a/lily/main.cc
+++ b/lily/main.cc
@@ -169,7 +169,7 @@ static Long_option_init options_static[]
   {
     _i ("LOGLEVEL"), "loglevel", 'l', _i ("print log messages according to"
     " LOGLEVEL.  Possible values are:\n"
-    "NONE, ERROR, WARNING, BASIC, PROGRESS (default) and DEBUG.")
+    "NONE, ERROR, WARNING, BASIC, PROGRESS, INFO (default) and DEBUG.")
   },
   {_i ("FILE"), "output", 'o', _i ("write output to FILE (suffix will be added)")},
   {0, "relocate", 0, _i ("relocate using directory of lilypond program")},