diff mbox

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

Message ID 20180612112852.28152-3-eschwartz@archlinux.org
State Superseded, archived
Headers show

Commit Message

Eli Schwartz June 12, 2018, 11:28 a.m. UTC
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@archlinux.org>
---
 doc/pacman.conf.5.asciidoc | 2 ++
 1 file changed, 2 insertions(+)

Comments

Allan McRae June 19, 2018, 11:16 a.m. UTC | #1
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@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
>  -------
>
diff mbox

Patch

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.
+
 
 Example
 -------