Loglevels: Document distinction between PROGRESS and INFO

[lilypond.git] / Documentation / contributor / programming-work.itexi

diff --git a/Documentation/contributor/programming-work.itexi b/Documentation/contributor/programming-work.itexi
index f11406f5fd4ecc643aae1005c0caf4e8a1a3b5b4..9dea92d1511680b716121b68608d70dbbea1ba75 100644 (file)
--- 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