[bug#33342] [PATCH] doc: Fix formatting of notes in multiple sections. Add note

[zimoun]

Hi,

This patch#33342 seems felt into the cracks:

    http://issues.guix.gnu.org/issue/33342

and it appears to me an improvement.  The commit title and the commit
message are not ready tough.

Do we apply it?

On Sun, 11 Nov 2018 at 10:32, swedebugia <swedebugia@riseup.net> wrote:

>>From 27ee648a921f1586f6a2d145de06fe93635102cd Mon Sep 17 00:00:00 2001
> From: swedebugia <swedebugia@riseup.net>
> Date: Sun, 11 Nov 2018 10:28:23 +0100
> Subject: [PATCH] doc: Fix formatting of notes in multiple sections. Add note
>
> * doc/guix.texi (Instantiating the system): Add suggestion to keep
>   config.scm under version control.
> ---
>  doc/guix.texi | 40 ++++++++++++++++++++++++++++++----------
>  1 file changed, 30 insertions(+), 10 deletions(-)
>
> diff --git a/doc/guix.texi b/doc/guix.texi
> index c74351dd8..cbf65c2df 100644
> --- a/doc/guix.texi
> +++ b/doc/guix.texi
> @@ -9780,6 +9780,11 @@ file, the @command{guix system reconfigure 
> my-system-config.scm} command
>  instantiates that configuration, and makes it the default GRUB boot
>  entry (@pxref{Invoking guix system}).
>
> +@quotation Note
> +Note: We recommend that you keep this my-system-config.scm-file safe and 
> under
> +version control to easily track changes to your configuration.
> +@end quotation
> +
>  The normal way to change the system configuration is by updating this
>  file and re-running @command{guix system reconfigure}.  One should never
>  have to touch files in @file{/etc} or to run commands that modify the
> @@ -12853,9 +12858,11 @@ like this (you need to use the @code{(gnu packages 
> cups)} module):
>               (list cups-filters escpr hplip-minimal))))
>  @end example
>
> +@quotation Note
>  Note: If you wish to use the Qt5 based GUI which comes with the hplip
>  package then it is suggested that you install the @code{hplip} package,
>  either in your OS configuration file or as your user.
> +@end quotation
>
>  The available configuration parameters follow.  Each parameter
>  definition is preceded by its type; for example, @samp{string-list foo}
> @@ -15930,11 +15937,13 @@ example if you want your users to have addresses 
> like
>  @samp{"john.smith@@example.com"} then you need to add a host
>  @samp{"example.com"}.  All options in this list will apply only to this host.
>
> +@quotation Note
>  Note: the name "virtual" host is used in configuration to avoid confusion 
> with
>  the actual physical host that Prosody is installed on.  A single Prosody
>  instance can serve many domains, each one defined as a VirtualHost entry in
>  Prosody's configuration.  Conversely a server that hosts a single domain 
> would
>  have just one VirtualHost entry.
> +@end quotation
>
>  See @url{https://prosody.im/doc/configure#virtual_host_settings}.
>
> @@ -16274,9 +16283,11 @@ before setting it here, to get a feel for which 
> cipher suites you will get.
>  After setting this option, it is recommend that you inspect your Murmur log
>  to ensure that Murmur is using the cipher suites that you expected it to.
>
> +@quotation Note
>  Note: Changing this option may impact the backwards compatibility of your
>  Murmur server, and can remove the ability for older Mumble clients to be able
>  to connect to it.
> +@end quotation
>
>  @item @code{public-registration} (default: @code{#f})
>  Must be a @code{<murmur-public-registration-configuration>} record or 
> @code{#f}.
> @@ -18048,13 +18059,15 @@ configuration:
>  (service ddclient-service-type)
>  @end example
>
> -Note that ddclient needs to access credentials that are stored in a
> +@quotation Note
> +Note: ddclient needs to access credentials that are stored in a
>  @dfn{secret file}, by default @file{/etc/ddclient/secrets} (see
>  @code{secret-file} below.)  You are expected to create this file manually, in
>  an ``out-of-band'' fashion (you @emph{could} make this file part of the
>  service configuration, for instance by using @code{plain-file}, but it will 
> be
>  world-readable @i{via} @file{/gnu/store}.)  See the examples in the
>  @file{share/ddclient} directory of the @code{ddclient} package.
> +@end quotation
>
>  @c %start of fragment
>
> @@ -21609,10 +21622,12 @@ to the @code{packages} field of the 
> @code{operating-system} declaration
>  @code{nss-certs}, which is a set of CA certificates provided as part of
>  Mozilla's Network Security Services.
>
> -Note that it is @emph{not} part of @var{%base-packages}, so you need to
> +@quotation Note
> +Note: @code{nss-certs} is @emph{not} part of @var{%base-packages}, so you 
> need to
>  explicitly add it.  The @file{/etc/ssl/certs} directory, which is where
>  most applications and libraries look for certificates by default, points
>  to the certificates installed globally.
> +@end quotation
>
>  Unprivileged users, including users of Guix on a foreign distro,
>  can also install their own certificate package in
> @@ -21700,13 +21715,14 @@ Do not worry: the @code{%mdns-host-lookup-nss} 
> variable (see below)
>  contains this configuration, so you will not have to type it if all you
>  want is to have @code{.local} host lookup working.
>
> -Note that, in this case, in addition to setting the
> -@code{name-service-switch} of the @code{operating-system} declaration,
> -you also need to use @code{avahi-service} (@pxref{Networking Services,
> -@code{avahi-service}}), or @var{%desktop-services}, which includes it
> -(@pxref{Desktop Services}).  Doing this makes @code{nss-mdns} accessible
> -to the name service cache daemon (@pxref{Base Services,
> -@code{nscd-service}}).
> +@quotation Note
> +Note: In addition to setting the @code{name-service-switch} of the
> +@code{operating-system} declaration, you also need to use 
> @code{avahi-service}
> +(@pxref{Networking Services, @code{avahi-service}}), or
> +@var{%desktop-services}, which includes it (@pxref{Desktop Services}).  Doing
> +this makes @code{nss-mdns} accessible to the name service cache daemon
> +(@pxref{Base Services, @code{nscd-service}}).
> +@end quotation
>
>  For convenience, the following variables provide typical NSS
>  configurations.
> @@ -22542,6 +22558,10 @@ $ guix system extension-graph @var{file} | dot -Tpdf 
> > services.pdf
>
>  produces a PDF file showing the extension relations among services.
>
> +@quotation Note
> +Note: The @command{dot} program is provided by the @code{graphviz} package.
> +@end quotation
> +
>  @anchor{system-shepherd-graph}
>  @item shepherd-graph
>  Emit in Dot/Graphviz format to standard output the @dfn{dependency
> @@ -22660,7 +22680,7 @@ VM.  To enable that you'll also have to pass the 
> following flags to @command{qem
>  name=com.redhat.spice.0
>  @end example
>
> -You'll also need to add the @pxref{Miscellaneous Services, Spice service}.
> +You'll also need to add the @code{(spice-service)}, @pxref{Miscellaneous 
> Services, Spice service}.
>
>  @node Defining Services
>  @subsection Defining Services

Cheers,
simon