From: Stefan Sperling <stsp@stsp.name>
Subject: Re: improve *.conf.5
To: Omar Polo <op@omarpolo.com>
Cc: gameoftrees@openbsd.org
Date: Tue, 6 Aug 2024 20:39:47 +0200

On Tue, Aug 06, 2024 at 07:19:48PM +0200, Omar Polo wrote:
> 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

typo: doube -> double
(occurs in all 3 changed pages)

ok with that fixed.

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