From: Omar Polo <op@omarpolo.com>
Subject: Re: improve *.conf.5
To: gameoftrees@openbsd.org
Date: Tue, 06 Aug 2024 19:19:48 +0200

On 2024/08/06 19:08:08 +0200, Omar Polo <op@omarpolo.com> wrote:
> We have this blurb of text in all our *.conf.5 pages:
> 
> > The file format is line-based, with one configuration directive
> > per line.  Any lines beggining with a '#' are treated as a comments
> > and ignored.
> 
> which is not entirely correct because:
> 
>  1. while most entries are in fact line-based (e.g. `request timeout 2h')
>     we also have a lot of "blocks" which span multiple lines;
> 
>  2. comments don't need to start at the end of the line, they can be
>     anywhere;
> 
>  3. lines can be extended over multiple physical lines using \, and this
>     expands to comments too;
> 
>  4. finally, and more importantly, we don't document when quoting is
>     nicessary.
> 
> Diff below addresses points 2 and 4, if anything because there's little
> need for 3 and it gets confusing when comments are involved, and 1
> because maybe it's better to think of these files as line-based.
> Otherwise, I can lift the whole blurb from smtpd.conf(5) that addresses
> all the points.
> 
> Thoughts?

Ooops, copy-pasted without fixing the "such as".  Now fixed :)

diff /home/op/w/got
commit - df3d15f3663597c19334b0a50326ff2d07fab70d
path + /home/op/w/got
blob - 6e7ca5a02c54e06736b5ac4e5d9755da996cf1f5
file + got/got.conf.5
--- got/got.conf.5
+++ got/got.conf.5
@@ -34,9 +34,15 @@ settings for
 commands executed within this work tree.
 .Pp
 The file format is line-based, with one configuration directive per line.
-Any lines beginning with a
-.Sq #
-are treated as comments and ignored.
+Comments can be put anywhere in the file using a hash mark
+.Pq Sq # ,
+and extend to the end of the current line.
+Arguments names not beginning with a letter, digit or underscore,
+as well as reserved words
+.Pq such as Ic author , Ic remote No or Ic port ,
+must be quoted.
+Arguments containing whitespace should be surrounded by doube quotes
+.Pq \&" .
 .Pp
 The available configuration directives are as follows:
 .Bl -tag -width Ds
blob - fd312076688c5cf8bb47bce4dc90bb1df44222db
file + gotd/gotd.conf.5
--- gotd/gotd.conf.5
+++ gotd/gotd.conf.5
@@ -25,9 +25,15 @@ is the run-time configuration file for
 .Xr gotd 8 .
 .Pp
 The file format is line-based, with one configuration directive per line.
-Any lines beginning with a
-.Sq #
-are treated as comments and ignored.
+Comments can be put anywhere in the file using a hash mark
+.Pq Sq # ,
+and extend to the end of the current line.
+Arguments names not beginning with a letter, digit or underscore,
+as well as reserved words
+.Pq such as Ic listen , Ic repository No or Ic user ,
+must be quoted.
+Arguments containing whitespace should be surrounded by doube quotes
+.Pq \&" .
 .Sh GLOBAL CONFIGURATION
 The available global configuration directives are as follows:
 .Bl -tag -width Ds
blob - 107ee3f149a19d1adc3b1944da2664b7b30b8526
file + gotwebd/gotwebd.conf.5
--- gotwebd/gotwebd.conf.5
+++ gotwebd/gotwebd.conf.5
@@ -25,9 +25,15 @@ is the run-time configuration file for
 .Xr gotwebd 8 .
 .Pp
 The file format is line-based, with one configuration directive per line.
-Any lines beginning with a
-.Sq #
-are treated as comments and ignored.
+Comments can be put anywhere in the file using a hash mark
+.Pq Sq # ,
+and extend to the end of the current line.
+Arguments names not beginning with a letter, digit or underscore,
+as well as reserved words
+.Pq such as Ic listen , Ic server No or Ic user ,
+must be quoted.
+Arguments containing whitespace should be surrounded by doube quotes
+.Pq \&" .
 .Pp
 Macros can be defined that are later expanded in context.
 Macro names must start with a letter, digit, or underscore, and may