[pacman-dev] [PATCH] doc: declare what type of comments we support in pacman.conf

[Allan McRae]

On 12/06/18 21:28, Eli Schwartz wrote:
> Ini-style configuration formats are all over the place. So are we, for
> that matter, as we switched how we treated middle-of-line comments in
> commit 8a19c4a78251c5e34ecf508a65d943ca2dc833c7 -- namely, they're not
> comments anymore. This is surprising to users, who report bugs because
> it used to work, but what's more surprising is that the only
> "documentation" for the type of comments users can be expected to use,
> is by guessing from our example pacman.conf and maybe discovering
> unreliable easter eggs.
> 
> Fixes FS#58809
> 
> Signed-off-by: Eli Schwartz <eschwartz at archlinux.org>
> ---
>  doc/pacman.conf.5.asciidoc | 2 ++
>  1 file changed, 2 insertions(+)
> 
> diff --git a/doc/pacman.conf.5.asciidoc b/doc/pacman.conf.5.asciidoc
> index e5fffecf..157e00ee 100644
> --- a/doc/pacman.conf.5.asciidoc
> +++ b/doc/pacman.conf.5.asciidoc
> @@ -19,6 +19,8 @@ Each section defines a package repository that pacman can use when searching
>  for packages in '\--sync' mode. The exception to this is the options section,
>  which defines global options.
>  
> +Comments are supported, only by beginning a line with the hash (#) symbol.
> +

I don't like this wording.  How about:

Comments are only supported by beginning a line with the hash (#)
symbol.  Comments can not begin in the middle of a line.

>  
>  Example
>  -------
>