From: "SZEDER Gábor" <szeder.dev@gmail.com>
To: git@vger.kernel.org
Subject: Re: [PATCH 3/3] Documentation/technical/protocol-v2.txt: fix formatting
Date: Sun, 24 Mar 2019 16:58:12 +0100 [thread overview]
Message-ID: <20190324155812.GI22459@szeder.dev> (raw)
In-Reply-To: <20190324155219.2284-3-szeder.dev@gmail.com>
On Sun, Mar 24, 2019 at 04:52:19PM +0100, SZEDER Gábor wrote:
> 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.
> 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
>
next prev parent reply other threads:[~2019-03-24 15:58 UTC|newest]
Thread overview: 25+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-03-24 15:52 [PATCH 1/3] Documentation/git-diff-tree.txt: fix formatting SZEDER Gábor
2019-03-24 15:52 ` [PATCH 2/3] Documentation/technical/api-config.txt: " SZEDER Gábor
2019-03-24 15:52 ` [PATCH 3/3] Documentation/technical/protocol-v2.txt: " SZEDER Gábor
2019-03-24 15:58 ` SZEDER Gábor [this message]
2019-03-24 21:55 ` [PATCH v2 0/6] Asciidoctor-related formatting and CI fixes SZEDER Gábor
2019-03-24 21:55 ` [PATCH v2 1/6] Documentation/git-diff-tree.txt: fix formatting SZEDER Gábor
2019-03-24 21:55 ` [PATCH v2 2/6] Documentation/technical/api-config.txt: " SZEDER Gábor
2019-03-24 21:55 ` [PATCH v2 3/6] Documentation/technical/protocol-v2.txt: " SZEDER Gábor
2019-03-24 21:55 ` [PATCH v2 4/6] ci: install Asciidoctor in 'ci/install-dependencies.sh' SZEDER Gábor
2019-03-25 21:28 ` Johannes Schindelin
2019-03-25 21:46 ` SZEDER Gábor
2019-03-26 13:41 ` Johannes Schindelin
2019-03-24 21:55 ` [PATCH v2 5/6] ci: stick with Asciidoctor v1.5.8 for now SZEDER Gábor
2019-03-24 21:55 ` [PATCH v2 6/6] ci: fix AsciiDoc/Asciidoctor stderr check in the documentation build job SZEDER Gábor
2019-03-26 16:24 ` [PATCH v2 0/6] Asciidoctor-related formatting and CI fixes Jeff King
2019-03-29 12:35 ` [PATCH v3 " SZEDER Gábor
2019-03-29 12:35 ` [PATCH v3 1/6] Documentation/git-diff-tree.txt: fix formatting SZEDER Gábor
2019-03-29 12:35 ` [PATCH v3 2/6] Documentation/technical/api-config.txt: " SZEDER Gábor
2019-03-29 12:35 ` [PATCH v3 3/6] Documentation/technical/protocol-v2.txt: " SZEDER Gábor
2019-03-29 12:35 ` [PATCH v3 4/6] ci: install Asciidoctor in 'ci/install-dependencies.sh' SZEDER Gábor
2019-03-29 12:35 ` [PATCH v3 5/6] ci: stick with Asciidoctor v1.5.8 for now SZEDER Gábor
2019-03-29 19:52 ` [PATCH v3.1 " SZEDER Gábor
2019-04-03 11:34 ` Martin Ågren
2019-03-29 12:35 ` [PATCH v3 6/6] ci: fix AsciiDoc/Asciidoctor stderr check in the documentation build job SZEDER Gábor
2019-03-29 15:56 ` [PATCH v3 0/6] Asciidoctor-related formatting and CI fixes Johannes Schindelin
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20190324155812.GI22459@szeder.dev \
--to=szeder.dev@gmail.com \
--cc=git@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).