"GOT", but the "O" is a cute, smiling pufferfish. Index | Thread | Search

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

Download raw body.

Thread
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?

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 author , Ic remote No or Ic port ,
+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 author , Ic remote No or Ic port ,
+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