Merge branch 'ta/doc-http-protocol-in-html'

* ta/doc-http-protocol-in-html:
  http-protocol.txt: don't use uppercase for variable names in "The Negotiation Algorithm"
  Documentation: make it easier to maintain enumerated documents
  create HTML for http-protocol.txt

2 files changed, 121 insertions, 114 deletions

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 36c58fc646..fc6b2cf9ec 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -2,6 +2,9 @@
 MAN1_TXT =
 MAN5_TXT =
 MAN7_TXT =
+TECH_DOCS =
+ARTICLES =
+SP_ARTICLES =
 
 MAN1_TXT += $(filter-out \
 		$(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \
@@ -37,12 +40,12 @@ MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))
 OBSOLETE_HTML = git-remote-helpers.html
 DOC_HTML = $(MAN_HTML) $(OBSOLETE_HTML)
 
-ARTICLES = howto-index
+ARTICLES += howto-index
 ARTICLES += everyday
 ARTICLES += git-tools
 ARTICLES += git-bisect-lk2009
 # with their own formatting rules.
-SP_ARTICLES = user-manual
+SP_ARTICLES += user-manual
 SP_ARTICLES += howto/new-command
 SP_ARTICLES += howto/revert-branch-rebase
 SP_ARTICLES += howto/using-merge-subtree
@@ -60,7 +63,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 d21d77d1de..544373b16f 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
@@ -332,128 +335,128 @@ 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 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: 0032want <WANT #1>...............................
-   C: 0032want <WANT #2>...............................
+C: Send one `$GIT_URL/git-upload-pack` request:
+
+   C: 0032want <want #1>...............................
+   C: 0032want <want #2>...............................
    ....
-   C: 0032have <COMMON #1>.............................
-   C: 0032have <COMMON #2>.............................
+   C: 0032have <common #1>.............................
+   C: 0032have <common #2>.............................
    ....
-   C: 0032have <HAVE #1>...............................
-   C: 0032have <HAVE #2>...............................
+   C: 0032have <have #1>...............................
+   C: 0032have <have #2>...............................
    ....
    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