{"thread":{"id":"50814","subject":"[PATCH 1/3] Documentation/git-diff-tree.txt: fix formatting","startedAt":"2019-03-24T15:52:27Z","lastAt":"2019-04-03T11:35:13Z","messageCount":25,"participants":["SZEDER Gábor","Johannes Schindelin","Jeff King","Martin Ågren"],"isPatch":true,"patchVersion":1,"patchTotal":3},"messages":[{"id":"372369","messageId":"20190324155219.2284-1-szeder.dev@gmail.com","threadId":"50814","inReplyTo":null,"subject":"[PATCH 1/3] Documentation/git-diff-tree.txt: fix formatting","fromName":"SZEDER Gábor","fromEmail":"szeder.dev@gmail.com","sentAt":"2019-03-24T15:52:17Z","receivedAt":"2019-03-24T15:52:27Z","isPatch":true,"sender":{"key":"szeder.dev@gmail.com","avatar":"https://avatars.githubusercontent.com/u/116324?v=4"},"body":"Some more recent versions of Asciidoctor issue the following warning\nwhile building the documentation:\n\n      ASCIIDOC git-diff-tree.xml\n  asciidoctor: WARNING: diff-format.txt: line 2: unterminated listing block\n\nThis highlights an issue where the \"Raw output format\" header is not\nrendered as a header, and the rest of the document is rendered in\nmonospace.  This is not caused by 'diff-format.txt' in itself, but\nrather by 'git-diff-tree.txt' including 'pretty-formats.txt' and\n'diff-format.txt' on subsequent lines, while the former happens to end\nwith monospace-formatted example commands.\n\nFix this by inserting an empty line between the two include::\ndirectives.\n\nThe page rendered with AsciiDoc doesn't have this formatting issue.\n\nSigned-off-by: SZEDER Gábor <szeder.dev@gmail.com>\n---\n Documentation/git-diff-tree.txt | 1 +\n 1 file changed, 1 insertion(+)\n\ndiff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt\nindex 24f32e8c54..5c8a2a5e97 100644\n--- a/Documentation/git-diff-tree.txt\n+++ b/Documentation/git-diff-tree.txt\n@@ -118,6 +118,7 @@ include::pretty-options.txt[]\n \n \n include::pretty-formats.txt[]\n+\n include::diff-format.txt[]\n \n GIT\n-- \n2.21.0.539.g07239c3a71.dirty\n\n"},{"id":"372370","messageId":"20190324155219.2284-2-szeder.dev@gmail.com","threadId":"50814","inReplyTo":"20190324155219.2284-1-szeder.dev@gmail.com","subject":"[PATCH 2/3] Documentation/technical/api-config.txt: fix formatting","fromName":"SZEDER Gábor","fromEmail":"szeder.dev@gmail.com","sentAt":"2019-03-24T15:52:18Z","receivedAt":"2019-03-24T15:52:32Z","isPatch":true,"sender":{"key":"szeder.dev@gmail.com","avatar":"https://avatars.githubusercontent.com/u/116324?v=4"},"body":"Some more recent versions of Asciidoctor issue the following warning\nwhile building the documentation:\n\n      ASCIIDOC technical/api-config.html\n  asciidoctor: WARNING: api-config.txt: line 232: unterminated listing block\n\nThis highlight an issue where the length of the '----' lines\nsurrounding a code example don't match, and the rest of the document\nis rendered in monospace.\n\nFix this by making sure that the length of those lines match.\n\nThe page rendered with AsciiDoc doesn't have this formatting issue.\n\nSigned-off-by: SZEDER Gábor <szeder.dev@gmail.com>\n---\n Documentation/technical/api-config.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt\nindex fa39ac9d71..7d20716c32 100644\n--- a/Documentation/technical/api-config.txt\n+++ b/Documentation/technical/api-config.txt\n@@ -229,7 +229,7 @@ A `config_set` can be used to construct an in-memory cache for\n config-like files that the caller specifies (i.e., files like `.gitmodules`,\n `~/.gitconfig` etc.). For example,\n \n----------------------------------------\n+----------------------------------------\n struct config_set gm_config;\n git_configset_init(&gm_config);\n int b;\n-- \n2.21.0.539.g07239c3a71.dirty\n\n"},{"id":"372371","messageId":"20190324155219.2284-3-szeder.dev@gmail.com","threadId":"50814","inReplyTo":"20190324155219.2284-1-szeder.dev@gmail.com","subject":"[PATCH 3/3] Documentation/technical/protocol-v2.txt: fix formatting","fromName":"SZEDER Gábor","fromEmail":"szeder.dev@gmail.com","sentAt":"2019-03-24T15:52:19Z","receivedAt":"2019-03-24T15:52:32Z","isPatch":true,"sender":{"key":"szeder.dev@gmail.com","avatar":"https://avatars.githubusercontent.com/u/116324?v=4"},"body":"Some more recent versions of Asciidoctor issue the following warning\nwhile building the documentation:\n\n      ASCIIDOC technical/protocol-v2.html\n  asciidoctor: WARNING: protocol-v2.txt: line 38: unterminated listing block\n\nThis highlights an issue where the 'Initial Client Request' header is\nnot rendered as a header but in monospace.  I'm not sure what exactly\ncauses this issue and why it's an issue only with this particular\nheader, but all headers in 'protocol-v2.txt' are written like this:\n\n   Initial Client Request\n  ------------------------\n\ni.e. the header itself is indented by a space, and the \"underline\"\n\nDropping that indentation and making the length of the underline match\nthe length of the header apparently fixes this issue.\n\nWhile at it, adjust all other headers 'protocol-v2.txt' as well, to\nmatch the style we use everywhere else.\n\nThe page rendered with AsciiDoc doesn't have this formatting issue.\n\nSigned-off-by: SZEDER Gábor <szeder.dev@gmail.com>\n---\n Documentation/technical/protocol-v2.txt | 52 ++++++++++++-------------\n 1 file changed, 26 insertions(+), 26 deletions(-)\n\ndiff --git a/Documentation/technical/protocol-v2.txt b/Documentation/technical/protocol-v2.txt\nindex ead85ce35c..03264c7d9a 100644\n--- a/Documentation/technical/protocol-v2.txt\n+++ b/Documentation/technical/protocol-v2.txt\n@@ -1,5 +1,5 @@\n- Git Wire Protocol, Version 2\n-==============================\n+Git Wire Protocol, Version 2\n+============================\n \n This document presents a specification for a version 2 of Git's wire\n protocol.  Protocol v2 will improve upon v1 in the following ways:\n@@ -22,8 +22,8 @@ will be commands which a client can request be executed.  Once a command\n has completed, a client can reuse the connection and request that other\n commands be executed.\n \n- Packet-Line Framing\n----------------------\n+Packet-Line Framing\n+-------------------\n \n All communication is done using packet-line framing, just as in v1.  See\n `Documentation/technical/pack-protocol.txt` and\n@@ -34,8 +34,8 @@ In protocol v2 these special packets will have the following semantics:\n   * '0000' Flush Packet (flush-pkt) - indicates the end of a message\n   * '0001' Delimiter Packet (delim-pkt) - separates sections of a message\n \n- Initial Client Request\n-------------------------\n+Initial Client Request\n+----------------------\n \n In general a client can request to speak protocol v2 by sending\n `version=2` through the respective side-channel for the transport being\n@@ -43,22 +43,22 @@ used which inevitably sets `GIT_PROTOCOL`.  More information can be\n found in `pack-protocol.txt` and `http-protocol.txt`.  In all cases the\n response from the server is the capability advertisement.\n \n- Git Transport\n-~~~~~~~~~~~~~~~\n+Git Transport\n+~~~~~~~~~~~~~\n \n When using the git:// transport, you can request to use protocol v2 by\n sending \"version=2\" as an extra parameter:\n \n    003egit-upload-pack /project.git\\0host=myserver.com\\0\\0version=2\\0\n \n- SSH and File Transport\n-~~~~~~~~~~~~~~~~~~~~~~~~\n+SSH and File Transport\n+~~~~~~~~~~~~~~~~~~~~~~\n \n When using either the ssh:// or file:// transport, the GIT_PROTOCOL\n environment variable must be set explicitly to include \"version=2\".\n \n- HTTP Transport\n-~~~~~~~~~~~~~~~~\n+HTTP Transport\n+~~~~~~~~~~~~~~\n \n When using the http:// or https:// transport a client makes a \"smart\"\n info/refs request as described in `http-protocol.txt` and requests that\n@@ -79,8 +79,8 @@ A v2 server would reply:\n Subsequent requests are then made directly to the service\n `$GIT_URL/git-upload-pack`. (This works the same for git-receive-pack).\n \n- Capability Advertisement\n---------------------------\n+Capability Advertisement\n+------------------------\n \n A server which decides to communicate (based on a request from a client)\n using protocol version 2, notifies the client by sending a version string\n@@ -101,8 +101,8 @@ to be executed by the client.\n     key = 1*(ALPHA | DIGIT | \"-_\")\n     value = 1*(ALPHA | DIGIT | \" -_.,?\\/{}[]()<>!@#$%^&*+=:;\")\n \n- Command Request\n------------------\n+Command Request\n+---------------\n \n After receiving the capability advertisement, a client can then issue a\n request to select the command it wants with any particular capabilities\n@@ -137,8 +137,8 @@ command be executed or can terminate the connection.  A client may\n optionally send an empty request consisting of just a flush-pkt to\n indicate that no more requests will be made.\n \n- Capabilities\n---------------\n+Capabilities\n+------------\n \n There are two different types of capabilities: normal capabilities,\n which can be used to to convey information or alter the behavior of a\n@@ -153,8 +153,8 @@ management on the server side in order to function correctly.  This\n permits simple round-robin load-balancing on the server side, without\n needing to worry about state management.\n \n- agent\n-~~~~~~~\n+agent\n+~~~~~\n \n The server can advertise the `agent` capability with a value `X` (in the\n form `agent=X`) to notify the client that the server is running version\n@@ -168,8 +168,8 @@ printable ASCII characters except space (i.e., the byte range 32 < x <\n and debugging purposes, and MUST NOT be used to programmatically assume\n the presence or absence of particular features.\n \n- ls-refs\n-~~~~~~~~~\n+ls-refs\n+~~~~~~~\n \n `ls-refs` is the command used to request a reference advertisement in v2.\n Unlike the current reference advertisement, ls-refs takes in arguments\n@@ -199,8 +199,8 @@ The output of ls-refs is as follows:\n     symref = \"symref-target:\" symref-target\n     peeled = \"peeled:\" obj-id\n \n- fetch\n-~~~~~~~\n+fetch\n+~~~~~\n \n `fetch` is the command used to fetch a packfile in v2.  It can be looked\n at as a modified version of the v1 fetch where the ref-advertisement is\n@@ -444,8 +444,8 @@ header.\n \t\t2 - progress messages\n \t\t3 - fatal error message just before stream aborts\n \n- server-option\n-~~~~~~~~~~~~~~~\n+server-option\n+~~~~~~~~~~~~~\n \n If advertised, indicates that any number of server specific options can be\n included in a request.  This is done by sending each option as a\n-- \n2.21.0.539.g07239c3a71.dirty\n\n"},{"id":"372372","messageId":"20190324155812.GI22459@szeder.dev","threadId":"50814","inReplyTo":"20190324155219.2284-3-szeder.dev@gmail.com","subject":"Re: [PATCH 3/3] Documentation/technical/protocol-v2.txt: fix formatting","fromName":"SZEDER Gábor","fromEmail":"szeder.dev@gmail.com","sentAt":"2019-03-24T15:58:12Z","receivedAt":"2019-03-24T15:58:21Z","isPatch":true,"sender":{"key":"szeder.dev@gmail.com","avatar":"https://avatars.githubusercontent.com/u/116324?v=4"},"body":"On Sun, Mar 24, 2019 at 04:52:19PM +0100, SZEDER Gábor wrote:\n> Some more recent versions of Asciidoctor issue the following warning\n> while building the documentation:\n> \n>       ASCIIDOC technical/protocol-v2.html\n>   asciidoctor: WARNING: protocol-v2.txt: line 38: unterminated listing block\n> \n> This highlights an issue where the 'Initial Client Request' header is\n> not rendered as a header but in monospace.  I'm not sure what exactly\n> causes this issue and why it's an issue only with this particular\n> header, but all headers in 'protocol-v2.txt' are written like this:\n> \n>    Initial Client Request\n>   ------------------------\n> \n> i.e. the header itself is indented by a space, and the \"underline\"\n\nHrm, I don't know where the rest of the sentence went, probably some\nunnoticed mishap during rebase/reword...  Anyway, it should read:\n\n  i.e. the header itself is indented by a space, and the \"underline\" is\n  two characters longer than the header.\n\n> Dropping that indentation and making the length of the underline match\n> the length of the header apparently fixes this issue.\n> \n> While at it, adjust all other headers 'protocol-v2.txt' as well, to\n> match the style we use everywhere else.\n> \n> The page rendered with AsciiDoc doesn't have this formatting issue.\n> \n> Signed-off-by: SZEDER Gábor <szeder.dev@gmail.com>\n> ---\n>  Documentation/technical/protocol-v2.txt | 52 ++++++++++++-------------\n>  1 file changed, 26 insertions(+), 26 deletions(-)\n> \n> diff --git a/Documentation/technical/protocol-v2.txt b/Documentation/technical/protocol-v2.txt\n> index ead85ce35c..03264c7d9a 100644\n> --- a/Documentation/technical/protocol-v2.txt\n> +++ b/Documentation/technical/protocol-v2.txt\n> @@ -1,5 +1,5 @@\n> - Git Wire Protocol, Version 2\n> -==============================\n> +Git Wire Protocol, Version 2\n> +============================\n>  \n>  This document presents a specification for a version 2 of Git's wire\n>  protocol.  Protocol v2 will improve upon v1 in the following ways:\n> @@ -22,8 +22,8 @@ will be commands which a client can request be executed.  Once a command\n>  has completed, a client can reuse the connection and request that other\n>  commands be executed.\n>  \n> - Packet-Line Framing\n> ----------------------\n> +Packet-Line Framing\n> +-------------------\n>  \n>  All communication is done using packet-line framing, just as in v1.  See\n>  `Documentation/technical/pack-protocol.txt` and\n> @@ -34,8 +34,8 @@ In protocol v2 these special packets will have the following semantics:\n>    * '0000' Flush Packet (flush-pkt) - indicates the end of a message\n>    * '0001' Delimiter Packet (delim-pkt) - separates sections of a message\n>  \n> - Initial Client Request\n> -------------------------\n> +Initial Client Request\n> +----------------------\n>  \n>  In general a client can request to speak protocol v2 by sending\n>  `version=2` through the respective side-channel for the transport being\n> @@ -43,22 +43,22 @@ used which inevitably sets `GIT_PROTOCOL`.  More information can be\n>  found in `pack-protocol.txt` and `http-protocol.txt`.  In all cases the\n>  response from the server is the capability advertisement.\n>  \n> - Git Transport\n> -~~~~~~~~~~~~~~~\n> +Git Transport\n> +~~~~~~~~~~~~~\n>  \n>  When using the git:// transport, you can request to use protocol v2 by\n>  sending \"version=2\" as an extra parameter:\n>  \n>     003egit-upload-pack /project.git\\0host=myserver.com\\0\\0version=2\\0\n>  \n> - SSH and File Transport\n> -~~~~~~~~~~~~~~~~~~~~~~~~\n> +SSH and File Transport\n> +~~~~~~~~~~~~~~~~~~~~~~\n>  \n>  When using either the ssh:// or file:// transport, the GIT_PROTOCOL\n>  environment variable must be set explicitly to include \"version=2\".\n>  \n> - HTTP Transport\n> -~~~~~~~~~~~~~~~~\n> +HTTP Transport\n> +~~~~~~~~~~~~~~\n>  \n>  When using the http:// or https:// transport a client makes a \"smart\"\n>  info/refs request as described in `http-protocol.txt` and requests that\n> @@ -79,8 +79,8 @@ A v2 server would reply:\n>  Subsequent requests are then made directly to the service\n>  `$GIT_URL/git-upload-pack`. (This works the same for git-receive-pack).\n>  \n> - Capability Advertisement\n> ---------------------------\n> +Capability Advertisement\n> +------------------------\n>  \n>  A server which decides to communicate (based on a request from a client)\n>  using protocol version 2, notifies the client by sending a version string\n> @@ -101,8 +101,8 @@ to be executed by the client.\n>      key = 1*(ALPHA | DIGIT | \"-_\")\n>      value = 1*(ALPHA | DIGIT | \" -_.,?\\/{}[]()<>!@#$%^&*+=:;\")\n>  \n> - Command Request\n> ------------------\n> +Command Request\n> +---------------\n>  \n>  After receiving the capability advertisement, a client can then issue a\n>  request to select the command it wants with any particular capabilities\n> @@ -137,8 +137,8 @@ command be executed or can terminate the connection.  A client may\n>  optionally send an empty request consisting of just a flush-pkt to\n>  indicate that no more requests will be made.\n>  \n> - Capabilities\n> ---------------\n> +Capabilities\n> +------------\n>  \n>  There are two different types of capabilities: normal capabilities,\n>  which can be used to to convey information or alter the behavior of a\n> @@ -153,8 +153,8 @@ management on the server side in order to function correctly.  This\n>  permits simple round-robin load-balancing on the server side, without\n>  needing to worry about state management.\n>  \n> - agent\n> -~~~~~~~\n> +agent\n> +~~~~~\n>  \n>  The server can advertise the `agent` capability with a value `X` (in the\n>  form `agent=X`) to notify the client that the server is running version\n> @@ -168,8 +168,8 @@ printable ASCII characters except space (i.e., the byte range 32 < x <\n>  and debugging purposes, and MUST NOT be used to programmatically assume\n>  the presence or absence of particular features.\n>  \n> - ls-refs\n> -~~~~~~~~~\n> +ls-refs\n> +~~~~~~~\n>  \n>  `ls-refs` is the command used to request a reference advertisement in v2.\n>  Unlike the current reference advertisement, ls-refs takes in arguments\n> @@ -199,8 +199,8 @@ The output of ls-refs is as follows:\n>      symref = \"symref-target:\" symref-target\n>      peeled = \"peeled:\" obj-id\n>  \n> - fetch\n> -~~~~~~~\n> +fetch\n> +~~~~~\n>  \n>  `fetch` is the command used to fetch a packfile in v2.  It can be looked\n>  at as a modified version of the v1 fetch where the ref-advertisement is\n> @@ -444,8 +444,8 @@ header.\n>  \t\t2 - progress messages\n>  \t\t3 - fatal error message just before stream aborts\n>  \n> - server-option\n> -~~~~~~~~~~~~~~~\n> +server-option\n> +~~~~~~~~~~~~~\n>  \n>  If advertised, indicates that any number of server specific options can be\n>  included in a request.  This is done by sending each option as a\n> -- \n> 2.21.0.539.g07239c3a71.dirty\n> \n"},{"id":"372378","messageId":"20190324215534.9495-1-szeder.dev@gmail.com","threadId":"50814","inReplyTo":"20190324155219.2284-1-szeder.dev@gmail.com","subject":"[PATCH v2 0/6] Asciidoctor-related formatting and CI fixes","fromName":"SZEDER Gábor","fromEmail":"szeder.dev@gmail.com","sentAt":"2019-03-24T21:55:28Z","receivedAt":"2019-03-24T21:55:51Z","isPatch":true,"sender":{"key":"szeder.dev@gmail.com","avatar":"https://avatars.githubusercontent.com/u/116324?v=4"},"body":"The first three patches fix formatting issues with Asciidoctor; they\nare the same patches that I sent earlier today, except some commit\nmessage updates (now they mention the Asciidoctor version which\nstarted to issue the warning, and I fixed that missing half-sentence\nin one of the commit messages).\n\nThe last three patches are a small cleanup and fixes to the\ndocumentation CI build jobs; notably patch 5 un-breaks the\ndocumentation build job on Travis CI in the era of Asciidoctor v2.0.0\n[1], and patch 5 fixes some forever-broken checks.\n\nThe formatting and CI fixes are not really related, but the check\nfixed in patch 6 would choke without the formatting fixes silencing\nwarnings from Asciidoctor, that's why I send them in the same patch\nseries.\n\n[1] https://public-inbox.org/git/20190324162131.GL4047@pobox.com/\n\n\n\nSZEDER Gábor (6):\n  Documentation/git-diff-tree.txt: fix formatting\n  Documentation/technical/api-config.txt: fix formatting\n  Documentation/technical/protocol-v2.txt: fix formatting\n  ci: install Asciidoctor in 'ci/install-dependencies.sh'\n  ci: stick with Asciidoctor v1.5.8 for now\n  ci: fix AsciiDoc/Asciidoctor stderr check in the documentation build\n    job\n\n Documentation/git-diff-tree.txt         |  1 +\n Documentation/technical/api-config.txt  |  2 +-\n Documentation/technical/protocol-v2.txt | 52 ++++++++++++-------------\n ci/install-dependencies.sh              |  3 ++\n ci/test-documentation.sh                | 15 ++++---\n 5 files changed, 38 insertions(+), 35 deletions(-)\n\n-- \n2.21.0.539.g07239c3a71.dirty\n\n"},{"id":"372379","messageId":"20190324215534.9495-2-szeder.dev@gmail.com","threadId":"50814","inReplyTo":"20190324215534.9495-1-szeder.dev@gmail.com","subject":"[PATCH v2 1/6] Documentation/git-diff-tree.txt: fix formatting","fromName":"SZEDER Gábor","fromEmail":"szeder.dev@gmail.com","sentAt":"2019-03-24T21:55:29Z","receivedAt":"2019-03-24T21:55:53Z","isPatch":true,"sender":{"key":"szeder.dev@gmail.com","avatar":"https://avatars.githubusercontent.com/u/116324?v=4"},"body":"Asciidoctor versions v1.5.7 or later print the following warning while\nbuilding the documentation:\n\n      ASCIIDOC git-diff-tree.xml\n  asciidoctor: WARNING: diff-format.txt: line 2: unterminated listing block\n\nThis highlights an issue (even with older Asciidoctor versions) where\nthe \"Raw output format\" header is not rendered as a header, and the\nrest of the document is rendered in monospace.  This is not caused by\n'diff-format.txt' in itself, but rather by 'git-diff-tree.txt'\nincluding 'pretty-formats.txt' and 'diff-format.txt' on subsequent\nlines, while the former happens to end with monospace-formatted\nexample commands.\n\nFix this by inserting an empty line between the two include::\ndirectives.\n\nThe page rendered with AsciiDoc doesn't have this formatting issue.\n\nSigned-off-by: SZEDER Gábor <szeder.dev@gmail.com>\n---\n Documentation/git-diff-tree.txt | 1 +\n 1 file changed, 1 insertion(+)\n\ndiff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt\nindex 24f32e8c54..5c8a2a5e97 100644\n--- a/Documentation/git-diff-tree.txt\n+++ b/Documentation/git-diff-tree.txt\n@@ -118,6 +118,7 @@ include::pretty-options.txt[]\n \n \n include::pretty-formats.txt[]\n+\n include::diff-format.txt[]\n \n GIT\n-- \n2.21.0.539.g07239c3a71.dirty\n\n"},{"id":"372380","messageId":"20190324215534.9495-3-szeder.dev@gmail.com","threadId":"50814","inReplyTo":"20190324215534.9495-1-szeder.dev@gmail.com","subject":"[PATCH v2 2/6] Documentation/technical/api-config.txt: fix formatting","fromName":"SZEDER Gábor","fromEmail":"szeder.dev@gmail.com","sentAt":"2019-03-24T21:55:30Z","receivedAt":"2019-03-24T21:55:53Z","isPatch":true,"sender":{"key":"szeder.dev@gmail.com","avatar":"https://avatars.githubusercontent.com/u/116324?v=4"},"body":"Asciidoctor versions v1.5.7 or later print the following warning while\nbuilding the documentation:\n\n      ASCIIDOC technical/api-config.html\n  asciidoctor: WARNING: api-config.txt: line 232: unterminated listing block\n\nThis highlight an issue (even with older Asciidoctor versions) where\nthe length of the '----' lines surrounding a code example don't match,\nand the rest of the document is rendered in monospace.\n\nFix this by making sure that the length of those lines match.\n\nThe page rendered with AsciiDoc doesn't have this formatting issue.\n\nSigned-off-by: SZEDER Gábor <szeder.dev@gmail.com>\n---\n Documentation/technical/api-config.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt\nindex fa39ac9d71..7d20716c32 100644\n--- a/Documentation/technical/api-config.txt\n+++ b/Documentation/technical/api-config.txt\n@@ -229,7 +229,7 @@ A `config_set` can be used to construct an in-memory cache for\n config-like files that the caller specifies (i.e., files like `.gitmodules`,\n `~/.gitconfig` etc.). For example,\n \n----------------------------------------\n+----------------------------------------\n struct config_set gm_config;\n git_configset_init(&gm_config);\n int b;\n-- \n2.21.0.539.g07239c3a71.dirty\n\n"},{"id":"372381","messageId":"20190324215534.9495-4-szeder.dev@gmail.com","threadId":"50814","inReplyTo":"20190324215534.9495-1-szeder.dev@gmail.com","subject":"[PATCH v2 3/6] Documentation/technical/protocol-v2.txt: fix formatting","fromName":"SZEDER Gábor","fromEmail":"szeder.dev@gmail.com","sentAt":"2019-03-24T21:55:31Z","receivedAt":"2019-03-24T21:55:55Z","isPatch":true,"sender":{"key":"szeder.dev@gmail.com","avatar":"https://avatars.githubusercontent.com/u/116324?v=4"},"body":"Asciidoctor versions v1.5.7 or later print the following warning while\nbuilding the documentation:\n\n      ASCIIDOC technical/protocol-v2.html\n  asciidoctor: WARNING: protocol-v2.txt: line 38: unterminated listing block\n\nThis highlights an issue (even with older Asciidoctor versions) where\nthe 'Initial Client Request' header is not rendered as a header but in\nmonospace.  I'm not sure what exactly causes this issue and why it's\nan issue only with this particular header, but all headers in\n'protocol-v2.txt' are written like this:\n\n   Initial Client Request\n  ------------------------\n\ni.e. the header itself is indented by a space, and the \"underline\" is\ntwo characters longer than the header.\n\nDropping that indentation and making the length of the underline match\nthe length of the header apparently fixes this issue.\n\nWhile at it, adjust all other headers 'protocol-v2.txt' as well, to\nmatch the style we use everywhere else.\n\nThe page rendered with AsciiDoc doesn't have this formatting issue.\n\nSigned-off-by: SZEDER Gábor <szeder.dev@gmail.com>\n---\n Documentation/technical/protocol-v2.txt | 52 ++++++++++++-------------\n 1 file changed, 26 insertions(+), 26 deletions(-)\n\ndiff --git a/Documentation/technical/protocol-v2.txt b/Documentation/technical/protocol-v2.txt\nindex ead85ce35c..03264c7d9a 100644\n--- a/Documentation/technical/protocol-v2.txt\n+++ b/Documentation/technical/protocol-v2.txt\n@@ -1,5 +1,5 @@\n- Git Wire Protocol, Version 2\n-==============================\n+Git Wire Protocol, Version 2\n+============================\n \n This document presents a specification for a version 2 of Git's wire\n protocol.  Protocol v2 will improve upon v1 in the following ways:\n@@ -22,8 +22,8 @@ will be commands which a client can request be executed.  Once a command\n has completed, a client can reuse the connection and request that other\n commands be executed.\n \n- Packet-Line Framing\n----------------------\n+Packet-Line Framing\n+-------------------\n \n All communication is done using packet-line framing, just as in v1.  See\n `Documentation/technical/pack-protocol.txt` and\n@@ -34,8 +34,8 @@ In protocol v2 these special packets will have the following semantics:\n   * '0000' Flush Packet (flush-pkt) - indicates the end of a message\n   * '0001' Delimiter Packet (delim-pkt) - separates sections of a message\n \n- Initial Client Request\n-------------------------\n+Initial Client Request\n+----------------------\n \n In general a client can request to speak protocol v2 by sending\n `version=2` through the respective side-channel for the transport being\n@@ -43,22 +43,22 @@ used which inevitably sets `GIT_PROTOCOL`.  More information can be\n found in `pack-protocol.txt` and `http-protocol.txt`.  In all cases the\n response from the server is the capability advertisement.\n \n- Git Transport\n-~~~~~~~~~~~~~~~\n+Git Transport\n+~~~~~~~~~~~~~\n \n When using the git:// transport, you can request to use protocol v2 by\n sending \"version=2\" as an extra parameter:\n \n    003egit-upload-pack /project.git\\0host=myserver.com\\0\\0version=2\\0\n \n- SSH and File Transport\n-~~~~~~~~~~~~~~~~~~~~~~~~\n+SSH and File Transport\n+~~~~~~~~~~~~~~~~~~~~~~\n \n When using either the ssh:// or file:// transport, the GIT_PROTOCOL\n environment variable must be set explicitly to include \"version=2\".\n \n- HTTP Transport\n-~~~~~~~~~~~~~~~~\n+HTTP Transport\n+~~~~~~~~~~~~~~\n \n When using the http:// or https:// transport a client makes a \"smart\"\n info/refs request as described in `http-protocol.txt` and requests that\n@@ -79,8 +79,8 @@ A v2 server would reply:\n Subsequent requests are then made directly to the service\n `$GIT_URL/git-upload-pack`. (This works the same for git-receive-pack).\n \n- Capability Advertisement\n---------------------------\n+Capability Advertisement\n+------------------------\n \n A server which decides to communicate (based on a request from a client)\n using protocol version 2, notifies the client by sending a version string\n@@ -101,8 +101,8 @@ to be executed by the client.\n     key = 1*(ALPHA | DIGIT | \"-_\")\n     value = 1*(ALPHA | DIGIT | \" -_.,?\\/{}[]()<>!@#$%^&*+=:;\")\n \n- Command Request\n------------------\n+Command Request\n+---------------\n \n After receiving the capability advertisement, a client can then issue a\n request to select the command it wants with any particular capabilities\n@@ -137,8 +137,8 @@ command be executed or can terminate the connection.  A client may\n optionally send an empty request consisting of just a flush-pkt to\n indicate that no more requests will be made.\n \n- Capabilities\n---------------\n+Capabilities\n+------------\n \n There are two different types of capabilities: normal capabilities,\n which can be used to to convey information or alter the behavior of a\n@@ -153,8 +153,8 @@ management on the server side in order to function correctly.  This\n permits simple round-robin load-balancing on the server side, without\n needing to worry about state management.\n \n- agent\n-~~~~~~~\n+agent\n+~~~~~\n \n The server can advertise the `agent` capability with a value `X` (in the\n form `agent=X`) to notify the client that the server is running version\n@@ -168,8 +168,8 @@ printable ASCII characters except space (i.e., the byte range 32 < x <\n and debugging purposes, and MUST NOT be used to programmatically assume\n the presence or absence of particular features.\n \n- ls-refs\n-~~~~~~~~~\n+ls-refs\n+~~~~~~~\n \n `ls-refs` is the command used to request a reference advertisement in v2.\n Unlike the current reference advertisement, ls-refs takes in arguments\n@@ -199,8 +199,8 @@ The output of ls-refs is as follows:\n     symref = \"symref-target:\" symref-target\n     peeled = \"peeled:\" obj-id\n \n- fetch\n-~~~~~~~\n+fetch\n+~~~~~\n \n `fetch` is the command used to fetch a packfile in v2.  It can be looked\n at as a modified version of the v1 fetch where the ref-advertisement is\n@@ -444,8 +444,8 @@ header.\n \t\t2 - progress messages\n \t\t3 - fatal error message just before stream aborts\n \n- server-option\n-~~~~~~~~~~~~~~~\n+server-option\n+~~~~~~~~~~~~~\n \n If advertised, indicates that any number of server specific options can be\n included in a request.  This is done by sending each option as a\n-- \n2.21.0.539.g07239c3a71.dirty\n\n"},{"id":"372382","messageId":"20190324215534.9495-5-szeder.dev@gmail.com","threadId":"50814","inReplyTo":"20190324215534.9495-1-szeder.dev@gmail.com","subject":"[PATCH v2 4/6] ci: install Asciidoctor in 'ci/install-dependencies.sh'","fromName":"SZEDER Gábor","fromEmail":"szeder.dev@gmail.com","sentAt":"2019-03-24T21:55:32Z","receivedAt":"2019-03-24T21:55:55Z","isPatch":true,"sender":{"key":"szeder.dev@gmail.com","avatar":"https://avatars.githubusercontent.com/u/116324?v=4"},"body":"When our '.travis.yml' was split into several 'ci/*' scripts [1], the\ninstallation of the 'asciidoctor' gem somehow ended up in\n'ci/test-documentation.sh'.\n\nInstall it in 'ci/install-dependencies.sh', where we install\neverything else.\n\n[1] 657343a602 (travis-ci: move Travis CI code into dedicated scripts,\n    2017-09-10)\n\nSigned-off-by: SZEDER Gábor <szeder.dev@gmail.com>\n---\n ci/install-dependencies.sh | 3 +++\n ci/test-documentation.sh   | 3 ---\n 2 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/ci/install-dependencies.sh b/ci/install-dependencies.sh\nindex d64667fcbf..76ec308965 100755\n--- a/ci/install-dependencies.sh\n+++ b/ci/install-dependencies.sh\n@@ -54,6 +54,9 @@ StaticAnalysis)\n Documentation)\n \tsudo apt-get -q update\n \tsudo apt-get -q -y install asciidoc xmlto\n+\n+\ttest -n \"$ALREADY_HAVE_ASCIIDOCTOR\" ||\n+\tgem install asciidoctor\n \t;;\n esac\n \ndiff --git a/ci/test-documentation.sh b/ci/test-documentation.sh\nindex be3b7d376a..8f91f48c81 100755\n--- a/ci/test-documentation.sh\n+++ b/ci/test-documentation.sh\n@@ -5,9 +5,6 @@\n \n . ${0%/*}/lib.sh\n \n-test -n \"$ALREADY_HAVE_ASCIIDOCTOR\" ||\n-gem install asciidoctor\n-\n make check-builtins\n make check-docs\n \n-- \n2.21.0.539.g07239c3a71.dirty\n\n"},{"id":"372383","messageId":"20190324215534.9495-7-szeder.dev@gmail.com","threadId":"50814","inReplyTo":"20190324215534.9495-1-szeder.dev@gmail.com","subject":"[PATCH v2 6/6] ci: fix AsciiDoc/Asciidoctor stderr check in the documentation build job","fromName":"SZEDER Gábor","fromEmail":"szeder.dev@gmail.com","sentAt":"2019-03-24T21:55:34Z","receivedAt":"2019-03-24T21:55:58Z","isPatch":true,"sender":{"key":"szeder.dev@gmail.com","avatar":"https://avatars.githubusercontent.com/u/116324?v=4"},"body":"In our 'ci/*' build scripts we rely on 'set -e' aborting the build job\nwhen a command exits with error, while in 'ci/test-documentation.sh'\nwe tried to check the emptiness of AsciiDoc's and Asciidoctor's\nstandard error with '! test -s stderr.log'.  Unfortunately, the\ncombination of the two doesn't work as intended, because, according to\nPOSIX [1]:\n\n  \"The -e setting shall be ignored when executing [...] a pipeline\n  beginning with the ! reserved word\" [2]\n\nWatch and learn:\n\n  $ cat e.sh\n  #!/bin/sh\n  set -ex\n  echo unexpected >file\n  ! test -s file\n  test ! -s file\n  echo \"should not reach this\"\n  $ ./e.sh\n  + echo unexpected\n  + test -s file\n  + test ! -s file\n  $\n\nThis is why we haven't noticed the warnings from Asciidoctor that were\nfixed in the first patches of this patch series, though some of them\nwere already there in the build of v2.18.0-rc0 [3].\n\nCheck the emptiness of that file with 'test ! -s' instead, which works\nproperly with 'set -e'.  Furthermore, dump the contents of that file\nto the log for our convenience, so if it were to unexpectedly end up\nbeing non-empty, then we wouldn't have to scroll through all that long\nbuild log looking for warnings, but could see them right away near the\nend of the log.\n\nAnd one more thing: we build the docs with Asciidoctor right after a\n'make clean', meaning that 'make doc' starts with running\n'GIT-VERSION-GEN', which in turn prints the version to its standard\nerror.  This version then goes to 'stderr.log' as well, and a 'sed'\ncommand is supposed to remove it to prevent it from interfering with\nthat (previously defunct) emptiness check.  Alas, this command doesn't\nwork as intended, either, because it leaves the file to be checked\nintact, but the defunct emptiness check hid this issue, too...  This\npatch deals with this as well.\n\n[1] http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#set\n\n[2] POSIX doesn't discuss the meaning of '! cmd' in case of simple\n    commands, but it defines that \"A pipeline is a sequence of one or\n    more commands separated by the control operator '|'\", so\n    apparently a simple command is considered as pipeline as well.\n\n    http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_09_02\n\n[3] https://travis-ci.org/git/git/jobs/385932007#L1463\n\nSigned-off-by: SZEDER Gábor <szeder.dev@gmail.com>\n---\n ci/test-documentation.sh | 12 +++++++-----\n 1 file changed, 7 insertions(+), 5 deletions(-)\n\ndiff --git a/ci/test-documentation.sh b/ci/test-documentation.sh\nindex 8f91f48c81..bd4a65e933 100755\n--- a/ci/test-documentation.sh\n+++ b/ci/test-documentation.sh\n@@ -10,7 +10,8 @@ make check-docs\n \n # Build docs with AsciiDoc\n make doc > >(tee stdout.log) 2> >(tee stderr.log >&2)\n-! test -s stderr.log\n+cat stderr.log\n+test ! -s stderr.log\n test -s Documentation/git.html\n test -s Documentation/git.xml\n test -s Documentation/git.1\n@@ -21,13 +22,14 @@ check_unignored_build_artifacts\n \n # Build docs with AsciiDoctor\n make clean\n-make USE_ASCIIDOCTOR=1 doc > >(tee stdout.log) 2> >(tee stderr.log >&2)\n-sed '/^GIT_VERSION = / d' stderr.log\n-! test -s stderr.log\n+make USE_ASCIIDOCTOR=1 doc > >(tee stdout.log) 2> >(tee stderr.raw >&2)\n+sed '/^GIT_VERSION = / d' stderr.raw >stderr.log\n+cat stderr.log\n+test ! -s stderr.log\n test -s Documentation/git.html\n grep '<meta name=\"generator\" content=\"Asciidoctor ' Documentation/git.html\n \n-rm -f stdout.log stderr.log\n+rm -f stdout.log stderr.log stderr.raw\n check_unignored_build_artifacts\n \n save_good_tree\n-- \n2.21.0.539.g07239c3a71.dirty\n\n"},{"id":"372384","messageId":"20190324215534.9495-6-szeder.dev@gmail.com","threadId":"50814","inReplyTo":"20190324215534.9495-1-szeder.dev@gmail.com","subject":"[PATCH v2 5/6] ci: stick with Asciidoctor v1.5.8 for now","fromName":"SZEDER Gábor","fromEmail":"szeder.dev@gmail.com","sentAt":"2019-03-24T21:55:33Z","receivedAt":"2019-03-24T21:55:59Z","isPatch":true,"sender":{"key":"szeder.dev@gmail.com","avatar":"https://avatars.githubusercontent.com/u/116324?v=4"},"body":"The release of Asciidoctor v2.0.0 two days ago broke our documentation\nbuild job on Travis CI, where we 'gem install asciidoctor', which\nalways brings us the latest and (supposedly) greatest.  Alas, we are\nnot ready for that just yet, because it removed support for DocBook\n4.5, and we have been requiring that particular DocBook version to\nbuild 'user-manual.xml' with Asciidoctor, resulting in:\n\n      ASCIIDOC user-manual.xml\n  asciidoctor: FAILED: missing converter for backend 'docbook45'. Processing aborted.\n    Use --trace for backtrace\n  make[1]: *** [user-manual.xml] Error 1\n\nUnfortunately, we can't simply switch to DocBook 5 right away, as\ndoing so leads to validation errors from 'xmlto', and working around\nthose leads to yet another errors... [1]\n\nSo let's stick with Asciidoctor v1.5.8 (latest stable release before\nv2.0.0) in our documentation build job on Travis CI for now, until we\nfigure out how to deal with the fallout from Asciidoctor v2.0.0.\n\n[1] https://public-inbox.org/git/20190324162131.GL4047@pobox.com/\n\nSigned-off-by: SZEDER Gábor <szeder.dev@gmail.com>\n---\n ci/install-dependencies.sh | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/ci/install-dependencies.sh b/ci/install-dependencies.sh\nindex 76ec308965..52a44c690a 100755\n--- a/ci/install-dependencies.sh\n+++ b/ci/install-dependencies.sh\n@@ -56,7 +56,7 @@ Documentation)\n \tsudo apt-get -q -y install asciidoc xmlto\n \n \ttest -n \"$ALREADY_HAVE_ASCIIDOCTOR\" ||\n-\tgem install asciidoctor\n+\tgem install --version 1.5.8 asciidoctor\n \t;;\n esac\n \n-- \n2.21.0.539.g07239c3a71.dirty\n\n"},{"id":"372474","messageId":"nycvar.QRO.7.76.6.1903252221300.41@tvgsbejvaqbjf.bet","threadId":"50814","inReplyTo":"20190324215534.9495-5-szeder.dev@gmail.com","subject":"Re: [PATCH v2 4/6] ci: install Asciidoctor in 'ci/install-dependencies.sh'","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2019-03-25T21:28:21Z","receivedAt":"2019-03-25T21:28:54Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nI like the rest of the patch series, but this patch, I am not so sure\nabout...\n\nOn Sun, 24 Mar 2019, SZEDER Gábor wrote:\n\n> When our '.travis.yml' was split into several 'ci/*' scripts [1], the\n> installation of the 'asciidoctor' gem somehow ended up in\n> 'ci/test-documentation.sh'.\n>\n> Install it in 'ci/install-dependencies.sh', where we install\n> everything else.\n\nThe big difference you introduce is that asciidoctor is now installed\nwith every job, not only with the Documentation job that actually uses it.\n\nEven if it affects me very little (because I don't pay much attention to\nTravis, it's been too flakey for me, and it does not test our Windows\nside, and it is too slow), I'd rather install asciidoctor really only when\nneeded.\n\nSo I'd like to recommend to drop this patch from the series.\n\nThanks,\nDscho\n\n>\n> [1] 657343a602 (travis-ci: move Travis CI code into dedicated scripts,\n>     2017-09-10)\n>\n> Signed-off-by: SZEDER Gábor <szeder.dev@gmail.com>\n> ---\n>  ci/install-dependencies.sh | 3 +++\n>  ci/test-documentation.sh   | 3 ---\n>  2 files changed, 3 insertions(+), 3 deletions(-)\n>\n> diff --git a/ci/install-dependencies.sh b/ci/install-dependencies.sh\n> index d64667fcbf..76ec308965 100755\n> --- a/ci/install-dependencies.sh\n> +++ b/ci/install-dependencies.sh\n> @@ -54,6 +54,9 @@ StaticAnalysis)\n>  Documentation)\n>  \tsudo apt-get -q update\n>  \tsudo apt-get -q -y install asciidoc xmlto\n> +\n> +\ttest -n \"$ALREADY_HAVE_ASCIIDOCTOR\" ||\n> +\tgem install asciidoctor\n>  \t;;\n>  esac\n>\n> diff --git a/ci/test-documentation.sh b/ci/test-documentation.sh\n> index be3b7d376a..8f91f48c81 100755\n> --- a/ci/test-documentation.sh\n> +++ b/ci/test-documentation.sh\n> @@ -5,9 +5,6 @@\n>\n>  . ${0%/*}/lib.sh\n>\n> -test -n \"$ALREADY_HAVE_ASCIIDOCTOR\" ||\n> -gem install asciidoctor\n> -\n>  make check-builtins\n>  make check-docs\n>\n> --\n> 2.21.0.539.g07239c3a71.dirty\n>\n>\n"},{"id":"372482","messageId":"20190325214603.GA1343@szeder.dev","threadId":"50814","inReplyTo":"nycvar.QRO.7.76.6.1903252221300.41@tvgsbejvaqbjf.bet","subject":"Re: [PATCH v2 4/6] ci: install Asciidoctor in 'ci/install-dependencies.sh'","fromName":"SZEDER Gábor","fromEmail":"szeder.dev@gmail.com","sentAt":"2019-03-25T21:46:03Z","receivedAt":"2019-03-25T21:46:12Z","isPatch":true,"sender":{"key":"szeder.dev@gmail.com","avatar":"https://avatars.githubusercontent.com/u/116324?v=4"},"body":"On Mon, Mar 25, 2019 at 10:28:21PM +0100, Johannes Schindelin wrote:\n> Hi,\n> \n> I like the rest of the patch series, but this patch, I am not so sure\n> about...\n> \n> On Sun, 24 Mar 2019, SZEDER Gábor wrote:\n> \n> > When our '.travis.yml' was split into several 'ci/*' scripts [1], the\n> > installation of the 'asciidoctor' gem somehow ended up in\n> > 'ci/test-documentation.sh'.\n> >\n> > Install it in 'ci/install-dependencies.sh', where we install\n> > everything else.\n> \n> The big difference you introduce is that asciidoctor is now installed\n> with every job, not only with the Documentation job that actually uses it.\n\nIt is only installed in the 'Documentation' build job.\n\n> Even if it affects me very little (because I don't pay much attention to\n> Travis, it's been too flakey for me, and it does not test our Windows\n> side, and it is too slow), I'd rather install asciidoctor really only when\n> needed.\n> \n> So I'd like to recommend to drop this patch from the series.\n> \n> Thanks,\n> Dscho\n> \n> >\n> > [1] 657343a602 (travis-ci: move Travis CI code into dedicated scripts,\n> >     2017-09-10)\n> >\n> > Signed-off-by: SZEDER Gábor <szeder.dev@gmail.com>\n> > ---\n> >  ci/install-dependencies.sh | 3 +++\n> >  ci/test-documentation.sh   | 3 ---\n> >  2 files changed, 3 insertions(+), 3 deletions(-)\n> >\n> > diff --git a/ci/install-dependencies.sh b/ci/install-dependencies.sh\n> > index d64667fcbf..76ec308965 100755\n> > --- a/ci/install-dependencies.sh\n> > +++ b/ci/install-dependencies.sh\n> > @@ -54,6 +54,9 @@ StaticAnalysis)\n> >  Documentation)\n\n     ^^^^^^^^^^^^^^\n\n> >  \tsudo apt-get -q update\n> >  \tsudo apt-get -q -y install asciidoc xmlto\n> > +\n> > +\ttest -n \"$ALREADY_HAVE_ASCIIDOCTOR\" ||\n> > +\tgem install asciidoctor\n> >  \t;;\n> >  esac\n> >\n> > diff --git a/ci/test-documentation.sh b/ci/test-documentation.sh\n> > index be3b7d376a..8f91f48c81 100755\n> > --- a/ci/test-documentation.sh\n> > +++ b/ci/test-documentation.sh\n> > @@ -5,9 +5,6 @@\n> >\n> >  . ${0%/*}/lib.sh\n> >\n> > -test -n \"$ALREADY_HAVE_ASCIIDOCTOR\" ||\n> > -gem install asciidoctor\n> > -\n> >  make check-builtins\n> >  make check-docs\n> >\n> > --\n> > 2.21.0.539.g07239c3a71.dirty\n> >\n> >\n\n"},{"id":"372517","messageId":"nycvar.QRO.7.76.6.1903261439090.41@tvgsbejvaqbjf.bet","threadId":"50814","inReplyTo":"20190325214603.GA1343@szeder.dev","subject":"Re: [PATCH v2 4/6] ci: install Asciidoctor in 'ci/install-dependencies.sh'","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2019-03-26T13:41:20Z","receivedAt":"2019-03-26T13:41:57Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi Gábor,\n\nOn Mon, 25 Mar 2019, SZEDER Gábor wrote:\n\n> On Mon, Mar 25, 2019 at 10:28:21PM +0100, Johannes Schindelin wrote:\n>\n> > I like the rest of the patch series, but this patch, I am not so sure\n> > about...\n> >\n> > On Sun, 24 Mar 2019, SZEDER Gábor wrote:\n> >\n> > > When our '.travis.yml' was split into several 'ci/*' scripts [1], the\n> > > installation of the 'asciidoctor' gem somehow ended up in\n> > > 'ci/test-documentation.sh'.\n> > >\n> > > Install it in 'ci/install-dependencies.sh', where we install\n> > > everything else.\n> >\n> > The big difference you introduce is that asciidoctor is now installed\n> > with every job, not only with the Documentation job that actually uses it.\n>\n> It is only installed in the 'Documentation' build job.\n\nOy, you're right!\n\n> > Even if it affects me very little (because I don't pay much attention to\n> > Travis, it's been too flakey for me, and it does not test our Windows\n> > side, and it is too slow), I'd rather install asciidoctor really only when\n> > needed.\n> >\n> > So I'd like to recommend to drop this patch from the series.\n> >\n> > [...]\n> >\n> > > diff --git a/ci/install-dependencies.sh b/ci/install-dependencies.sh\n> > > index d64667fcbf..76ec308965 100755\n> > > --- a/ci/install-dependencies.sh\n> > > +++ b/ci/install-dependencies.sh\n> > > @@ -54,6 +54,9 @@ StaticAnalysis)\n> > >  Documentation)\n>\n>      ^^^^^^^^^^^^^^\n\nTo be honest, I think it was kind of easy to miss that. Maybe the commit\nmessage could talk about this, so that future Dscho will have a helpful\nhint when looking at the commit history and stumbling over this move?\n\nIf you could add that hint, I would be most grateful.\n\nIn any case, based on what you taught me I retract my objection to this\npatch.\n\nThanks,\nDscho\n\n>\n> > >  \tsudo apt-get -q update\n> > >  \tsudo apt-get -q -y install asciidoc xmlto\n> > > +\n> > > +\ttest -n \"$ALREADY_HAVE_ASCIIDOCTOR\" ||\n> > > +\tgem install asciidoctor\n> > >  \t;;\n> > >  esac\n> > >\n> > > diff --git a/ci/test-documentation.sh b/ci/test-documentation.sh\n> > > index be3b7d376a..8f91f48c81 100755\n> > > --- a/ci/test-documentation.sh\n> > > +++ b/ci/test-documentation.sh\n> > > @@ -5,9 +5,6 @@\n> > >\n> > >  . ${0%/*}/lib.sh\n> > >\n> > > -test -n \"$ALREADY_HAVE_ASCIIDOCTOR\" ||\n> > > -gem install asciidoctor\n> > > -\n> > >  make check-builtins\n> > >  make check-docs\n> > >\n> > > --\n> > > 2.21.0.539.g07239c3a71.dirty\n> > >\n> > >\n>\n>\n"},{"id":"372529","messageId":"20190326162427.GB29627@sigill.intra.peff.net","threadId":"50814","inReplyTo":"20190324215534.9495-1-szeder.dev@gmail.com","subject":"Re: [PATCH v2 0/6] Asciidoctor-related formatting and CI fixes","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2019-03-26T16:24:27Z","receivedAt":"2019-03-26T16:24:31Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sun, Mar 24, 2019 at 10:55:28PM +0100, SZEDER Gábor wrote:\n\n> The first three patches fix formatting issues with Asciidoctor; they\n> are the same patches that I sent earlier today, except some commit\n> message updates (now they mention the Asciidoctor version which\n> started to issue the warning, and I fixed that missing half-sentence\n> in one of the commit messages).\n> \n> The last three patches are a small cleanup and fixes to the\n> documentation CI build jobs; notably patch 5 un-breaks the\n> documentation build job on Travis CI in the era of Asciidoctor v2.0.0\n> [1], and patch 5 fixes some forever-broken checks.\n> \n> The formatting and CI fixes are not really related, but the check\n> fixed in patch 6 would choke without the formatting fixes silencing\n> warnings from Asciidoctor, that's why I send them in the same patch\n> series.\n\nThanks, these all look good to me (I do agree with Dscho that the\n\"Documentation\" subtlety in patch 4 might be worth calling out in the\ncommit message).\n\n-Peff\n"},{"id":"372688","messageId":"20190329123520.27549-1-szeder.dev@gmail.com","threadId":"50814","inReplyTo":"20190324215534.9495-1-szeder.dev@gmail.com","subject":"[PATCH v3 0/6] Asciidoctor-related formatting and CI fixes","fromName":"SZEDER Gábor","fromEmail":"szeder.dev@gmail.com","sentAt":"2019-03-29T12:35:14Z","receivedAt":"2019-03-29T12:35:35Z","isPatch":true,"sender":{"key":"szeder.dev@gmail.com","avatar":"https://avatars.githubusercontent.com/u/116324?v=4"},"body":"The first three patches fix formatting issues with Asciidoctor, while\nthe last three patches are a small cleanup and fixes to the\ndocumentation CI build jobs; notably patch 5 un-breaks the\ndocumentation build job on Travis CI in the era of Asciidoctor v2.0.0\n[1], and patch 6 fixes some forever-broken checks.\n\nChanges since v2:\n\n  - The fixed stderr check in patch 6 is triggered when merged with\n    'pu', in particular with commit 9a71722b4d (Doc: auto-detect\n    changed build flags, 2019-03-17) in\n    'ma/doc-diff-doc-vs-doctor-comparison'.  The changes to patch 6\n    deal with that.\n\n  - Mention in patch 4's commit message that Asciidoctor is still only\n    installed in the Documentation build job.\n\n\n[1] https://public-inbox.org/git/20190324162131.GL4047@pobox.com/\n\n\n\nSZEDER Gábor (6):\n  Documentation/git-diff-tree.txt: fix formatting\n  Documentation/technical/api-config.txt: fix formatting\n  Documentation/technical/protocol-v2.txt: fix formatting\n  ci: install Asciidoctor in 'ci/install-dependencies.sh'\n  ci: stick with Asciidoctor v1.5.8 for now\n  ci: fix AsciiDoc/Asciidoctor stderr check in the documentation build\n    job\n\n Documentation/git-diff-tree.txt         |  1 +\n Documentation/technical/api-config.txt  |  2 +-\n Documentation/technical/protocol-v2.txt | 52 ++++++++++++-------------\n ci/install-dependencies.sh              |  3 ++\n ci/test-documentation.sh                | 24 +++++++-----\n 5 files changed, 46 insertions(+), 36 deletions(-)\n\nRange-diff:\n1:  8026f62876 = 1:  8026f62876 Documentation/git-diff-tree.txt: fix formatting\n2:  fd19cf4b24 = 2:  fd19cf4b24 Documentation/technical/api-config.txt: fix formatting\n3:  638dcd64e9 = 3:  638dcd64e9 Documentation/technical/protocol-v2.txt: fix formatting\n4:  6f8c6ff398 ! 4:  2e94e2b7b6 ci: install Asciidoctor in 'ci/install-dependencies.sh'\n    @@ -6,8 +6,9 @@\n         installation of the 'asciidoctor' gem somehow ended up in\n         'ci/test-documentation.sh'.\n     \n    -    Install it in 'ci/install-dependencies.sh', where we install\n    -    everything else.\n    +    Install it in 'ci/install-dependencies.sh', where we install other\n    +    dependencies of the Documentation build job as well (asciidoc,\n    +    xmlto).\n     \n         [1] 657343a602 (travis-ci: move Travis CI code into dedicated scripts,\n             2017-09-10)\n5:  b9eb371f81 = 5:  95476591dd ci: stick with Asciidoctor v1.5.8 for now\n6:  ba2a005a05 ! 6:  04ee6831fd ci: fix AsciiDoc/Asciidoctor stderr check in the documentation build job\n    @@ -2,51 +2,62 @@\n     \n         ci: fix AsciiDoc/Asciidoctor stderr check in the documentation build job\n     \n    -    In our 'ci/*' build scripts we rely on 'set -e' aborting the build job\n    -    when a command exits with error, while in 'ci/test-documentation.sh'\n    -    we tried to check the emptiness of AsciiDoc's and Asciidoctor's\n    -    standard error with '! test -s stderr.log'.  Unfortunately, the\n    -    combination of the two doesn't work as intended, because, according to\n    -    POSIX [1]:\n    +    In 'ci/test-documentation.sh' we save the standard error of 'make\n    +    doc', and, in an attempt to make sure that neither AsciiDoc nor\n    +    Asciidoctor printed any warnings, we check the emptiness of the\n    +    resulting file with '! test -s stderr.log'.  This check has never\n    +    actually worked, because in our 'ci/*' build scripts we rely on 'set\n    +    -e' aborting the build job when a command exits with error, and,\n    +    unfortunately, the combination of the two doesn't work as intended.\n    +    According to POSIX [1]:\n     \n           \"The -e setting shall be ignored when executing [...] a pipeline\n           beginning with the ! reserved word\" [2]\n     \n         Watch and learn:\n     \n    -      $ cat e.sh\n    -      #!/bin/sh\n    -      set -ex\n    -      echo unexpected >file\n    -      ! test -s file\n    -      test ! -s file\n    -      echo \"should not reach this\"\n    -      $ ./e.sh\n    -      + echo unexpected\n    -      + test -s file\n    -      + test ! -s file\n    -      $\n    +      $ echo unexpected >file\n    +      $ ( set -e; ! test -s file ; echo \"should not reach this\" ) ; echo $?\n    +      should not reach this\n    +      0\n     \n         This is why we haven't noticed the warnings from Asciidoctor that were\n         fixed in the first patches of this patch series, though some of them\n         were already there in the build of v2.18.0-rc0 [3].\n     \n         Check the emptiness of that file with 'test ! -s' instead, which works\n    -    properly with 'set -e'.  Furthermore, dump the contents of that file\n    -    to the log for our convenience, so if it were to unexpectedly end up\n    -    being non-empty, then we wouldn't have to scroll through all that long\n    -    build log looking for warnings, but could see them right away near the\n    -    end of the log.\n    -\n    -    And one more thing: we build the docs with Asciidoctor right after a\n    -    'make clean', meaning that 'make doc' starts with running\n    -    'GIT-VERSION-GEN', which in turn prints the version to its standard\n    -    error.  This version then goes to 'stderr.log' as well, and a 'sed'\n    -    command is supposed to remove it to prevent it from interfering with\n    -    that (previously defunct) emptiness check.  Alas, this command doesn't\n    -    work as intended, either, because it leaves the file to be checked\n    -    intact, but the defunct emptiness check hid this issue, too...  This\n    -    patch deals with this as well.\n    +    properly with 'set -e':\n    +\n    +      $ ( set -e; test ! -s file ; echo \"should not reach this\" ) ; echo $?\n    +      1\n    +\n    +    Furthermore, dump the contents of that file to the log for our\n    +    convenience, so if it were to unexpectedly end up being non-empty,\n    +    then we wouldn't have to scroll through all that long build log\n    +    looking for warnings, but could see them right away near the end of\n    +    the log.\n    +\n    +    Note that we are only really interested in the standard error of\n    +    AsciiDoc and Asciidoctor, but by saving the stderr of 'make doc' we\n    +    also save any error output from the make rules.  Currently there is\n    +    only one such line: we build the docs with Asciidoctor right after a\n    +    'make clean', meaning that 'make USE_ASCIIDOCTOR=1 doc' always starts\n    +    with running 'GIT-VERSION-GEN', which in turn prints the version to\n    +    stderr.  A 'sed' command was supposed to remove this version line to\n    +    prevent it from triggering that (previously defunct) emptiness check,\n    +    but, unfortunately, this command doesn't work as intended, either,\n    +    because it leaves the file to be checked intact, but that defunct\n    +    emptiness check hid this issue, too...  Furthermore, in the near\n    +    future there will be an other line on stderr, because commit\n    +    9a71722b4d (Doc: auto-detect changed build flags, 2019-03-17) in the\n    +    currently cooking branch 'ma/doc-diff-doc-vs-doctor-comparison' will\n    +    print \"* new asciidoc flags\" at the beginning of both 'make doc'\n    +    invokations.\n    +\n    +    Extend that 'sed' command to remove this line, too, wrap it in a\n    +    helper function so the output of both 'make doc' is filtered the same\n    +    way, and change its invokation to actually write the logfile to be\n    +    checked.\n     \n         [1] http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#set\n     \n    @@ -66,15 +77,32 @@\n      +++ b/ci/test-documentation.sh\n     @@\n      \n    + . ${0%/*}/lib.sh\n    + \n    ++filter_log () {\n    ++\tsed -e '/^GIT_VERSION = /d' \\\n    ++\t    -e '/^    \\* new asciidoc flags$/d' \\\n    ++\t    \"$1\"\n    ++}\n    ++\n    + make check-builtins\n    + make check-docs\n    + \n      # Build docs with AsciiDoc\n    - make doc > >(tee stdout.log) 2> >(tee stderr.log >&2)\n    +-make doc > >(tee stdout.log) 2> >(tee stderr.log >&2)\n     -! test -s stderr.log\n    -+cat stderr.log\n    ++make doc > >(tee stdout.log) 2> >(tee stderr.raw >&2)\n    ++cat stderr.raw\n    ++filter_log stderr.raw >stderr.log\n     +test ! -s stderr.log\n      test -s Documentation/git.html\n      test -s Documentation/git.xml\n      test -s Documentation/git.1\n    -@@\n    + grep '<meta name=\"generator\" content=\"AsciiDoc ' Documentation/git.html\n    + \n    +-rm -f stdout.log stderr.log\n    ++rm -f stdout.log stderr.log stderr.raw\n    + check_unignored_build_artifacts\n      \n      # Build docs with AsciiDoctor\n      make clean\n    @@ -82,8 +110,8 @@\n     -sed '/^GIT_VERSION = / d' stderr.log\n     -! test -s stderr.log\n     +make USE_ASCIIDOCTOR=1 doc > >(tee stdout.log) 2> >(tee stderr.raw >&2)\n    -+sed '/^GIT_VERSION = / d' stderr.raw >stderr.log\n    -+cat stderr.log\n    ++cat stderr.raw\n    ++filter_log stderr.raw >stderr.log\n     +test ! -s stderr.log\n      test -s Documentation/git.html\n      grep '<meta name=\"generator\" content=\"Asciidoctor ' Documentation/git.html\n-- \n2.21.0.539.g07239c3a71.dirty\n\n"},{"id":"372689","messageId":"20190329123520.27549-2-szeder.dev@gmail.com","threadId":"50814","inReplyTo":"20190329123520.27549-1-szeder.dev@gmail.com","subject":"[PATCH v3 1/6] Documentation/git-diff-tree.txt: fix formatting","fromName":"SZEDER Gábor","fromEmail":"szeder.dev@gmail.com","sentAt":"2019-03-29T12:35:15Z","receivedAt":"2019-03-29T12:35:36Z","isPatch":true,"sender":{"key":"szeder.dev@gmail.com","avatar":"https://avatars.githubusercontent.com/u/116324?v=4"},"body":"Asciidoctor versions v1.5.7 or later print the following warning while\nbuilding the documentation:\n\n      ASCIIDOC git-diff-tree.xml\n  asciidoctor: WARNING: diff-format.txt: line 2: unterminated listing block\n\nThis highlights an issue (even with older Asciidoctor versions) where\nthe \"Raw output format\" header is not rendered as a header, and the\nrest of the document is rendered in monospace.  This is not caused by\n'diff-format.txt' in itself, but rather by 'git-diff-tree.txt'\nincluding 'pretty-formats.txt' and 'diff-format.txt' on subsequent\nlines, while the former happens to end with monospace-formatted\nexample commands.\n\nFix this by inserting an empty line between the two include::\ndirectives.\n\nThe page rendered with AsciiDoc doesn't have this formatting issue.\n\nSigned-off-by: SZEDER Gábor <szeder.dev@gmail.com>\n---\n Documentation/git-diff-tree.txt | 1 +\n 1 file changed, 1 insertion(+)\n\ndiff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt\nindex 24f32e8c54..5c8a2a5e97 100644\n--- a/Documentation/git-diff-tree.txt\n+++ b/Documentation/git-diff-tree.txt\n@@ -118,6 +118,7 @@ include::pretty-options.txt[]\n \n \n include::pretty-formats.txt[]\n+\n include::diff-format.txt[]\n \n GIT\n-- \n2.21.0.539.g07239c3a71.dirty\n\n"},{"id":"372690","messageId":"20190329123520.27549-3-szeder.dev@gmail.com","threadId":"50814","inReplyTo":"20190329123520.27549-1-szeder.dev@gmail.com","subject":"[PATCH v3 2/6] Documentation/technical/api-config.txt: fix formatting","fromName":"SZEDER Gábor","fromEmail":"szeder.dev@gmail.com","sentAt":"2019-03-29T12:35:16Z","receivedAt":"2019-03-29T12:35:37Z","isPatch":true,"sender":{"key":"szeder.dev@gmail.com","avatar":"https://avatars.githubusercontent.com/u/116324?v=4"},"body":"Asciidoctor versions v1.5.7 or later print the following warning while\nbuilding the documentation:\n\n      ASCIIDOC technical/api-config.html\n  asciidoctor: WARNING: api-config.txt: line 232: unterminated listing block\n\nThis highlight an issue (even with older Asciidoctor versions) where\nthe length of the '----' lines surrounding a code example don't match,\nand the rest of the document is rendered in monospace.\n\nFix this by making sure that the length of those lines match.\n\nThe page rendered with AsciiDoc doesn't have this formatting issue.\n\nSigned-off-by: SZEDER Gábor <szeder.dev@gmail.com>\n---\n Documentation/technical/api-config.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt\nindex fa39ac9d71..7d20716c32 100644\n--- a/Documentation/technical/api-config.txt\n+++ b/Documentation/technical/api-config.txt\n@@ -229,7 +229,7 @@ A `config_set` can be used to construct an in-memory cache for\n config-like files that the caller specifies (i.e., files like `.gitmodules`,\n `~/.gitconfig` etc.). For example,\n \n----------------------------------------\n+----------------------------------------\n struct config_set gm_config;\n git_configset_init(&gm_config);\n int b;\n-- \n2.21.0.539.g07239c3a71.dirty\n\n"},{"id":"372691","messageId":"20190329123520.27549-5-szeder.dev@gmail.com","threadId":"50814","inReplyTo":"20190329123520.27549-1-szeder.dev@gmail.com","subject":"[PATCH v3 4/6] ci: install Asciidoctor in 'ci/install-dependencies.sh'","fromName":"SZEDER Gábor","fromEmail":"szeder.dev@gmail.com","sentAt":"2019-03-29T12:35:18Z","receivedAt":"2019-03-29T12:35:39Z","isPatch":true,"sender":{"key":"szeder.dev@gmail.com","avatar":"https://avatars.githubusercontent.com/u/116324?v=4"},"body":"When our '.travis.yml' was split into several 'ci/*' scripts [1], the\ninstallation of the 'asciidoctor' gem somehow ended up in\n'ci/test-documentation.sh'.\n\nInstall it in 'ci/install-dependencies.sh', where we install other\ndependencies of the Documentation build job as well (asciidoc,\nxmlto).\n\n[1] 657343a602 (travis-ci: move Travis CI code into dedicated scripts,\n    2017-09-10)\n\nSigned-off-by: SZEDER Gábor <szeder.dev@gmail.com>\n---\n ci/install-dependencies.sh | 3 +++\n ci/test-documentation.sh   | 3 ---\n 2 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/ci/install-dependencies.sh b/ci/install-dependencies.sh\nindex d64667fcbf..76ec308965 100755\n--- a/ci/install-dependencies.sh\n+++ b/ci/install-dependencies.sh\n@@ -54,6 +54,9 @@ StaticAnalysis)\n Documentation)\n \tsudo apt-get -q update\n \tsudo apt-get -q -y install asciidoc xmlto\n+\n+\ttest -n \"$ALREADY_HAVE_ASCIIDOCTOR\" ||\n+\tgem install asciidoctor\n \t;;\n esac\n \ndiff --git a/ci/test-documentation.sh b/ci/test-documentation.sh\nindex be3b7d376a..8f91f48c81 100755\n--- a/ci/test-documentation.sh\n+++ b/ci/test-documentation.sh\n@@ -5,9 +5,6 @@\n \n . ${0%/*}/lib.sh\n \n-test -n \"$ALREADY_HAVE_ASCIIDOCTOR\" ||\n-gem install asciidoctor\n-\n make check-builtins\n make check-docs\n \n-- \n2.21.0.539.g07239c3a71.dirty\n\n"},{"id":"372692","messageId":"20190329123520.27549-4-szeder.dev@gmail.com","threadId":"50814","inReplyTo":"20190329123520.27549-1-szeder.dev@gmail.com","subject":"[PATCH v3 3/6] Documentation/technical/protocol-v2.txt: fix formatting","fromName":"SZEDER Gábor","fromEmail":"szeder.dev@gmail.com","sentAt":"2019-03-29T12:35:17Z","receivedAt":"2019-03-29T12:35:40Z","isPatch":true,"sender":{"key":"szeder.dev@gmail.com","avatar":"https://avatars.githubusercontent.com/u/116324?v=4"},"body":"Asciidoctor versions v1.5.7 or later print the following warning while\nbuilding the documentation:\n\n      ASCIIDOC technical/protocol-v2.html\n  asciidoctor: WARNING: protocol-v2.txt: line 38: unterminated listing block\n\nThis highlights an issue (even with older Asciidoctor versions) where\nthe 'Initial Client Request' header is not rendered as a header but in\nmonospace.  I'm not sure what exactly causes this issue and why it's\nan issue only with this particular header, but all headers in\n'protocol-v2.txt' are written like this:\n\n   Initial Client Request\n  ------------------------\n\ni.e. the header itself is indented by a space, and the \"underline\" is\ntwo characters longer than the header.\n\nDropping that indentation and making the length of the underline match\nthe length of the header apparently fixes this issue.\n\nWhile at it, adjust all other headers 'protocol-v2.txt' as well, to\nmatch the style we use everywhere else.\n\nThe page rendered with AsciiDoc doesn't have this formatting issue.\n\nSigned-off-by: SZEDER Gábor <szeder.dev@gmail.com>\n---\n Documentation/technical/protocol-v2.txt | 52 ++++++++++++-------------\n 1 file changed, 26 insertions(+), 26 deletions(-)\n\ndiff --git a/Documentation/technical/protocol-v2.txt b/Documentation/technical/protocol-v2.txt\nindex ead85ce35c..03264c7d9a 100644\n--- a/Documentation/technical/protocol-v2.txt\n+++ b/Documentation/technical/protocol-v2.txt\n@@ -1,5 +1,5 @@\n- Git Wire Protocol, Version 2\n-==============================\n+Git Wire Protocol, Version 2\n+============================\n \n This document presents a specification for a version 2 of Git's wire\n protocol.  Protocol v2 will improve upon v1 in the following ways:\n@@ -22,8 +22,8 @@ will be commands which a client can request be executed.  Once a command\n has completed, a client can reuse the connection and request that other\n commands be executed.\n \n- Packet-Line Framing\n----------------------\n+Packet-Line Framing\n+-------------------\n \n All communication is done using packet-line framing, just as in v1.  See\n `Documentation/technical/pack-protocol.txt` and\n@@ -34,8 +34,8 @@ In protocol v2 these special packets will have the following semantics:\n   * '0000' Flush Packet (flush-pkt) - indicates the end of a message\n   * '0001' Delimiter Packet (delim-pkt) - separates sections of a message\n \n- Initial Client Request\n-------------------------\n+Initial Client Request\n+----------------------\n \n In general a client can request to speak protocol v2 by sending\n `version=2` through the respective side-channel for the transport being\n@@ -43,22 +43,22 @@ used which inevitably sets `GIT_PROTOCOL`.  More information can be\n found in `pack-protocol.txt` and `http-protocol.txt`.  In all cases the\n response from the server is the capability advertisement.\n \n- Git Transport\n-~~~~~~~~~~~~~~~\n+Git Transport\n+~~~~~~~~~~~~~\n \n When using the git:// transport, you can request to use protocol v2 by\n sending \"version=2\" as an extra parameter:\n \n    003egit-upload-pack /project.git\\0host=myserver.com\\0\\0version=2\\0\n \n- SSH and File Transport\n-~~~~~~~~~~~~~~~~~~~~~~~~\n+SSH and File Transport\n+~~~~~~~~~~~~~~~~~~~~~~\n \n When using either the ssh:// or file:// transport, the GIT_PROTOCOL\n environment variable must be set explicitly to include \"version=2\".\n \n- HTTP Transport\n-~~~~~~~~~~~~~~~~\n+HTTP Transport\n+~~~~~~~~~~~~~~\n \n When using the http:// or https:// transport a client makes a \"smart\"\n info/refs request as described in `http-protocol.txt` and requests that\n@@ -79,8 +79,8 @@ A v2 server would reply:\n Subsequent requests are then made directly to the service\n `$GIT_URL/git-upload-pack`. (This works the same for git-receive-pack).\n \n- Capability Advertisement\n---------------------------\n+Capability Advertisement\n+------------------------\n \n A server which decides to communicate (based on a request from a client)\n using protocol version 2, notifies the client by sending a version string\n@@ -101,8 +101,8 @@ to be executed by the client.\n     key = 1*(ALPHA | DIGIT | \"-_\")\n     value = 1*(ALPHA | DIGIT | \" -_.,?\\/{}[]()<>!@#$%^&*+=:;\")\n \n- Command Request\n------------------\n+Command Request\n+---------------\n \n After receiving the capability advertisement, a client can then issue a\n request to select the command it wants with any particular capabilities\n@@ -137,8 +137,8 @@ command be executed or can terminate the connection.  A client may\n optionally send an empty request consisting of just a flush-pkt to\n indicate that no more requests will be made.\n \n- Capabilities\n---------------\n+Capabilities\n+------------\n \n There are two different types of capabilities: normal capabilities,\n which can be used to to convey information or alter the behavior of a\n@@ -153,8 +153,8 @@ management on the server side in order to function correctly.  This\n permits simple round-robin load-balancing on the server side, without\n needing to worry about state management.\n \n- agent\n-~~~~~~~\n+agent\n+~~~~~\n \n The server can advertise the `agent` capability with a value `X` (in the\n form `agent=X`) to notify the client that the server is running version\n@@ -168,8 +168,8 @@ printable ASCII characters except space (i.e., the byte range 32 < x <\n and debugging purposes, and MUST NOT be used to programmatically assume\n the presence or absence of particular features.\n \n- ls-refs\n-~~~~~~~~~\n+ls-refs\n+~~~~~~~\n \n `ls-refs` is the command used to request a reference advertisement in v2.\n Unlike the current reference advertisement, ls-refs takes in arguments\n@@ -199,8 +199,8 @@ The output of ls-refs is as follows:\n     symref = \"symref-target:\" symref-target\n     peeled = \"peeled:\" obj-id\n \n- fetch\n-~~~~~~~\n+fetch\n+~~~~~\n \n `fetch` is the command used to fetch a packfile in v2.  It can be looked\n at as a modified version of the v1 fetch where the ref-advertisement is\n@@ -444,8 +444,8 @@ header.\n \t\t2 - progress messages\n \t\t3 - fatal error message just before stream aborts\n \n- server-option\n-~~~~~~~~~~~~~~~\n+server-option\n+~~~~~~~~~~~~~\n \n If advertised, indicates that any number of server specific options can be\n included in a request.  This is done by sending each option as a\n-- \n2.21.0.539.g07239c3a71.dirty\n\n"},{"id":"372693","messageId":"20190329123520.27549-6-szeder.dev@gmail.com","threadId":"50814","inReplyTo":"20190329123520.27549-1-szeder.dev@gmail.com","subject":"[PATCH v3 5/6] ci: stick with Asciidoctor v1.5.8 for now","fromName":"SZEDER Gábor","fromEmail":"szeder.dev@gmail.com","sentAt":"2019-03-29T12:35:19Z","receivedAt":"2019-03-29T12:35:41Z","isPatch":true,"sender":{"key":"szeder.dev@gmail.com","avatar":"https://avatars.githubusercontent.com/u/116324?v=4"},"body":"The release of Asciidoctor v2.0.0 two days ago broke our documentation\nbuild job on Travis CI, where we 'gem install asciidoctor', which\nalways brings us the latest and (supposedly) greatest.  Alas, we are\nnot ready for that just yet, because it removed support for DocBook\n4.5, and we have been requiring that particular DocBook version to\nbuild 'user-manual.xml' with Asciidoctor, resulting in:\n\n      ASCIIDOC user-manual.xml\n  asciidoctor: FAILED: missing converter for backend 'docbook45'. Processing aborted.\n    Use --trace for backtrace\n  make[1]: *** [user-manual.xml] Error 1\n\nUnfortunately, we can't simply switch to DocBook 5 right away, as\ndoing so leads to validation errors from 'xmlto', and working around\nthose leads to yet another errors... [1]\n\nSo let's stick with Asciidoctor v1.5.8 (latest stable release before\nv2.0.0) in our documentation build job on Travis CI for now, until we\nfigure out how to deal with the fallout from Asciidoctor v2.0.0.\n\n[1] https://public-inbox.org/git/20190324162131.GL4047@pobox.com/\n\nSigned-off-by: SZEDER Gábor <szeder.dev@gmail.com>\n---\n ci/install-dependencies.sh | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/ci/install-dependencies.sh b/ci/install-dependencies.sh\nindex 76ec308965..52a44c690a 100755\n--- a/ci/install-dependencies.sh\n+++ b/ci/install-dependencies.sh\n@@ -56,7 +56,7 @@ Documentation)\n \tsudo apt-get -q -y install asciidoc xmlto\n \n \ttest -n \"$ALREADY_HAVE_ASCIIDOCTOR\" ||\n-\tgem install asciidoctor\n+\tgem install --version 1.5.8 asciidoctor\n \t;;\n esac\n \n-- \n2.21.0.539.g07239c3a71.dirty\n\n"},{"id":"372694","messageId":"20190329123520.27549-7-szeder.dev@gmail.com","threadId":"50814","inReplyTo":"20190329123520.27549-1-szeder.dev@gmail.com","subject":"[PATCH v3 6/6] ci: fix AsciiDoc/Asciidoctor stderr check in the documentation build job","fromName":"SZEDER Gábor","fromEmail":"szeder.dev@gmail.com","sentAt":"2019-03-29T12:35:20Z","receivedAt":"2019-03-29T12:35:43Z","isPatch":true,"sender":{"key":"szeder.dev@gmail.com","avatar":"https://avatars.githubusercontent.com/u/116324?v=4"},"body":"In 'ci/test-documentation.sh' we save the standard error of 'make\ndoc', and, in an attempt to make sure that neither AsciiDoc nor\nAsciidoctor printed any warnings, we check the emptiness of the\nresulting file with '! test -s stderr.log'.  This check has never\nactually worked, because in our 'ci/*' build scripts we rely on 'set\n-e' aborting the build job when a command exits with error, and,\nunfortunately, the combination of the two doesn't work as intended.\nAccording to POSIX [1]:\n\n  \"The -e setting shall be ignored when executing [...] a pipeline\n  beginning with the ! reserved word\" [2]\n\nWatch and learn:\n\n  $ echo unexpected >file\n  $ ( set -e; ! test -s file ; echo \"should not reach this\" ) ; echo $?\n  should not reach this\n  0\n\nThis is why we haven't noticed the warnings from Asciidoctor that were\nfixed in the first patches of this patch series, though some of them\nwere already there in the build of v2.18.0-rc0 [3].\n\nCheck the emptiness of that file with 'test ! -s' instead, which works\nproperly with 'set -e':\n\n  $ ( set -e; test ! -s file ; echo \"should not reach this\" ) ; echo $?\n  1\n\nFurthermore, dump the contents of that file to the log for our\nconvenience, so if it were to unexpectedly end up being non-empty,\nthen we wouldn't have to scroll through all that long build log\nlooking for warnings, but could see them right away near the end of\nthe log.\n\nNote that we are only really interested in the standard error of\nAsciiDoc and Asciidoctor, but by saving the stderr of 'make doc' we\nalso save any error output from the make rules.  Currently there is\nonly one such line: we build the docs with Asciidoctor right after a\n'make clean', meaning that 'make USE_ASCIIDOCTOR=1 doc' always starts\nwith running 'GIT-VERSION-GEN', which in turn prints the version to\nstderr.  A 'sed' command was supposed to remove this version line to\nprevent it from triggering that (previously defunct) emptiness check,\nbut, unfortunately, this command doesn't work as intended, either,\nbecause it leaves the file to be checked intact, but that defunct\nemptiness check hid this issue, too...  Furthermore, in the near\nfuture there will be an other line on stderr, because commit\n9a71722b4d (Doc: auto-detect changed build flags, 2019-03-17) in the\ncurrently cooking branch 'ma/doc-diff-doc-vs-doctor-comparison' will\nprint \"* new asciidoc flags\" at the beginning of both 'make doc'\ninvokations.\n\nExtend that 'sed' command to remove this line, too, wrap it in a\nhelper function so the output of both 'make doc' is filtered the same\nway, and change its invokation to actually write the logfile to be\nchecked.\n\n[1] http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#set\n\n[2] POSIX doesn't discuss the meaning of '! cmd' in case of simple\n    commands, but it defines that \"A pipeline is a sequence of one or\n    more commands separated by the control operator '|'\", so\n    apparently a simple command is considered as pipeline as well.\n\n    http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_09_02\n\n[3] https://travis-ci.org/git/git/jobs/385932007#L1463\n\nSigned-off-by: SZEDER Gábor <szeder.dev@gmail.com>\n---\n ci/test-documentation.sh | 23 ++++++++++++++++-------\n 1 file changed, 16 insertions(+), 7 deletions(-)\n\ndiff --git a/ci/test-documentation.sh b/ci/test-documentation.sh\nindex 8f91f48c81..d49089832d 100755\n--- a/ci/test-documentation.sh\n+++ b/ci/test-documentation.sh\n@@ -5,29 +5,38 @@\n \n . ${0%/*}/lib.sh\n \n+filter_log () {\n+\tsed -e '/^GIT_VERSION = /d' \\\n+\t    -e '/^    \\* new asciidoc flags$/d' \\\n+\t    \"$1\"\n+}\n+\n make check-builtins\n make check-docs\n \n # Build docs with AsciiDoc\n-make doc > >(tee stdout.log) 2> >(tee stderr.log >&2)\n-! test -s stderr.log\n+make doc > >(tee stdout.log) 2> >(tee stderr.raw >&2)\n+cat stderr.raw\n+filter_log stderr.raw >stderr.log\n+test ! -s stderr.log\n test -s Documentation/git.html\n test -s Documentation/git.xml\n test -s Documentation/git.1\n grep '<meta name=\"generator\" content=\"AsciiDoc ' Documentation/git.html\n \n-rm -f stdout.log stderr.log\n+rm -f stdout.log stderr.log stderr.raw\n check_unignored_build_artifacts\n \n # Build docs with AsciiDoctor\n make clean\n-make USE_ASCIIDOCTOR=1 doc > >(tee stdout.log) 2> >(tee stderr.log >&2)\n-sed '/^GIT_VERSION = / d' stderr.log\n-! test -s stderr.log\n+make USE_ASCIIDOCTOR=1 doc > >(tee stdout.log) 2> >(tee stderr.raw >&2)\n+cat stderr.raw\n+filter_log stderr.raw >stderr.log\n+test ! -s stderr.log\n test -s Documentation/git.html\n grep '<meta name=\"generator\" content=\"Asciidoctor ' Documentation/git.html\n \n-rm -f stdout.log stderr.log\n+rm -f stdout.log stderr.log stderr.raw\n check_unignored_build_artifacts\n \n save_good_tree\n-- \n2.21.0.539.g07239c3a71.dirty\n\n"},{"id":"372711","messageId":"nycvar.QRO.7.76.6.1903291653590.41@tvgsbejvaqbjf.bet","threadId":"50814","inReplyTo":"20190329123520.27549-1-szeder.dev@gmail.com","subject":"Re: [PATCH v3 0/6] Asciidoctor-related formatting and CI fixes","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2019-03-29T15:56:28Z","receivedAt":"2019-03-29T15:56:48Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Fri, 29 Mar 2019, SZEDER Gábor wrote:\n\n> [...]\n>   - Mention in patch 4's commit message that Asciidoctor is still only\n>     installed in the Documentation build job.\n> [...]\n>\n> Range-diff:\n> 1:  8026f62876 = 1:  8026f62876 Documentation/git-diff-tree.txt: fix formatting\n> 2:  fd19cf4b24 = 2:  fd19cf4b24 Documentation/technical/api-config.txt: fix formatting\n> 3:  638dcd64e9 = 3:  638dcd64e9 Documentation/technical/protocol-v2.txt: fix formatting\n> 4:  6f8c6ff398 ! 4:  2e94e2b7b6 ci: install Asciidoctor in 'ci/install-dependencies.sh'\n>     @@ -6,8 +6,9 @@\n>          installation of the 'asciidoctor' gem somehow ended up in\n>          'ci/test-documentation.sh'.\n>\n>     -    Install it in 'ci/install-dependencies.sh', where we install\n>     -    everything else.\n>     +    Install it in 'ci/install-dependencies.sh', where we install other\n>     +    dependencies of the Documentation build job as well (asciidoc,\n>     +    xmlto).\n\nI would have wished for something that more explicitly said that it still\n*only* installs it for the Documentation job.\n\nBut I can live with the current wording.\n\n>          [1] 657343a602 (travis-ci: move Travis CI code into dedicated scripts,\n>              2017-09-10)\n> [...]\n>\n>     @@ -66,15 +77,32 @@\n>       +++ b/ci/test-documentation.sh\n>      @@\n>\n>     + . ${0%/*}/lib.sh\n>     +\n>     ++filter_log () {\n>     ++\tsed -e '/^GIT_VERSION = /d' \\\n>     ++\t    -e '/^    \\* new asciidoc flags$/d' \\\n>     ++\t    \"$1\"\n>     ++}\n>     ++\n>     + make check-builtins\n>     + make check-docs\n>     +\n>       # Build docs with AsciiDoc\n>     - make doc > >(tee stdout.log) 2> >(tee stderr.log >&2)\n>     +-make doc > >(tee stdout.log) 2> >(tee stderr.log >&2)\n>      -! test -s stderr.log\n>     -+cat stderr.log\n>     ++make doc > >(tee stdout.log) 2> >(tee stderr.raw >&2)\n>     ++cat stderr.raw\n>     ++filter_log stderr.raw >stderr.log\n>      +test ! -s stderr.log\n>       test -s Documentation/git.html\n>       test -s Documentation/git.xml\n>       test -s Documentation/git.1\n>     -@@\n>     + grep '<meta name=\"generator\" content=\"AsciiDoc ' Documentation/git.html\n>     +\n>     +-rm -f stdout.log stderr.log\n>     ++rm -f stdout.log stderr.log stderr.raw\n>     + check_unignored_build_artifacts\n>\n>       # Build docs with AsciiDoctor\n>       make clean\n>     @@ -82,8 +110,8 @@\n>      -sed '/^GIT_VERSION = / d' stderr.log\n>      -! test -s stderr.log\n>      +make USE_ASCIIDOCTOR=1 doc > >(tee stdout.log) 2> >(tee stderr.raw >&2)\n>     -+sed '/^GIT_VERSION = / d' stderr.raw >stderr.log\n>     -+cat stderr.log\n>     ++cat stderr.raw\n>     ++filter_log stderr.raw >stderr.log\n>      +test ! -s stderr.log\n>       test -s Documentation/git.html\n>       grep '<meta name=\"generator\" content=\"Asciidoctor ' Documentation/git.html\n\nWow. Subtle. And a bit hard to read without color ;-) But from what I\nunderstand, this does the right thing.\n\nSo from my side, this patch series is good to go!\n\nThanks,\nDscho\n"},{"id":"372728","messageId":"20190329195246.GH32732@szeder.dev","threadId":"50814","inReplyTo":"20190329123520.27549-6-szeder.dev@gmail.com","subject":"[PATCH v3.1 5/6] ci: stick with Asciidoctor v1.5.8 for now","fromName":"SZEDER Gábor","fromEmail":"szeder.dev@gmail.com","sentAt":"2019-03-29T19:52:46Z","receivedAt":"2019-03-29T19:52:52Z","isPatch":true,"sender":{"key":"szeder.dev@gmail.com","avatar":"https://avatars.githubusercontent.com/u/116324?v=4"},"body":"On Fri, Mar 29, 2019 at 01:35:19PM +0100, SZEDER Gábor wrote:\n> The release of Asciidoctor v2.0.0 two days ago broke our documentation\n\nWell, what happened \"two days ago\" when I sent v2 is now seven days\nago...  Let's just say \"recent\" instead.\n\n\n  --- >8 ---\n\nSubject: ci: stick with Asciidoctor v1.5.8 for now\n\nThe recent release of Asciidoctor v2.0.0 broke our documentation\nbuild job on Travis CI, where we 'gem install asciidoctor', which\nalways brings us the latest and (supposedly) greatest.  Alas, we are\nnot ready for that just yet, because it removed support for DocBook\n4.5, and we have been requiring that particular DocBook version to\nbuild 'user-manual.xml' with Asciidoctor, resulting in:\n\n      ASCIIDOC user-manual.xml\n  asciidoctor: FAILED: missing converter for backend 'docbook45'. Processing aborted.\n    Use --trace for backtrace\n  make[1]: *** [user-manual.xml] Error 1\n\nUnfortunately, we can't simply switch to DocBook 5 right away, as\ndoing so leads to validation errors from 'xmlto', and working around\nthose leads to yet another errors... [1]\n\nSo let's stick with Asciidoctor v1.5.8 (latest stable release before\nv2.0.0) in our documentation build job on Travis CI for now, until we\nfigure out how to deal with the fallout from Asciidoctor v2.0.0.\n\n[1] https://public-inbox.org/git/20190324162131.GL4047@pobox.com/\n\nSigned-off-by: SZEDER Gábor <szeder.dev@gmail.com>\n---\n ci/install-dependencies.sh | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/ci/install-dependencies.sh b/ci/install-dependencies.sh\nindex 76ec308965..52a44c690a 100755\n--- a/ci/install-dependencies.sh\n+++ b/ci/install-dependencies.sh\n@@ -56,7 +56,7 @@ Documentation)\n \tsudo apt-get -q -y install asciidoc xmlto\n \n \ttest -n \"$ALREADY_HAVE_ASCIIDOCTOR\" ||\n-\tgem install asciidoctor\n+\tgem install --version 1.5.8 asciidoctor\n \t;;\n esac\n \n-- \n2.21.0.539.g07239c3a71.dirty\n\n"},{"id":"373016","messageId":"CAN0heSrQrVQ+t3ZH1igU8zZLjjyhzZshFgarLcZOumWMBRN2Tg@mail.gmail.com","threadId":"50814","inReplyTo":"20190329195246.GH32732@szeder.dev","subject":"Re: [PATCH v3.1 5/6] ci: stick with Asciidoctor v1.5.8 for now","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2019-04-03T11:34:58Z","receivedAt":"2019-04-03T11:35:13Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"Hi Junio\n\nOn Fri, 29 Mar 2019 at 20:52, SZEDER Gábor <szeder.dev@gmail.com> wrote:\n>\n> On Fri, Mar 29, 2019 at 01:35:19PM +0100, SZEDER Gábor wrote:\n> > The release of Asciidoctor v2.0.0 two days ago broke our documentation\n>\n> Well, what happened \"two days ago\" when I sent v2 is now seven days\n> ago...  Let's just say \"recent\" instead.\n>\n>\n>   --- >8 ---\n>\n> Subject: ci: stick with Asciidoctor v1.5.8 for now\n\nThis was picked up as 28216d13f4 (\"ci: stick with Asciidoctor v1.5.8 for\nnow\", 2019-03-29) as part of sg/asciidoctor-in-ci. Actually, all of the\nabove is included, self-quote, scissors and all.\nMartin\n"}]}