Re: [PATCH v5 2/5] promisor-remote: allow a server to advertise more fields

> > +promisor.sendFields::
> > +     A comma or space separated list of additional remote related
> > +     field names. A server will send these field names and the
> > +     associated field values from its configuration when
> > +     advertising its promisor remotes using the "promisor-remote"
> > +     capability, see linkgit:gitprotocol-v2[5]. Currently, only the
> > +     "partialCloneFilter" and "token" field names are supported.
> > ++
> > +* "partialCloneFilter": contains the partial clone filter
> > +  used for the remote.
> > ++
> > +* "token": contains an authentication token for the remote.
> > ++
>
> This kind of text structure calls a description list instead and you can
> already use backquotes:
>
> `partialCloneFilter`:: contains the partial clone filter
> > +  used for the remote.
> > ++
> > +`token`:: contains an authentication token for the remote.

> > +When a field name is part of this list and a corresponding
> > +"remote.foo.<field name>" config variable is set on the server to a
>
> Please no space in placeholders: <field-name>
>
> > +non-empty value, then the field name and value will be sent when
> > +advertising the promisor remote "foo".
> > ++
> > +This list has no effect unless the "promisor.advertise" config
> > +variable is set to "true", and the "name" and "url" fields are always
> > +advertised regardless of this setting.
> > +
>
> More generally, I am a bit annoyed by the usage of the "will" auxiliary
> when not expressing a true future. For an international audience, this
> can be misleading. The plain language[1] philosophy mandates to not use
> auxiliaries other than where they are required (no convoluted sentences).

> Would it make sense to start a style guide to help writing consistent
> documentation that targets people whose first language is not English?
> Being an non native speaker, I often find our docs too literate, with
> lengthy sentences.
>
> [1] https://en.wikipedia.org/wiki/Plain_language

> >  promisor.acceptFromServer::
> >       If set to "all", a client will accept all the promisor remotes
> >       a server might advertise using the "promisor-remote"
> > diff --git a/Documentation/gitprotocol-v2.adoc b/Documentation/gitprotocol-v2.adoc
> > index 9a57005d77..0583fafa09 100644
> > --- a/Documentation/gitprotocol-v2.adoc
> > +++ b/Documentation/gitprotocol-v2.adoc
> > @@ -785,33 +785,59 @@ retrieving the header from a bundle at the indicated URI, and thus
> >  save themselves and the server(s) the request(s) needed to inspect the
> >  headers of that bundle or bundles.
> >
> > -promisor-remote=<pr-infos>
> > +promisor-remote=<pr-info>
> >  ~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> Be careful to adjust the length of the underline to the one of the title

> > +After these mandatory fields, the server MAY advertise the following
> > +optional fields in any order:
> > +
> > +- "partialCloneFilter": The filter specification used by the remote.
> > +Clients can use this to determine if the remote's filtering strategy
> > +is compatible with their needs (e.g., checking if both use "blob:none").
> > +It corresponds to the "remote.<name>.partialCloneFilter" config setting.
> > +
> > +- "token": An authentication token that clients can use when
> > +connecting to the remote. It corresponds to the "remote.<name>.token"
> > +config setting.
> > +
>
> This list can be turned into a description list.

> > +No other fields are defined by the protocol at this time. Clients MUST
> > +ignore fields they don't recognize to allow for future protocol
> > +extensions.
> > +
> > +For now, the client can only use information transmitted through these
> > +fields to decide if it accepts the advertised promisor remote. In the
> > +future that information might be used for other purposes though.
> > +
> > +Field values MUST be urlencoded.
> > +
> > +If the client decides to use one or more promisor remotes the server
> > +advertised, it can reply with "promisor-remote=<pr-names>" where
> > +<pr-names> should be of the form:
> > +
> > +     pr-names = pr-name | pr-names ";" pr-names
>
> Here the syntax used is not compatible with synopsis. Would it make
> sense to uniformize it, or is BNF ok?