* [PATCH] Create HTML for technical/http-protocol.txt
@ 2014-01-11 11:19 Thomas Ackermann
2014-01-13 18:40 ` Junio C Hamano
0 siblings, 1 reply; 2+ messages in thread
From: Thomas Ackermann @ 2014-01-11 11:19 UTC (permalink / raw)
To: git; +Cc: gitster, spearce
- Add to Documentation/Makefile
- Start every TODO with a new line
- Fix indentation error
Signed-off-by: Thomas Ackermann <th.acker@arcor•de>
---
Documentation/Makefile | 1 +
Documentation/technical/http-protocol.txt | 3 +--
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 36c58fc..b4a4c82 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -70,6 +70,7 @@ TECH_DOCS += technical/racy-git
TECH_DOCS += technical/send-pack-pipeline
TECH_DOCS += technical/shallow
TECH_DOCS += technical/trivial-merge
+TECH_DOCS += technical/http-protocol
SP_ARTICLES += $(TECH_DOCS)
SP_ARTICLES += technical/api-index
diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt
index d21d77d..c64a5e9 100644
--- a/Documentation/technical/http-protocol.txt
+++ b/Documentation/technical/http-protocol.txt
@@ -332,6 +332,7 @@ server advertises capability "allow-tip-sha1-in-want".
have_list = *PKT-LINE("have" SP id LF)
TODO: Document this further.
+
TODO: Don't use uppercase for variable names below.
The Negotiation Algorithm
@@ -376,10 +377,8 @@ The computation to select the minimal pack proceeds as follows
Commands MUST appear in the following order, if they appear
at all in the request stream:
-
* want
* have
-
The stream is terminated by a pkt-line flush ("0000").
A single "want" or "have" command MUST have one hex formatted
--
1.8.5.2.msysgit.0
---
Thomas
^ permalink raw reply related [flat|nested] 2+ messages in thread* Re: [PATCH] Create HTML for technical/http-protocol.txt
2014-01-11 11:19 [PATCH] Create HTML for technical/http-protocol.txt Thomas Ackermann
@ 2014-01-13 18:40 ` Junio C Hamano
0 siblings, 0 replies; 2+ messages in thread
From: Junio C Hamano @ 2014-01-13 18:40 UTC (permalink / raw)
To: Thomas Ackermann; +Cc: git, spearce
Thomas Ackermann <th.acker@arcor•de> writes:
> - Add to Documentation/Makefile
> - Start every TODO with a new line
> - Fix indentation error
>
> Signed-off-by: Thomas Ackermann <th.acker@arcor•de>
> ---
> Documentation/Makefile | 1 +
> Documentation/technical/http-protocol.txt | 3 +--
> 2 files changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 36c58fc..b4a4c82 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -70,6 +70,7 @@ TECH_DOCS += technical/racy-git
> TECH_DOCS += technical/send-pack-pipeline
> TECH_DOCS += technical/shallow
> TECH_DOCS += technical/trivial-merge
> +TECH_DOCS += technical/http-protocol
The output from "ls Documentation/technical/[b-z]*.txt" tells me
that this patch makes the TECH_DOCS cover everything (in other
words, this is not "I was intereted in http-protocol.txt; I did not
bother checking if there are others that are not formatted.").
Which is good, but that is something you could have said at the very
beginning as the motivation (which cannot be read from the patch)
before going into details of what you did (which can be read in the
patch).
Also let's keep them in order and move the new line before the
index-format, as h comes before i.
> SP_ARTICLES += $(TECH_DOCS)
> SP_ARTICLES += technical/api-index
>
> diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt
> index d21d77d..c64a5e9 100644
> --- a/Documentation/technical/http-protocol.txt
> +++ b/Documentation/technical/http-protocol.txt
> @@ -332,6 +332,7 @@ server advertises capability "allow-tip-sha1-in-want".
> have_list = *PKT-LINE("have" SP id LF)
>
> TODO: Document this further.
> +
> TODO: Don't use uppercase for variable names below.
>
> The Negotiation Algorithm
> @@ -376,10 +377,8 @@ The computation to select the minimal pack proceeds as follows
>
> Commands MUST appear in the following order, if they appear
> at all in the request stream:
> -
> * want
> * have
> -
> The stream is terminated by a pkt-line flush ("0000").
>
> A single "want" or "have" command MUST have one hex formatted
The resulting _source_ file read as txt becomes somewhat harder to
read with these changes. Admittedly, it is mostly because the
original text was meant to be easy to read in TEXT, not to be
formatted via AsciiDoc into HTML. We can see that in many places in
the formatted output with your patch. For example:
- Strings like "200 OK", "304 Not Modified", "HEAD" are italicized
("Discovering References" section); "GET" request is shown as
Roman body text. I think in our documentation it is customery to
typeset these "as-is" things in monospaced.
- "dumb server reply:", "smart server reply:" ("Smart Clients"
section) are shown in monospace just like the actual protocol
message examples that follow them, but we would most likely want
to see them as part of the body text.
- As all the descriptions of steps in the Negotiation Algorithm are
indented, the AsciiDoc formatted result becomes just a series of
fixed-font blocks around there.
So,... I think this patch may be a good first step, but it needs to
be followed by another that cleans up the mark-up in order for the
resulting HTML to be truly usable.
Thanks.
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2014-01-13 18:40 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2014-01-11 11:19 [PATCH] Create HTML for technical/http-protocol.txt Thomas Ackermann
2014-01-13 18:40 ` Junio C Hamano
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox