From 98228427781c5533f49238570ba22904791cb2de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?SZEDER=20G=C3=A1bor?= Date: Fri, 29 Mar 2019 13:35:15 +0100 Subject: [PATCH 1/6] Documentation/git-diff-tree.txt: fix formatting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Asciidoctor versions v1.5.7 or later print the following warning while building the documentation: ASCIIDOC git-diff-tree.xml asciidoctor: WARNING: diff-format.txt: line 2: unterminated listing block This highlights an issue (even with older Asciidoctor versions) where the "Raw output format" header is not rendered as a header, and the rest of the document is rendered in monospace. This is not caused by 'diff-format.txt' in itself, but rather by 'git-diff-tree.txt' including 'pretty-formats.txt' and 'diff-format.txt' on subsequent lines, while the former happens to end with monospace-formatted example commands. Fix this by inserting an empty line between the two include:: directives. The page rendered with AsciiDoc doesn't have this formatting issue. Signed-off-by: SZEDER Gábor Signed-off-by: Junio C Hamano --- Documentation/git-diff-tree.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index 24f32e8c54..5c8a2a5e97 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -118,6 +118,7 @@ include::pretty-options.txt[] include::pretty-formats.txt[] + include::diff-format.txt[] GIT From eeb26f81850d83667d49b9e6d28ebec7c7aad8d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?SZEDER=20G=C3=A1bor?= Date: Fri, 29 Mar 2019 13:35:16 +0100 Subject: [PATCH 2/6] Documentation/technical/api-config.txt: fix formatting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Asciidoctor versions v1.5.7 or later print the following warning while building the documentation: ASCIIDOC technical/api-config.html asciidoctor: WARNING: api-config.txt: line 232: unterminated listing block This highlight an issue (even with older Asciidoctor versions) where the length of the '----' lines surrounding a code example don't match, and the rest of the document is rendered in monospace. Fix this by making sure that the length of those lines match. The page rendered with AsciiDoc doesn't have this formatting issue. Signed-off-by: SZEDER Gábor Signed-off-by: Junio C Hamano --- Documentation/technical/api-config.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt index fa39ac9d71..7d20716c32 100644 --- a/Documentation/technical/api-config.txt +++ b/Documentation/technical/api-config.txt @@ -229,7 +229,7 @@ A `config_set` can be used to construct an in-memory cache for config-like files that the caller specifies (i.e., files like `.gitmodules`, `~/.gitconfig` etc.). For example, ---------------------------------------- +---------------------------------------- struct config_set gm_config; git_configset_init(&gm_config); int b; From b373e4d29b7eb67a40efc038156a8edde7ae2972 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?SZEDER=20G=C3=A1bor?= Date: Fri, 29 Mar 2019 13:35:17 +0100 Subject: [PATCH 3/6] Documentation/technical/protocol-v2.txt: fix formatting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Asciidoctor versions v1.5.7 or later print 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 (even with older Asciidoctor versions) 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" 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 Signed-off-by: Junio C Hamano --- 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 From f34a1bd96c42ac712a8eb828f2303af029c6cd86 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?SZEDER=20G=C3=A1bor?= Date: Fri, 29 Mar 2019 13:35:18 +0100 Subject: [PATCH 4/6] ci: install Asciidoctor in 'ci/install-dependencies.sh' MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When our '.travis.yml' was split into several 'ci/*' scripts [1], the installation of the 'asciidoctor' gem somehow ended up in 'ci/test-documentation.sh'. Install it in 'ci/install-dependencies.sh', where we install other dependencies of the Documentation build job as well (asciidoc, xmlto). [1] 657343a602 (travis-ci: move Travis CI code into dedicated scripts, 2017-09-10) Signed-off-by: SZEDER Gábor Signed-off-by: Junio C Hamano --- ci/install-dependencies.sh | 3 +++ ci/test-documentation.sh | 3 --- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/ci/install-dependencies.sh b/ci/install-dependencies.sh index d64667fcbf..76ec308965 100755 --- a/ci/install-dependencies.sh +++ b/ci/install-dependencies.sh @@ -54,6 +54,9 @@ StaticAnalysis) Documentation) sudo apt-get -q update sudo apt-get -q -y install asciidoc xmlto + + test -n "$ALREADY_HAVE_ASCIIDOCTOR" || + gem install asciidoctor ;; esac diff --git a/ci/test-documentation.sh b/ci/test-documentation.sh index be3b7d376a..8f91f48c81 100755 --- a/ci/test-documentation.sh +++ b/ci/test-documentation.sh @@ -5,9 +5,6 @@ . ${0%/*}/lib.sh -test -n "$ALREADY_HAVE_ASCIIDOCTOR" || -gem install asciidoctor - make check-builtins make check-docs From 615a6c37e1fb3fc15857d12edaad7d6f905c0e5c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?SZEDER=20G=C3=A1bor?= Date: Fri, 29 Mar 2019 20:52:46 +0100 Subject: [PATCH 5/6] ci: stick with Asciidoctor v1.5.8 for now MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The recent release of Asciidoctor v2.0.0 broke our documentation build job on Travis CI, where we 'gem install asciidoctor', which always brings us the latest and (supposedly) greatest. Alas, we are not ready for that just yet, because it removed support for DocBook 4.5, and we have been requiring that particular DocBook version to build 'user-manual.xml' with Asciidoctor, resulting in: ASCIIDOC user-manual.xml asciidoctor: FAILED: missing converter for backend 'docbook45'. Processing aborted. Use --trace for backtrace make[1]: *** [user-manual.xml] Error 1 Unfortunately, we can't simply switch to DocBook 5 right away, as doing so leads to validation errors from 'xmlto', and working around those leads to yet another errors... [1] So let's stick with Asciidoctor v1.5.8 (latest stable release before v2.0.0) in our documentation build job on Travis CI for now, until we figure out how to deal with the fallout from Asciidoctor v2.0.0. [1] https://public-inbox.org/git/20190324162131.GL4047@pobox.com/ Signed-off-by: SZEDER Gábor Signed-off-by: Junio C Hamano --- ci/install-dependencies.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ci/install-dependencies.sh b/ci/install-dependencies.sh index 76ec308965..52a44c690a 100755 --- a/ci/install-dependencies.sh +++ b/ci/install-dependencies.sh @@ -56,7 +56,7 @@ Documentation) sudo apt-get -q -y install asciidoc xmlto test -n "$ALREADY_HAVE_ASCIIDOCTOR" || - gem install asciidoctor + gem install --version 1.5.8 asciidoctor ;; esac From 37fc8cb15faeec4e216e50d93fb9c96ee01ad16a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?SZEDER=20G=C3=A1bor?= Date: Fri, 29 Mar 2019 13:35:20 +0100 Subject: [PATCH 6/6] ci: fix AsciiDoc/Asciidoctor stderr check in the documentation build job MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit In 'ci/test-documentation.sh' we save the standard error of 'make doc', and, in an attempt to make sure that neither AsciiDoc nor Asciidoctor printed any warnings, we check the emptiness of the resulting file with '! test -s stderr.log'. This check has never actually worked, because in our 'ci/*' build scripts we rely on 'set -e' aborting the build job when a command exits with error, and, unfortunately, the combination of the two doesn't work as intended. According to POSIX [1]: "The -e setting shall be ignored when executing [...] a pipeline beginning with the ! reserved word" [2] Watch and learn: $ echo unexpected >file $ ( set -e; ! test -s file ; echo "should not reach this" ) ; echo $? should not reach this 0 This is why we haven't noticed the warnings from Asciidoctor that were fixed in the first patches of this patch series, though some of them were already there in the build of v2.18.0-rc0 [3]. Check the emptiness of that file with 'test ! -s' instead, which works properly with 'set -e': $ ( set -e; test ! -s file ; echo "should not reach this" ) ; echo $? 1 Furthermore, dump the contents of that file to the log for our convenience, so if it were to unexpectedly end up being non-empty, then we wouldn't have to scroll through all that long build log looking for warnings, but could see them right away near the end of the log. Note that we are only really interested in the standard error of AsciiDoc and Asciidoctor, but by saving the stderr of 'make doc' we also save any error output from the make rules. Currently there is only one such line: we build the docs with Asciidoctor right after a 'make clean', meaning that 'make USE_ASCIIDOCTOR=1 doc' always starts with running 'GIT-VERSION-GEN', which in turn prints the version to stderr. A 'sed' command was supposed to remove this version line to prevent it from triggering that (previously defunct) emptiness check, but, unfortunately, this command doesn't work as intended, either, because it leaves the file to be checked intact, but that defunct emptiness check hid this issue, too... Furthermore, in the near future there will be an other line on stderr, because commit 9a71722b4d (Doc: auto-detect changed build flags, 2019-03-17) in the currently cooking branch 'ma/doc-diff-doc-vs-doctor-comparison' will print "* new asciidoc flags" at the beginning of both 'make doc' invokations. Extend that 'sed' command to remove this line, too, wrap it in a helper function so the output of both 'make doc' is filtered the same way, and change its invokation to actually write the logfile to be checked. [1] http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#set [2] POSIX doesn't discuss the meaning of '! cmd' in case of simple commands, but it defines that "A pipeline is a sequence of one or more commands separated by the control operator '|'", so apparently a simple command is considered as pipeline as well. http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_09_02 [3] https://travis-ci.org/git/git/jobs/385932007#L1463 Signed-off-by: SZEDER Gábor Signed-off-by: Junio C Hamano --- ci/test-documentation.sh | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/ci/test-documentation.sh b/ci/test-documentation.sh index 8f91f48c81..d49089832d 100755 --- a/ci/test-documentation.sh +++ b/ci/test-documentation.sh @@ -5,29 +5,38 @@ . ${0%/*}/lib.sh +filter_log () { + sed -e '/^GIT_VERSION = /d' \ + -e '/^ \* new asciidoc flags$/d' \ + "$1" +} + make check-builtins make check-docs # Build docs with AsciiDoc -make doc > >(tee stdout.log) 2> >(tee stderr.log >&2) -! test -s stderr.log +make doc > >(tee stdout.log) 2> >(tee stderr.raw >&2) +cat stderr.raw +filter_log stderr.raw >stderr.log +test ! -s stderr.log test -s Documentation/git.html test -s Documentation/git.xml test -s Documentation/git.1 grep '