httpd.conf grammar

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

httpd.conf grammar

Laurence Tratt
I wanted to use httpd's fastcgi "socket" and "strip" options and based upon
the man page's brief text:

     [no] fastcgi [option]
             Enable FastCGI instead of serving files.  Valid options are:

tried "obvious" permutations such as:

  fastcgi strip 1 socket "..."
  fastcgi socket "..." strip 1
  fastcgi socket "...", strip 1

but with each was greeted by a terse "syntax error".

After hunting around in the relevant parse.y file, it transpires that the
grammar allows, roughly speaking, the following:

  fastcgi
  fastcgi option
  fastcgi { option ((',' '\n'? | '\n') option)* }

In other words, if you want to use more than one option you *have* to use
the {...} notation, but there's more than one way for options inside curly
brackets to be separated. In my case I can specify:

  fastcgi {
    socket "..."
    strip 1
  }

or:

  fastcgi {
    socket "...", strip 1
  }

or:

  fastcgi {
    socket "...",
    strip 1
  }

This raised a couple of questions in my mind.

First, stylistically, I'm not quite sure if having three slightly different
ways of separating multiple options is useful or not. That said, I assume
that some people might already be taking advantage of this flexibility, so
perhaps worrying about it now is pointless.

Second, is it worthwhile giving users a hint about what to do when multiple
options need to be specified? For example, something like:

     [no] fastcgi [option]
             Enable FastCGI instead of serving files.  If more than option
             is specified, they must be included inside { ... }, with each
             option separated by a comma or newline.  Valid options are:

I'm happy to raise a patch if other people think this is worth fixing,
although I'm not entirely sure if we want to make people aware of the full
extent of the grammar, or something a little less complete such as the
suggestion above.


Laurie

Reply | Threaded
Open this post in threaded view
|

Re: httpd.conf grammar

Andrew Grillet
I favour a fuller explanation, this one is fine by me.

On Sun, 21 Mar 2021 at 17:20, Laurence Tratt <[hidden email]> wrote:

>
> I wanted to use httpd's fastcgi "socket" and "strip" options and based upon
> the man page's brief text:
>
>      [no] fastcgi [option]
>              Enable FastCGI instead of serving files.  Valid options are:
>
> tried "obvious" permutations such as:
>
>   fastcgi strip 1 socket "..."
>   fastcgi socket "..." strip 1
>   fastcgi socket "...", strip 1
>
> but with each was greeted by a terse "syntax error".
>
> After hunting around in the relevant parse.y file, it transpires that the
> grammar allows, roughly speaking, the following:
>
>   fastcgi
>   fastcgi option
>   fastcgi { option ((',' '\n'? | '\n') option)* }
>
> In other words, if you want to use more than one option you *have* to use
> the {...} notation, but there's more than one way for options inside curly
> brackets to be separated. In my case I can specify:
>
>   fastcgi {
>     socket "..."
>     strip 1
>   }
>
> or:
>
>   fastcgi {
>     socket "...", strip 1
>   }
>
> or:
>
>   fastcgi {
>     socket "...",
>     strip 1
>   }
>
> This raised a couple of questions in my mind.
>
> First, stylistically, I'm not quite sure if having three slightly different
> ways of separating multiple options is useful or not. That said, I assume
> that some people might already be taking advantage of this flexibility, so
> perhaps worrying about it now is pointless.
>
> Second, is it worthwhile giving users a hint about what to do when multiple
> options need to be specified? For example, something like:
>
>      [no] fastcgi [option]
>              Enable FastCGI instead of serving files.  If more than option
>              is specified, they must be included inside { ... }, with each
>              option separated by a comma or newline.  Valid options are:
>
> I'm happy to raise a patch if other people think this is worth fixing,
> although I'm not entirely sure if we want to make people aware of the full
> extent of the grammar, or something a little less complete such as the
> suggestion above.
>
>
> Laurie
>

Reply | Threaded
Open this post in threaded view
|

Re: httpd.conf grammar

Raf Czlonka-2
In reply to this post by Laurence Tratt
On Sun, Mar 21, 2021 at 05:08:00PM GMT, Laurence Tratt wrote:

> I wanted to use httpd's fastcgi "socket" and "strip" options and based upon
> the man page's brief text:
>
>      [no] fastcgi [option]
>              Enable FastCGI instead of serving files.  Valid options are:
>
> tried "obvious" permutations such as:
>
>   fastcgi strip 1 socket "..."
>   fastcgi socket "..." strip 1
>   fastcgi socket "...", strip 1
>
> but with each was greeted by a terse "syntax error".
>
> After hunting around in the relevant parse.y file, it transpires that the
> grammar allows, roughly speaking, the following:
>
>   fastcgi
>   fastcgi option
>   fastcgi { option ((',' '\n'? | '\n') option)* }
>
> In other words, if you want to use more than one option you *have* to use
> the {...} notation, but there's more than one way for options inside curly
> brackets to be separated. In my case I can specify:
>
>   fastcgi {
>     socket "..."
>     strip 1
>   }
>
> or:
>
>   fastcgi {
>     socket "...", strip 1
>   }
>
> or:
>
>   fastcgi {
>     socket "...",
>     strip 1
>   }
>
> This raised a couple of questions in my mind.
>
> First, stylistically, I'm not quite sure if having three slightly different
> ways of separating multiple options is useful or not. That said, I assume
> that some people might already be taking advantage of this flexibility, so
> perhaps worrying about it now is pointless.
>
> Second, is it worthwhile giving users a hint about what to do when multiple
> options need to be specified? For example, something like:
>
>      [no] fastcgi [option]
>              Enable FastCGI instead of serving files.  If more than option
>              is specified, they must be included inside { ... }, with each
>              option separated by a comma or newline.  Valid options are:
>
> I'm happy to raise a patch if other people think this is worth fixing,
> although I'm not entirely sure if we want to make people aware of the full
> extent of the grammar, or something a little less complete such as the
> suggestion above.
>
>
> Laurie
>

Hi Laurie,

I'd simply use the existing wording, without getting into details.

While there, "braces" dominate the manual page, with a single
occurrence of "brackets" so let's change that too, for consistency.

Regards,

Raf

Index: usr.sbin/httpd/httpd.conf.5
===================================================================
RCS file: /cvs/src/usr.sbin/httpd/httpd.conf.5,v
retrieving revision 1.114
diff -u -p -r1.114 httpd.conf.5
--- usr.sbin/httpd/httpd.conf.5 29 Oct 2020 12:30:52 -0000 1.114
+++ usr.sbin/httpd/httpd.conf.5 21 Mar 2021 22:56:53 -0000
@@ -155,7 +155,7 @@ see
 .Xr patterns 7 .
 .El
 .Pp
-Followed by a block of options that is enclosed in curly brackets:
+Followed by a block of options that is enclosed in curly braces:
 .Bl -tag -width Ds
 .It Ic alias Ar name
 Specify an additional alias
@@ -282,6 +282,7 @@ will neither display nor generate a dire
 .El
 .It Oo Ic no Oc Ic fastcgi Oo Ar option Oc
 Enable FastCGI instead of serving files.
+Multiple options may be specified within curly braces.
 Valid options are:
 .Bl -tag -width Ds
 .It Ic socket Oo Cm tcp Oc Ar socket Oo Ar port Oc

Reply | Threaded
Open this post in threaded view
|

Re: httpd.conf grammar

Laurence Tratt
On Sun, Mar 21, 2021 at 10:58:02PM +0000, Raf Czlonka wrote:

Hello Raf,

> I'd simply use the existing wording, without getting into details.
>
> While there, "braces" dominate the manual page, with a single occurrence of
> "brackets" so let's change that too, for consistency.

That works for me!


Laurie

Reply | Threaded
Open this post in threaded view
|

Re: httpd.conf grammar

Jason McIntyre-2
In reply to this post by Raf Czlonka-2
On Sun, Mar 21, 2021 at 10:58:02PM +0000, Raf Czlonka wrote:

>
> Hi Laurie,
>
> I'd simply use the existing wording, without getting into details.
>
> While there, "braces" dominate the manual page, with a single
> occurrence of "brackets" so let's change that too, for consistency.
>
> Regards,
>
> Raf
>

hi. i could have sworn i recently discussed this documenting of multiple
options with someone else, but cannot find the mails. anyway, a couple
of points:

- "a block of options that is enclosed in curly braces" can be shortened to
  "a block of options enclosed in curly braces". up to you.

- if it is generally true that where multiple options can be given they
  are specified in the same way (curly braces) then it would be better
  just to say up front that this is the case, rather than repeating the
  text endlessly everywhere it's possible.

in other respects i'm fine with the diff.
jmc

> Index: usr.sbin/httpd/httpd.conf.5
> ===================================================================
> RCS file: /cvs/src/usr.sbin/httpd/httpd.conf.5,v
> retrieving revision 1.114
> diff -u -p -r1.114 httpd.conf.5
> --- usr.sbin/httpd/httpd.conf.5 29 Oct 2020 12:30:52 -0000 1.114
> +++ usr.sbin/httpd/httpd.conf.5 21 Mar 2021 22:56:53 -0000
> @@ -155,7 +155,7 @@ see
>  .Xr patterns 7 .
>  .El
>  .Pp
> -Followed by a block of options that is enclosed in curly brackets:
> +Followed by a block of options that is enclosed in curly braces:
>  .Bl -tag -width Ds
>  .It Ic alias Ar name
>  Specify an additional alias
> @@ -282,6 +282,7 @@ will neither display nor generate a dire
>  .El
>  .It Oo Ic no Oc Ic fastcgi Oo Ar option Oc
>  Enable FastCGI instead of serving files.
> +Multiple options may be specified within curly braces.
>  Valid options are:
>  .Bl -tag -width Ds
>  .It Ic socket Oo Cm tcp Oc Ar socket Oo Ar port Oc
>

Reply | Threaded
Open this post in threaded view
|

Re: httpd.conf grammar

Raf Czlonka-2
On Mon, Mar 22, 2021 at 07:08:32AM GMT, Jason McIntyre wrote:

> On Sun, Mar 21, 2021 at 10:58:02PM +0000, Raf Czlonka wrote:
> >
> > Hi Laurie,
> >
> > I'd simply use the existing wording, without getting into details.
> >
> > While there, "braces" dominate the manual page, with a single
> > occurrence of "brackets" so let's change that too, for consistency.
> >
> > Regards,
> >
> > Raf
> >

Hi Jason,

> hi. i could have sworn i recently discussed this documenting of multiple
> options with someone else, but cannot find the mails. anyway, a couple
> of points:
>
> - "a block of options that is enclosed in curly braces" can be shortened to
>   "a block of options enclosed in curly braces". up to you.

Yup.

> - if it is generally true that where multiple options can be given they
>   are specified in the same way (curly braces) then it would be better
>   just to say up front that this is the case, rather than repeating the
>   text endlessly everywhere it's possible.

I did think about it as there's a lot of repetition:

        $ grep '^Multiple options' /usr/share/man/man5/httpd.conf.5
        Multiple options may be specified within curly braces.
        Multiple options may be specified within curly braces.
        Multiple options may be specified within curly braces.
        Multiple options may be specified within curly braces.
        Multiple options may be specified within curly braces.
        Multiple options may be specified within curly braces.

but wanted the diff to be as small as possible ;^)

> in other respects i'm fine with the diff.
> jmc

How about this?

Cheers,

Raf

Index: usr.sbin/httpd/httpd.conf.5
===================================================================
RCS file: /cvs/src/usr.sbin/httpd/httpd.conf.5,v
retrieving revision 1.114
diff -u -p -r1.114 httpd.conf.5
--- usr.sbin/httpd/httpd.conf.5 29 Oct 2020 12:30:52 -0000 1.114
+++ usr.sbin/httpd/httpd.conf.5 22 Mar 2021 13:24:58 -0000
@@ -78,6 +78,8 @@ the comment is effective until the end o
 Argument names not beginning with a letter, digit, or underscore
 must be quoted.
 .Pp
+Multiple options may be specified within curly braces.
+.Pp
 Additional configuration files can be included with the
 .Ic include
 keyword, for example:
@@ -155,7 +157,7 @@ see
 .Xr patterns 7 .
 .El
 .Pp
-Followed by a block of options that is enclosed in curly brackets:
+Followed by a block of options enclosed in curly braces:
 .Bl -tag -width Ds
 .It Ic alias Ar name
 Specify an additional alias
@@ -238,7 +240,6 @@ option.
 .El
 .It Ic connection Ar option
 Set the specified options and limits for HTTP connections.
-Multiple options may be specified within curly braces.
 Valid options are:
 .Bl -tag -width Ds
 .It Ic max request body Ar number
@@ -265,7 +266,6 @@ Set the default media type for the speci
 overwriting the global setting.
 .It Ic directory Ar option
 Set the specified options when serving or accessing directories.
-Multiple options may be specified within curly braces.
 Valid options are:
 .Bl -tag -width Ds
 .It Oo Ic no Oc Ic auto index
@@ -451,7 +451,6 @@ but can be changed per server or locatio
 Use the
 .Ic no log
 directive to disable logging of any requests.
-Multiple options may be specified within curly braces.
 Valid options are:
 .Bl -tag -width Ds
 .It Ic access Ar name
@@ -509,7 +508,6 @@ Disable any previous
 in a location.
 .It Ic request Ar option
 Configure the options for the request path.
-Multiple options may be specified within curly braces.
 Valid options are:
 .Bl -tag -width Ds
 .It Oo Ic no Oc Ic rewrite Ar path
@@ -547,7 +545,6 @@ Enable or disable the specified TCP/IP o
 and
 .Xr ip 4
 for more information about the options.
-Multiple options may be specified within curly braces.
 Valid options are:
 .Bl -tag -width Ds
 .It Ic backlog Ar number
@@ -577,7 +574,6 @@ This will affect the TCP window size.
 .It Ic tls Ar option
 Set the TLS configuration for the server.
 These options are only used if TLS has been enabled via the listen directive.
-Multiple options may be specified within curly braces.
 Valid options are:
 .Bl -tag -width Ds
 .It Ic certificate Ar file

Reply | Threaded
Open this post in threaded view
|

Re: httpd.conf grammar

Jason McIntyre-2
On Mon, Mar 22, 2021 at 01:33:34PM +0000, Raf Czlonka wrote:

> On Mon, Mar 22, 2021 at 07:08:32AM GMT, Jason McIntyre wrote:
> > On Sun, Mar 21, 2021 at 10:58:02PM +0000, Raf Czlonka wrote:
> > >
> > > Hi Laurie,
> > >
> > > I'd simply use the existing wording, without getting into details.
> > >
> > > While there, "braces" dominate the manual page, with a single
> > > occurrence of "brackets" so let's change that too, for consistency.
> > >
> > > Regards,
> > >
> > > Raf
> > >
>
> Hi Jason,
>
> > hi. i could have sworn i recently discussed this documenting of multiple
> > options with someone else, but cannot find the mails. anyway, a couple
> > of points:
> >
> > - "a block of options that is enclosed in curly braces" can be shortened to
> >   "a block of options enclosed in curly braces". up to you.
>
> Yup.
>
> > - if it is generally true that where multiple options can be given they
> >   are specified in the same way (curly braces) then it would be better
> >   just to say up front that this is the case, rather than repeating the
> >   text endlessly everywhere it's possible.
>
> I did think about it as there's a lot of repetition:
>
> $ grep '^Multiple options' /usr/share/man/man5/httpd.conf.5
> Multiple options may be specified within curly braces.
> Multiple options may be specified within curly braces.
> Multiple options may be specified within curly braces.
> Multiple options may be specified within curly braces.
> Multiple options may be specified within curly braces.
> Multiple options may be specified within curly braces.
>
> but wanted the diff to be as small as possible ;^)
>
> > in other respects i'm fine with the diff.
> > jmc
>
> How about this?
>
> Cheers,
>
> Raf
>

yes, exactly what i'd hoped. ok by me.
jmc

> Index: usr.sbin/httpd/httpd.conf.5
> ===================================================================
> RCS file: /cvs/src/usr.sbin/httpd/httpd.conf.5,v
> retrieving revision 1.114
> diff -u -p -r1.114 httpd.conf.5
> --- usr.sbin/httpd/httpd.conf.5 29 Oct 2020 12:30:52 -0000 1.114
> +++ usr.sbin/httpd/httpd.conf.5 22 Mar 2021 13:24:58 -0000
> @@ -78,6 +78,8 @@ the comment is effective until the end o
>  Argument names not beginning with a letter, digit, or underscore
>  must be quoted.
>  .Pp
> +Multiple options may be specified within curly braces.
> +.Pp
>  Additional configuration files can be included with the
>  .Ic include
>  keyword, for example:
> @@ -155,7 +157,7 @@ see
>  .Xr patterns 7 .
>  .El
>  .Pp
> -Followed by a block of options that is enclosed in curly brackets:
> +Followed by a block of options enclosed in curly braces:
>  .Bl -tag -width Ds
>  .It Ic alias Ar name
>  Specify an additional alias
> @@ -238,7 +240,6 @@ option.
>  .El
>  .It Ic connection Ar option
>  Set the specified options and limits for HTTP connections.
> -Multiple options may be specified within curly braces.
>  Valid options are:
>  .Bl -tag -width Ds
>  .It Ic max request body Ar number
> @@ -265,7 +266,6 @@ Set the default media type for the speci
>  overwriting the global setting.
>  .It Ic directory Ar option
>  Set the specified options when serving or accessing directories.
> -Multiple options may be specified within curly braces.
>  Valid options are:
>  .Bl -tag -width Ds
>  .It Oo Ic no Oc Ic auto index
> @@ -451,7 +451,6 @@ but can be changed per server or locatio
>  Use the
>  .Ic no log
>  directive to disable logging of any requests.
> -Multiple options may be specified within curly braces.
>  Valid options are:
>  .Bl -tag -width Ds
>  .It Ic access Ar name
> @@ -509,7 +508,6 @@ Disable any previous
>  in a location.
>  .It Ic request Ar option
>  Configure the options for the request path.
> -Multiple options may be specified within curly braces.
>  Valid options are:
>  .Bl -tag -width Ds
>  .It Oo Ic no Oc Ic rewrite Ar path
> @@ -547,7 +545,6 @@ Enable or disable the specified TCP/IP o
>  and
>  .Xr ip 4
>  for more information about the options.
> -Multiple options may be specified within curly braces.
>  Valid options are:
>  .Bl -tag -width Ds
>  .It Ic backlog Ar number
> @@ -577,7 +574,6 @@ This will affect the TCP window size.
>  .It Ic tls Ar option
>  Set the TLS configuration for the server.
>  These options are only used if TLS has been enabled via the listen directive.
> -Multiple options may be specified within curly braces.
>  Valid options are:
>  .Bl -tag -width Ds
>  .It Ic certificate Ar file
>

Reply | Threaded
Open this post in threaded view
|

Re: httpd.conf grammar

Raf Czlonka-2
Hello,

Could this get committed before the freeze?

Cheers,

Raf

On Mon, Mar 22, 2021 at 02:20:42PM GMT, Jason McIntyre wrote:

> On Mon, Mar 22, 2021 at 01:33:34PM +0000, Raf Czlonka wrote:
> > On Mon, Mar 22, 2021 at 07:08:32AM GMT, Jason McIntyre wrote:
> > > On Sun, Mar 21, 2021 at 10:58:02PM +0000, Raf Czlonka wrote:
> > > >
> > > > Hi Laurie,
> > > >
> > > > I'd simply use the existing wording, without getting into details.
> > > >
> > > > While there, "braces" dominate the manual page, with a single
> > > > occurrence of "brackets" so let's change that too, for consistency.
> > > >
> > > > Regards,
> > > >
> > > > Raf
> > > >
> >
> > Hi Jason,
> >
> > > hi. i could have sworn i recently discussed this documenting of multiple
> > > options with someone else, but cannot find the mails. anyway, a couple
> > > of points:
> > >
> > > - "a block of options that is enclosed in curly braces" can be shortened to
> > >   "a block of options enclosed in curly braces". up to you.
> >
> > Yup.
> >
> > > - if it is generally true that where multiple options can be given they
> > >   are specified in the same way (curly braces) then it would be better
> > >   just to say up front that this is the case, rather than repeating the
> > >   text endlessly everywhere it's possible.
> >
> > I did think about it as there's a lot of repetition:
> >
> > $ grep '^Multiple options' /usr/share/man/man5/httpd.conf.5
> > Multiple options may be specified within curly braces.
> > Multiple options may be specified within curly braces.
> > Multiple options may be specified within curly braces.
> > Multiple options may be specified within curly braces.
> > Multiple options may be specified within curly braces.
> > Multiple options may be specified within curly braces.
> >
> > but wanted the diff to be as small as possible ;^)
> >
> > > in other respects i'm fine with the diff.
> > > jmc
> >
> > How about this?
> >
> > Cheers,
> >
> > Raf
> >
>
> yes, exactly what i'd hoped. ok by me.
> jmc
>
> > Index: usr.sbin/httpd/httpd.conf.5
> > ===================================================================
> > RCS file: /cvs/src/usr.sbin/httpd/httpd.conf.5,v
> > retrieving revision 1.114
> > diff -u -p -r1.114 httpd.conf.5
> > --- usr.sbin/httpd/httpd.conf.5 29 Oct 2020 12:30:52 -0000 1.114
> > +++ usr.sbin/httpd/httpd.conf.5 22 Mar 2021 13:24:58 -0000
> > @@ -78,6 +78,8 @@ the comment is effective until the end o
> >  Argument names not beginning with a letter, digit, or underscore
> >  must be quoted.
> >  .Pp
> > +Multiple options may be specified within curly braces.
> > +.Pp
> >  Additional configuration files can be included with the
> >  .Ic include
> >  keyword, for example:
> > @@ -155,7 +157,7 @@ see
> >  .Xr patterns 7 .
> >  .El
> >  .Pp
> > -Followed by a block of options that is enclosed in curly brackets:
> > +Followed by a block of options enclosed in curly braces:
> >  .Bl -tag -width Ds
> >  .It Ic alias Ar name
> >  Specify an additional alias
> > @@ -238,7 +240,6 @@ option.
> >  .El
> >  .It Ic connection Ar option
> >  Set the specified options and limits for HTTP connections.
> > -Multiple options may be specified within curly braces.
> >  Valid options are:
> >  .Bl -tag -width Ds
> >  .It Ic max request body Ar number
> > @@ -265,7 +266,6 @@ Set the default media type for the speci
> >  overwriting the global setting.
> >  .It Ic directory Ar option
> >  Set the specified options when serving or accessing directories.
> > -Multiple options may be specified within curly braces.
> >  Valid options are:
> >  .Bl -tag -width Ds
> >  .It Oo Ic no Oc Ic auto index
> > @@ -451,7 +451,6 @@ but can be changed per server or locatio
> >  Use the
> >  .Ic no log
> >  directive to disable logging of any requests.
> > -Multiple options may be specified within curly braces.
> >  Valid options are:
> >  .Bl -tag -width Ds
> >  .It Ic access Ar name
> > @@ -509,7 +508,6 @@ Disable any previous
> >  in a location.
> >  .It Ic request Ar option
> >  Configure the options for the request path.
> > -Multiple options may be specified within curly braces.
> >  Valid options are:
> >  .Bl -tag -width Ds
> >  .It Oo Ic no Oc Ic rewrite Ar path
> > @@ -547,7 +545,6 @@ Enable or disable the specified TCP/IP o
> >  and
> >  .Xr ip 4
> >  for more information about the options.
> > -Multiple options may be specified within curly braces.
> >  Valid options are:
> >  .Bl -tag -width Ds
> >  .It Ic backlog Ar number
> > @@ -577,7 +574,6 @@ This will affect the TCP window size.
> >  .It Ic tls Ar option
> >  Set the TLS configuration for the server.
> >  These options are only used if TLS has been enabled via the listen directive.
> > -Multiple options may be specified within curly braces.
> >  Valid options are:
> >  .Bl -tag -width Ds
> >  .It Ic certificate Ar file
> >
>

Reply | Threaded
Open this post in threaded view
|

Re: httpd.conf grammar

Jason McIntyre-2
On Mon, Apr 05, 2021 at 11:05:45PM +0100, Raf Czlonka wrote:
> Hello,
>
> Could this get committed before the freeze?
>

hi. thanks for your mail. i'd thought i was oking a diff, and it's
obviously been left at that.

anyway i rereviewed it, and decided my suggestion to have the sentence
in one place, though good, was bad ;) the trouble is it interferes with
the same sentence in SERVERS, and i worry it would make it unclear.

so i committed a diff which:

- changed brackets to braces, per raf's suggestion
- shortened that text, per mine
- noted that fatcgi could take multiple options

jmc

> Cheers,
>
> Raf
>
> On Mon, Mar 22, 2021 at 02:20:42PM GMT, Jason McIntyre wrote:
> > On Mon, Mar 22, 2021 at 01:33:34PM +0000, Raf Czlonka wrote:
> > > On Mon, Mar 22, 2021 at 07:08:32AM GMT, Jason McIntyre wrote:
> > > > On Sun, Mar 21, 2021 at 10:58:02PM +0000, Raf Czlonka wrote:
> > > > >
> > > > > Hi Laurie,
> > > > >
> > > > > I'd simply use the existing wording, without getting into details.
> > > > >
> > > > > While there, "braces" dominate the manual page, with a single
> > > > > occurrence of "brackets" so let's change that too, for consistency.
> > > > >
> > > > > Regards,
> > > > >
> > > > > Raf
> > > > >
> > >
> > > Hi Jason,
> > >
> > > > hi. i could have sworn i recently discussed this documenting of multiple
> > > > options with someone else, but cannot find the mails. anyway, a couple
> > > > of points:
> > > >
> > > > - "a block of options that is enclosed in curly braces" can be shortened to
> > > >   "a block of options enclosed in curly braces". up to you.
> > >
> > > Yup.
> > >
> > > > - if it is generally true that where multiple options can be given they
> > > >   are specified in the same way (curly braces) then it would be better
> > > >   just to say up front that this is the case, rather than repeating the
> > > >   text endlessly everywhere it's possible.
> > >
> > > I did think about it as there's a lot of repetition:
> > >
> > > $ grep '^Multiple options' /usr/share/man/man5/httpd.conf.5
> > > Multiple options may be specified within curly braces.
> > > Multiple options may be specified within curly braces.
> > > Multiple options may be specified within curly braces.
> > > Multiple options may be specified within curly braces.
> > > Multiple options may be specified within curly braces.
> > > Multiple options may be specified within curly braces.
> > >
> > > but wanted the diff to be as small as possible ;^)
> > >
> > > > in other respects i'm fine with the diff.
> > > > jmc
> > >
> > > How about this?
> > >
> > > Cheers,
> > >
> > > Raf
> > >
> >
> > yes, exactly what i'd hoped. ok by me.
> > jmc
> >
> > > Index: usr.sbin/httpd/httpd.conf.5
> > > ===================================================================
> > > RCS file: /cvs/src/usr.sbin/httpd/httpd.conf.5,v
> > > retrieving revision 1.114
> > > diff -u -p -r1.114 httpd.conf.5
> > > --- usr.sbin/httpd/httpd.conf.5 29 Oct 2020 12:30:52 -0000 1.114
> > > +++ usr.sbin/httpd/httpd.conf.5 22 Mar 2021 13:24:58 -0000
> > > @@ -78,6 +78,8 @@ the comment is effective until the end o
> > >  Argument names not beginning with a letter, digit, or underscore
> > >  must be quoted.
> > >  .Pp
> > > +Multiple options may be specified within curly braces.
> > > +.Pp
> > >  Additional configuration files can be included with the
> > >  .Ic include
> > >  keyword, for example:
> > > @@ -155,7 +157,7 @@ see
> > >  .Xr patterns 7 .
> > >  .El
> > >  .Pp
> > > -Followed by a block of options that is enclosed in curly brackets:
> > > +Followed by a block of options enclosed in curly braces:
> > >  .Bl -tag -width Ds
> > >  .It Ic alias Ar name
> > >  Specify an additional alias
> > > @@ -238,7 +240,6 @@ option.
> > >  .El
> > >  .It Ic connection Ar option
> > >  Set the specified options and limits for HTTP connections.
> > > -Multiple options may be specified within curly braces.
> > >  Valid options are:
> > >  .Bl -tag -width Ds
> > >  .It Ic max request body Ar number
> > > @@ -265,7 +266,6 @@ Set the default media type for the speci
> > >  overwriting the global setting.
> > >  .It Ic directory Ar option
> > >  Set the specified options when serving or accessing directories.
> > > -Multiple options may be specified within curly braces.
> > >  Valid options are:
> > >  .Bl -tag -width Ds
> > >  .It Oo Ic no Oc Ic auto index
> > > @@ -451,7 +451,6 @@ but can be changed per server or locatio
> > >  Use the
> > >  .Ic no log
> > >  directive to disable logging of any requests.
> > > -Multiple options may be specified within curly braces.
> > >  Valid options are:
> > >  .Bl -tag -width Ds
> > >  .It Ic access Ar name
> > > @@ -509,7 +508,6 @@ Disable any previous
> > >  in a location.
> > >  .It Ic request Ar option
> > >  Configure the options for the request path.
> > > -Multiple options may be specified within curly braces.
> > >  Valid options are:
> > >  .Bl -tag -width Ds
> > >  .It Oo Ic no Oc Ic rewrite Ar path
> > > @@ -547,7 +545,6 @@ Enable or disable the specified TCP/IP o
> > >  and
> > >  .Xr ip 4
> > >  for more information about the options.
> > > -Multiple options may be specified within curly braces.
> > >  Valid options are:
> > >  .Bl -tag -width Ds
> > >  .It Ic backlog Ar number
> > > @@ -577,7 +574,6 @@ This will affect the TCP window size.
> > >  .It Ic tls Ar option
> > >  Set the TLS configuration for the server.
> > >  These options are only used if TLS has been enabled via the listen directive.
> > > -Multiple options may be specified within curly braces.
> > >  Valid options are:
> > >  .Bl -tag -width Ds
> > >  .It Ic certificate Ar file
> > >
> >
>