create HTML for http-protocol.txt

./Documentation/technical/http-protocol.txt was missing from TECH_DOCS in Makefile.
Add it and also improve HTML formatting while still retaining good readability of the ASCII text:
- Use monospace font instead of italicized or roman font for machine output and source text
- Use roman font for things which should be body text
- Use double quotes consistently for "want" and "have" commands
- Use uppercase "C" / "S" consistently for "client" / "server";
  also use "C:" / "S:" instead of "(C)" / "(S)" for consistency and
  to avoid having formatted "(C)" as copyright symbol in HTML
- Use only spaces and not a combination of tabs and spaces for whitespace

Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

2 files changed, 110 insertions, 105 deletions

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 36c58fc64..b19d52acf 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -60,7 +60,8 @@ SP_ARTICLES += howto/maintain-git
 API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
 SP_ARTICLES += $(API_DOCS)
 
-TECH_DOCS = technical/index-format
+TECH_DOCS = technical/http-protocol
+TECH_DOCS += technical/index-format
 TECH_DOCS += technical/pack-format
 TECH_DOCS += technical/pack-heuristics
 TECH_DOCS += technical/pack-protocol
diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt
index d21d77d1d..828e9fe37 100644
--- a/Documentation/technical/http-protocol.txt
+++ b/Documentation/technical/http-protocol.txt
@@ -20,13 +20,13 @@ URL syntax documented by RFC 1738, so they are of the form:
 
   http://<host>:<port>/<path>?<searchpart>
 
-Within this documentation the placeholder $GIT_URL will stand for
+Within this documentation the placeholder `$GIT_URL` will stand for
 the http:// repository URL entered by the end-user.
 
-Servers SHOULD handle all requests to locations matching $GIT_URL, as
+Servers SHOULD handle all requests to locations matching `$GIT_URL`, as
 both the "smart" and "dumb" HTTP protocols used by Git operate
 by appending additional path components onto the end of the user
-supplied $GIT_URL string.
+supplied `$GIT_URL` string.
 
 An example of a dumb client requesting for a loose object:
 
@@ -43,10 +43,10 @@ An example of a request to a submodule:
   $GIT_URL:     http://example.com/git/repo.git/path/submodule.git
   URL request:  http://example.com/git/repo.git/path/submodule.git/info/refs
 
-Clients MUST strip a trailing '/', if present, from the user supplied
-$GIT_URL string to prevent empty path tokens ('//') from appearing
+Clients MUST strip a trailing `/`, if present, from the user supplied
+`$GIT_URL` string to prevent empty path tokens (`//`) from appearing
 in any URL sent to a server.  Compatible clients MUST expand
-'$GIT_URL/info/refs' as 'foo/info/refs' and not 'foo//info/refs'.
+`$GIT_URL/info/refs` as `foo/info/refs` and not `foo//info/refs`.
 
 
 Authentication
@@ -103,14 +103,14 @@ Except where noted, all standard HTTP behavior SHOULD be assumed
 by both client and server.  This includes (but is not necessarily
 limited to):
 
-If there is no repository at $GIT_URL, or the resource pointed to by a
-location matching $GIT_URL does not exist, the server MUST NOT respond
-with '200 OK' response.  A server SHOULD respond with
-'404 Not Found', '410 Gone', or any other suitable HTTP status code
+If there is no repository at `$GIT_URL`, or the resource pointed to by a
+location matching `$GIT_URL` does not exist, the server MUST NOT respond
+with `200 OK` response.  A server SHOULD respond with
+`404 Not Found`, `410 Gone`, or any other suitable HTTP status code
 which does not imply the resource exists as requested.
 
-If there is a repository at $GIT_URL, but access is not currently
-permitted, the server MUST respond with the '403 Forbidden' HTTP
+If there is a repository at `$GIT_URL`, but access is not currently
+permitted, the server MUST respond with the `403 Forbidden` HTTP
 status code.
 
 Servers SHOULD support both HTTP 1.0 and HTTP 1.1.
@@ -126,9 +126,9 @@ Servers MAY return ETag and/or Last-Modified headers.
 Clients MAY revalidate cached entities by including If-Modified-Since
 and/or If-None-Match request headers.
 
-Servers MAY return '304 Not Modified' if the relevant headers appear
+Servers MAY return `304 Not Modified` if the relevant headers appear
 in the request and the entity has not changed.  Clients MUST treat
-'304 Not Modified' identical to '200 OK' by reusing the cached entity.
+`304 Not Modified` identical to `200 OK` by reusing the cached entity.
 
 Clients MAY reuse a cached entity without revalidation if the
 Cache-Control and/or Expires header permits caching.  Clients and
@@ -148,7 +148,7 @@ HTTP clients that only support the "dumb" protocol MUST discover
 references by making a request for the special info/refs file of
 the repository.
 
-Dumb HTTP clients MUST make a GET request to $GIT_URL/info/refs,
+Dumb HTTP clients MUST make a `GET` request to `$GIT_URL/info/refs`,
 without any search/query parameters.
 
    C: GET $GIT_URL/info/refs HTTP/1.0
@@ -161,21 +161,21 @@ without any search/query parameters.
    S: a3c2e2402b99163d1d59756e5f207ae21cccba4c	refs/tags/v1.0^{}
 
 The Content-Type of the returned info/refs entity SHOULD be
-"text/plain; charset=utf-8", but MAY be any content type.
+`text/plain; charset=utf-8`, but MAY be any content type.
 Clients MUST NOT attempt to validate the returned Content-Type.
 Dumb servers MUST NOT return a return type starting with
-"application/x-git-".
+`application/x-git-`.
 
 Cache-Control headers MAY be returned to disable caching of the
 returned entity.
 
 When examining the response clients SHOULD only examine the HTTP
-status code.  Valid responses are '200 OK', or '304 Not Modified'.
+status code.  Valid responses are `200 OK`, or `304 Not Modified`.
 
 The returned content is a UNIX formatted text file describing
 each ref and its known value.  The file SHOULD be sorted by name
 according to the C locale ordering.  The file SHOULD NOT include
-the default ref named 'HEAD'.
+the default ref named `HEAD`.
 
   info_refs   =  *( ref_record )
   ref_record  =  any_ref / peeled_ref
@@ -192,13 +192,14 @@ HTTP clients that support the "smart" protocol (or both the
 a parameterized request for the info/refs file of the repository.
 
 The request MUST contain exactly one query parameter,
-'service=$servicename', where $servicename MUST be the service
+`service=$servicename`, where `$servicename` MUST be the service
 name the client wishes to contact to complete the operation.
 The request MUST NOT contain additional query parameters.
 
    C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0
 
-   dumb server reply:
+dumb server reply:
+
    S: 200 OK
    S:
    S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31	refs/heads/maint
@@ -206,7 +207,8 @@ The request MUST NOT contain additional query parameters.
    S: 2cb58b79488a98d2721cea644875a8dd0026b115	refs/tags/v1.0
    S: a3c2e2402b99163d1d59756e5f207ae21cccba4c	refs/tags/v1.0^{}
 
-   smart server reply:
+smart server reply:
+
    S: 200 OK
    S: Content-Type: application/x-git-upload-pack-advertisement
    S: Cache-Control: no-cache
@@ -228,7 +230,7 @@ Smart Server Response
 ^^^^^^^^^^^^^^^^^^^^^
 If the server does not recognize the requested service name, or the
 requested service name has been disabled by the server administrator,
-the server MUST respond with the '403 Forbidden' HTTP status code.
+the server MUST respond with the `403 Forbidden` HTTP status code.
 
 Otherwise, smart servers MUST respond with the smart server reply
 format for the requested service name.
@@ -236,35 +238,35 @@ format for the requested service name.
 Cache-Control headers SHOULD be used to disable caching of the
 returned entity.
 
-The Content-Type MUST be 'application/x-$servicename-advertisement'.
+The Content-Type MUST be `application/x-$servicename-advertisement`.
 Clients SHOULD fall back to the dumb protocol if another content
 type is returned.  When falling back to the dumb protocol clients
-SHOULD NOT make an additional request to $GIT_URL/info/refs, but
+SHOULD NOT make an additional request to `$GIT_URL/info/refs`, but
 instead SHOULD use the response already in hand.  Clients MUST NOT
 continue if they do not support the dumb protocol.
 
-Clients MUST validate the status code is either '200 OK' or
-'304 Not Modified'.
+Clients MUST validate the status code is either `200 OK` or
+`304 Not Modified`.
 
 Clients MUST validate the first five bytes of the response entity
-matches the regex "^[0-9a-f]{4}#".  If this test fails, clients
+matches the regex `^[0-9a-f]{4}#`.  If this test fails, clients
 MUST NOT continue.
 
 Clients MUST parse the entire response as a sequence of pkt-line
 records.
 
-Clients MUST verify the first pkt-line is "# service=$servicename".
+Clients MUST verify the first pkt-line is `# service=$servicename`.
 Servers MUST set $servicename to be the request parameter value.
 Servers SHOULD include an LF at the end of this line.
 Clients MUST ignore an LF at the end of the line.
 
-Servers MUST terminate the response with the magic "0000" end
+Servers MUST terminate the response with the magic `0000` end
 pkt-line marker.
 
 The returned response is a pkt-line stream describing each ref and
 its known value.  The stream SHOULD be sorted by name according to
 the C locale ordering.  The stream SHOULD include the default ref
-named 'HEAD' as the first ref.  The stream MUST include capability
+named `HEAD` as the first ref.  The stream MUST include capability
 declarations behind a NUL on the first ref.
 
   smart_reply     =  PKT-LINE("# service=$servicename" LF)
@@ -286,12 +288,13 @@ declarations behind a NUL on the first ref.
   peeled_ref      =  PKT-LINE(obj-id SP name LF)
 		     PKT-LINE(obj-id SP name "^{}" LF
 
+
 Smart Service git-upload-pack
 ------------------------------
-This service reads from the repository pointed to by $GIT_URL.
+This service reads from the repository pointed to by `$GIT_URL`.
 
 Clients MUST first perform ref discovery with
-'$GIT_URL/info/refs?service=git-upload-pack'.
+`$GIT_URL/info/refs?service=git-upload-pack`.
 
    C: POST $GIT_URL/git-upload-pack HTTP/1.0
    C: Content-Type: application/x-git-upload-pack-request
@@ -313,10 +316,10 @@ to prevent caching of the response.
 
 Servers SHOULD support all capabilities defined here.
 
-Clients MUST send at least one 'want' command in the request body.
-Clients MUST NOT reference an id in a 'want' command which did not
+Clients MUST send at least one "want" command in the request body.
+Clients MUST NOT reference an id in a "want" command which did not
 appear in the response obtained through ref discovery unless the
-server advertises capability "allow-tip-sha1-in-want".
+server advertises capability `allow-tip-sha1-in-want`.
 
   compute_request   =  want_list
 		       have_list
@@ -337,24 +340,28 @@ TODO: Don't use uppercase for variable names below.
 The Negotiation Algorithm
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 The computation to select the minimal pack proceeds as follows
-(c = client, s = server):
+(C = client, S = server):
+
+'init step:'
+
+C: Use ref discovery to obtain the advertised refs.
+
+C: Place any object seen into set ADVERTISED.
 
- init step:
- (c) Use ref discovery to obtain the advertised refs.
- (c) Place any object seen into set ADVERTISED.
+C: Build an empty set, COMMON, to hold the objects that are later
+   determined to be on both ends.
 
- (c) Build an empty set, COMMON, to hold the objects that are later
-     determined to be on both ends.
- (c) Build a set, WANT, of the objects from ADVERTISED the client
-     wants to fetch, based on what it saw during ref discovery.
+C: Build a set, WANT, of the objects from ADVERTISED the client
+   wants to fetch, based on what it saw during ref discovery.
 
- (c) Start a queue, C_PENDING, ordered by commit time (popping newest
-     first).  Add all client refs.  When a commit is popped from
-     the queue its parents SHOULD be automatically inserted back.
-     Commits MUST only enter the queue once.
+C: Start a queue, C_PENDING, ordered by commit time (popping newest
+   first).  Add all client refs.  When a commit is popped from
+   the queue its parents SHOULD be automatically inserted back.
+   Commits MUST only enter the queue once.
 
- one compute step:
- (c) Send one $GIT_URL/git-upload-pack request:
+'one compute step:'
+
+C: Send one `$GIT_URL/git-upload-pack` request:
 
    C: 0032want <WANT #1>...............................
    C: 0032want <WANT #2>...............................
@@ -367,93 +374,90 @@ The computation to select the minimal pack proceeds as follows
    ....
    C: 0000
 
-     The stream is organized into "commands", with each command
-     appearing by itself in a pkt-line.  Within a command line
-     the text leading up to the first space is the command name,
-     and the remainder of the line to the first LF is the value.
-     Command lines are terminated with an LF as the last byte of
-     the pkt-line value.
+The stream is organized into "commands", with each command
+appearing by itself in a pkt-line.  Within a command line
+the text leading up to the first space is the command name,
+and the remainder of the line to the first LF is the value.
+Command lines are terminated with an LF as the last byte of
+the pkt-line value.
 
-     Commands MUST appear in the following order, if they appear
-     at all in the request stream:
+Commands MUST appear in the following order, if they appear
+at all in the request stream:
 
-       * want
-       * have
+* "want"
+* "have"
 
-     The stream is terminated by a pkt-line flush ("0000").
+The stream is terminated by a pkt-line flush (`0000`).
 
-     A single "want" or "have" command MUST have one hex formatted
-     SHA-1 as its value.  Multiple SHA-1s MUST be sent by sending
-     multiple commands.
+A single "want" or "have" command MUST have one hex formatted
+SHA-1 as its value.  Multiple SHA-1s MUST be sent by sending
+multiple commands.
 
-     The HAVE list is created by popping the first 32 commits
-     from C_PENDING.  Less can be supplied if C_PENDING empties.
+The HAVE list is created by popping the first 32 commits
+from C_PENDING.  Less can be supplied if C_PENDING empties.
 
-     If the client has sent 256 HAVE commits and has not yet
-     received one of those back from S_COMMON, or the client has
-     emptied C_PENDING it SHOULD include a "done" command to let
-     the server know it won't proceed:
+If the client has sent 256 HAVE commits and has not yet
+received one of those back from S_COMMON, or the client has
+emptied C_PENDING it SHOULD include a "done" command to let
+the server know it won't proceed:
 
    C: 0009done
 
-  (s) Parse the git-upload-pack request:
-
-      Verify all objects in WANT are directly reachable from refs.
-
-      The server MAY walk backwards through history or through
-      the reflog to permit slightly stale requests.
+S: Parse the git-upload-pack request:
 
-      If no WANT objects are received, send an error:
+Verify all objects in WANT are directly reachable from refs.
 
-TODO: Define error if no want lines are requested.
+The server MAY walk backwards through history or through
+the reflog to permit slightly stale requests.
 
-      If any WANT object is not reachable, send an error:
+If no WANT objects are received, send an error:
+TODO: Define error if no "want" lines are requested.
 
-TODO: Define error if an invalid want is requested.
+If any WANT object is not reachable, send an error:
+TODO: Define error if an invalid "want" is requested.
 
-     Create an empty list, S_COMMON.
+Create an empty list, S_COMMON.
 
-     If 'have' was sent:
+If "have" was sent:
 
-     Loop through the objects in the order supplied by the client.
-     For each object, if the server has the object reachable from
-     a ref, add it to S_COMMON.  If a commit is added to S_COMMON,
-     do not add any ancestors, even if they also appear in HAVE.
+Loop through the objects in the order supplied by the client.
 
-  (s) Send the git-upload-pack response:
+For each object, if the server has the object reachable from
+a ref, add it to S_COMMON.  If a commit is added to S_COMMON,
+do not add any ancestors, even if they also appear in HAVE.
 
-     If the server has found a closed set of objects to pack or the
-     request ends with "done", it replies with the pack.
+S: Send the git-upload-pack response:
 
+If the server has found a closed set of objects to pack or the
+request ends with "done", it replies with the pack.
 TODO: Document the pack based response
-   S: PACK...
 
-     The returned stream is the side-band-64k protocol supported
-     by the git-upload-pack service, and the pack is embedded into
-     stream 1.  Progress messages from the server side MAY appear
-     in stream 2.
+   S: PACK...
 
-     Here a "closed set of objects" is defined to have at least
-     one path from every WANT to at least one COMMON object.
+The returned stream is the side-band-64k protocol supported
+by the git-upload-pack service, and the pack is embedded into
+stream 1.  Progress messages from the server side MAY appear
+in stream 2.
 
-     If the server needs more information, it replies with a
-     status continue response:
+Here a "closed set of objects" is defined to have at least
+one path from every WANT to at least one COMMON object.
 
+If the server needs more information, it replies with a
+status continue response:
 TODO: Document the non-pack response
 
-  (c) Parse the upload-pack response:
-
-TODO: Document parsing response
+C: Parse the upload-pack response:
+   TODO: Document parsing response
 
-      Do another compute step.
+'Do another compute step.'
 
 
 Smart Service git-receive-pack
 ------------------------------
-This service reads from the repository pointed to by $GIT_URL.
+This service reads from the repository pointed to by `$GIT_URL`.
 
 Clients MUST first perform ref discovery with
-'$GIT_URL/info/refs?service=git-receive-pack'.
+`$GIT_URL/info/refs?service=git-receive-pack`.
 
    C: POST $GIT_URL/git-receive-pack HTTP/1.0
    C: Content-Type: application/x-git-receive-pack-request