Re: [PATCH 3/3] Documentation/technical/protocol-v2.txt: fix formatting
- From
SZEDER Gábor <szeder.dev@gmail.com>
- Date
- Mar 24, 2019, 15:58 UTC
- Message-ID
- <20190324155812.GI22459@szeder.dev>
- In-Reply-To
- <20190324155219.2284-3-szeder.dev@gmail.com>
On Sun, Mar 24, 2019 at 04:52:19PM +0100, SZEDER Gábor wrote:
Show 15 quoted lines
> Some more recent versions of Asciidoctor issue the following warning > while building the documentation: > > ASCIIDOC technical/protocol-v2.html > asciidoctor: WARNING: protocol-v2.txt: line 38: unterminated listing block > > This highlights an issue where the 'Initial Client Request' header is > not rendered as a header but in monospace. I'm not sure what exactly > causes this issue and why it's an issue only with this particular > header, but all headers in 'protocol-v2.txt' are written like this: > > Initial Client Request > ------------------------ > > i.e. the header itself is indented by a space, and the "underline"
Hrm, I don't know where the rest of the sentence went, probably some unnoticed mishap during rebase/reword... Anyway, it should read:
i.e. the header itself is indented by a space, and the "underline" is two characters longer than the header.
Show 156 quoted lines
> Dropping that indentation and making the length of the underline match
> the length of the header apparently fixes this issue.
>
> While at it, adjust all other headers 'protocol-v2.txt' as well, to
> match the style we use everywhere else.
>
> The page rendered with AsciiDoc doesn't have this formatting issue.
>
> Signed-off-by: SZEDER Gábor <szeder.dev@gmail.com>
> ---
> Documentation/technical/protocol-v2.txt | 52 ++++++++++++-------------
> 1 file changed, 26 insertions(+), 26 deletions(-)
>
> diff --git a/Documentation/technical/protocol-v2.txt b/Documentation/technical/protocol-v2.txt
> index ead85ce35c..03264c7d9a 100644
> --- a/Documentation/technical/protocol-v2.txt
> +++ b/Documentation/technical/protocol-v2.txt
> @@ -1,5 +1,5 @@
> - Git Wire Protocol, Version 2
> -==============================
> +Git Wire Protocol, Version 2
> +============================
>
> This document presents a specification for a version 2 of Git's wire
> protocol. Protocol v2 will improve upon v1 in the following ways:
> @@ -22,8 +22,8 @@ will be commands which a client can request be executed. Once a command
> has completed, a client can reuse the connection and request that other
> commands be executed.
>
> - Packet-Line Framing
> ----------------------
> +Packet-Line Framing
> +-------------------
>
> All communication is done using packet-line framing, just as in v1. See
> `Documentation/technical/pack-protocol.txt` and
> @@ -34,8 +34,8 @@ In protocol v2 these special packets will have the following semantics:
> * '0000' Flush Packet (flush-pkt) - indicates the end of a message
> * '0001' Delimiter Packet (delim-pkt) - separates sections of a message
>
> - Initial Client Request
> -------------------------
> +Initial Client Request
> +----------------------
>
> In general a client can request to speak protocol v2 by sending
> `version=2` through the respective side-channel for the transport being
> @@ -43,22 +43,22 @@ used which inevitably sets `GIT_PROTOCOL`. More information can be
> found in `pack-protocol.txt` and `http-protocol.txt`. In all cases the
> response from the server is the capability advertisement.
>
> - Git Transport
> -~~~~~~~~~~~~~~~
> +Git Transport
> +~~~~~~~~~~~~~
>
> When using the git:// transport, you can request to use protocol v2 by
> sending "version=2" as an extra parameter:
>
> 003egit-upload-pack /project.git\0host=myserver.com\0\0version=2\0
>
> - SSH and File Transport
> -~~~~~~~~~~~~~~~~~~~~~~~~
> +SSH and File Transport
> +~~~~~~~~~~~~~~~~~~~~~~
>
> When using either the ssh:// or file:// transport, the GIT_PROTOCOL
> environment variable must be set explicitly to include "version=2".
>
> - HTTP Transport
> -~~~~~~~~~~~~~~~~
> +HTTP Transport
> +~~~~~~~~~~~~~~
>
> When using the http:// or https:// transport a client makes a "smart"
> info/refs request as described in `http-protocol.txt` and requests that
> @@ -79,8 +79,8 @@ A v2 server would reply:
> Subsequent requests are then made directly to the service
> `$GIT_URL/git-upload-pack`. (This works the same for git-receive-pack).
>
> - Capability Advertisement
> ---------------------------
> +Capability Advertisement
> +------------------------
>
> A server which decides to communicate (based on a request from a client)
> using protocol version 2, notifies the client by sending a version string
> @@ -101,8 +101,8 @@ to be executed by the client.
> key = 1*(ALPHA | DIGIT | "-_")
> value = 1*(ALPHA | DIGIT | " -_.,?\/{}[]()<>!@#$%^&*+=:;")
>
> - Command Request
> ------------------
> +Command Request
> +---------------
>
> After receiving the capability advertisement, a client can then issue a
> request to select the command it wants with any particular capabilities
> @@ -137,8 +137,8 @@ command be executed or can terminate the connection. A client may
> optionally send an empty request consisting of just a flush-pkt to
> indicate that no more requests will be made.
>
> - Capabilities
> ---------------
> +Capabilities
> +------------
>
> There are two different types of capabilities: normal capabilities,
> which can be used to to convey information or alter the behavior of a
> @@ -153,8 +153,8 @@ management on the server side in order to function correctly. This
> permits simple round-robin load-balancing on the server side, without
> needing to worry about state management.
>
> - agent
> -~~~~~~~
> +agent
> +~~~~~
>
> The server can advertise the `agent` capability with a value `X` (in the
> form `agent=X`) to notify the client that the server is running version
> @@ -168,8 +168,8 @@ printable ASCII characters except space (i.e., the byte range 32 < x <
> and debugging purposes, and MUST NOT be used to programmatically assume
> the presence or absence of particular features.
>
> - ls-refs
> -~~~~~~~~~
> +ls-refs
> +~~~~~~~
>
> `ls-refs` is the command used to request a reference advertisement in v2.
> Unlike the current reference advertisement, ls-refs takes in arguments
> @@ -199,8 +199,8 @@ The output of ls-refs is as follows:
> symref = "symref-target:" symref-target
> peeled = "peeled:" obj-id
>
> - fetch
> -~~~~~~~
> +fetch
> +~~~~~
>
> `fetch` is the command used to fetch a packfile in v2. It can be looked
> at as a modified version of the v1 fetch where the ref-advertisement is
> @@ -444,8 +444,8 @@ header.
> 2 - progress messages
> 3 - fatal error message just before stream aborts
>
> - server-option
> -~~~~~~~~~~~~~~~
> +server-option
> +~~~~~~~~~~~~~
>
> If advertised, indicates that any number of server specific options can be
> included in a request. This is done by sending each option as a
> --
> 2.21.0.539.g07239c3a71.dirty
>