[master] 6a483b19f Tweak SLT_Notice to better fit the VSL

[Dridi Boukelmoune]

commit 6a483b19f143ad472a4e82d2a76919f167f92b20
Author: Dridi Boukelmoune <dridi.boukelmoune at gmail.com>
Date:   Fri Dec 20 18:50:35 2019 +0100

    Tweak SLT_Notice to better fit the VSL
    
    Martin entrusted me with those changes after I pointed out that [core]
    was not a great prefix considering that VSL records already have the
    notion of a prefix.
    
    I opted for:
    
    - an actionable "vsl:" prefix for core notice messages
    - a prefix naming scheme mapping to manual pages
    
    As a result I changed the documentation a bit.
    
    Better diff with --word-diff --ignore-all-space options.

diff --git a/bin/varnishd/cache/cache_fetch.c b/bin/varnishd/cache/cache_fetch.c
index 4eaa36a10..64e5ebf77 100644
--- a/bin/varnishd/cache/cache_fetch.c
+++ b/bin/varnishd/cache/cache_fetch.c
@@ -703,7 +703,7 @@ vbf_stp_condfetch(struct worker *wrk, struct busyobj *bo)
 		 * the object attributes are complete when we copy them
 		 * (this would be an issue for ie OA_GZIPBITS). */
 		VSLb(bo->vsl, SLT_Notice,
-		    "[core] Conditional fetch wait for streaming object");
+		    "vsl: Conditional fetch wait for streaming object");
 		ObjWaitState(bo->stale_oc, BOS_FINISHED);
 		stale_state = stale_boc->state;
 		HSH_DerefBoc(bo->wrk, bo->stale_oc);
diff --git a/doc/sphinx/reference/vsl.rst b/doc/sphinx/reference/vsl.rst
index 71a3110b4..583bd07b9 100644
--- a/doc/sphinx/reference/vsl.rst
+++ b/doc/sphinx/reference/vsl.rst
@@ -107,19 +107,23 @@ NOTICE MESSAGES
 
 Notice messages contain informational messages about the handling of a
 request. These can be exceptional circumstances encountered that causes
-deviation from the normal handling. The messages are prefixed with [core]
-for core Varnish generated messages, or with [<VMOD name>] for VMOD
-generated messages. The [core] messages are described in detail below, see
-the individual VMOD documentation for messages from VMODs.
-
-[core] Conditional fetch wait for streaming object
-	The backend answered 304 Not Modified on a conditional fetch using
-	an object that has not yet been fully fetched as the stale
-	template object. This can only happen when the TTL of the object
-	is less than the time it takes to fetch it. The fetch is halted
-	until the stale object is fully fetched, upon which the new object
-	is created as normal. While waiting, any grace time on the stale
-	object will be in effect.
+deviation from the normal handling. The messages are prefixed with ``vsl``
+for core Varnish generated messages, and VMOD authors are encouraged to
+use ``vmod_<name>`` for their own notice messages. This matches the name
+of the manual page where detailed descriptions of notice messages are
+expected.
+
+The core messages are described below.
+
+Conditional fetch wait for streaming object
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The backend answered 304 Not Modified on a conditional fetch using an object
+that has not yet been fully fetched as the stale template object. This can
+only happen when the TTL of the object is less than the time it takes to fetch
+it. The fetch is halted until the stale object is fully fetched, upon which
+the new object is created as normal. While waiting, any grace time on the
+stale object will be in effect.
 
 
 HISTORY
diff --git a/include/tbl/vsl_tags.h b/include/tbl/vsl_tags.h
index 7ff491b07..281416d63 100644
--- a/include/tbl/vsl_tags.h
+++ b/include/tbl/vsl_tags.h
@@ -678,9 +678,17 @@ SLTM(VCL_use, 0, "VCL in use",
 
 SLTM(Notice, 0, "Informational messages about request handling",
 	"Informational log messages on events occured during request"
-	" handling. Lines are prefixed with either [core] or [<VMOD name>]."
-	" See the NOTICE MESSAGES section below or the individual VMOD manual"
+	" handling.\n\n"
+	"The format is::\n\n"
+	"\t%s: %s\n"
+	"\t|   |\n"
+	"\t|   +- Short description of the notice message\n"
+	"\t+----- Manual page containing the detailed description\n"
+	"\n"
+	"See the NOTICE MESSAGES section below or the individual VMOD manual"
 	" pages for detailed information of notice messages.\n"
+	"\n"
+
 )
 
 #undef NOSUP_NOTICE