[Patch 0/5] Create single PDF for all HTML files

[Patch 0/5] Create single PDF for all HTML files

[Thomas Ackermann]

Hi,

I wanted to have a single PDF file which contains the complete Git documentation 
(except user-manual) for easier reading on my tablet. The simplest way to do 
this was by using wkhtmltopdf which can combine a set of HTML files into a sinlge 
PDF file and also apply some reformatting. To this end HTML files for all the missing 
files in Documentation/technical and Documentation/howto and also for all the 
release notes in Documentation/RelNotes were created. 
The resulting PDF file "git-doc.pdf" is created by a new make target called "fullpdf".

Hope anybody finds that useful.


---
Thomas

[Patch 1/5] Fix some asciidoc layout problems

[Thomas Ackermann]

Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
---
 Documentation/git-bisect-lk2009.txt | 12 ++++++------
 Documentation/git-fetch-pack.txt    |  5 ++++-
 2 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-bisect-lk2009.txt b/Documentation/git-bisect-lk2009.txt
index 8a2ba37..99bdb46 100644
--- a/Documentation/git-bisect-lk2009.txt
+++ b/Documentation/git-bisect-lk2009.txt
@@ -248,7 +248,7 @@ Bisecting: 5480 revisions left to test after this (roughly 13 steps)
 And after a few more steps like that, "git bisect" will eventually
 find a first bad commit:
 
--------------
+------------------------------------------------------------------------------------------------------------
 $ git bisect bad
 2ddcca36c8bcfa251724fe342c8327451988be0d is the first bad commit
 commit 2ddcca36c8bcfa251724fe342c8327451988be0d
@@ -257,8 +257,8 @@ Date:   Sat May 3 11:59:44 2008 -0700
 
     Linux 2.6.26-rc1
 
-:100644 100644 5cf8258195331a4dbdddff08b8d68642638eea57 4492984efc09ab72ff6219a7bc21fb6a957c4cd5 M      Makefile
--------------
+:100644 100644 5cf8258195331a4dbdddff08b8d68642638eea57 4492984efc09ab72ff6219a7bc21fb6a957c4cd5 M  Makefile
+------------------------------------------------------------------------------------------------------------
 
 At this point we can see what the commit does, check it out (if it's
 not already checked out) or tinker with it, for example:
@@ -305,7 +305,7 @@ to launch a script or command at each bisection step to know if the
 current commit is "good" or "bad". To do that, we use the "git bisect
 run" command. For example:
 
--------------
+------------------------------------------------------------------------------------------------------------
 $ git bisect start v2.6.27 v2.6.25
 Bisecting: 10928 revisions left to test after this (roughly 14 steps)
 [2ec65f8b89ea003c27ff7723525a2ee335a2b393] x86: clean up using max_low_pfn on 32-bit
@@ -331,9 +331,9 @@ Date:   Sat May 3 11:59:44 2008 -0700
 
     Linux 2.6.26-rc1
 
-:100644 100644 5cf8258195331a4dbdddff08b8d68642638eea57 4492984efc09ab72ff6219a7bc21fb6a957c4cd5 M      Makefile
+:100644 100644 5cf8258195331a4dbdddff08b8d68642638eea57 4492984efc09ab72ff6219a7bc21fb6a957c4cd5 M  Makefile
 bisect run success
--------------
+------------------------------------------------------------------------------------------------------------
 
 In this example, we passed "grep '^SUBLEVEL = 25' Makefile" as
 parameter to "git bisect run". This means that at each step, the grep
diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt
index 474fa30..12cd8a2 100644
--- a/Documentation/git-fetch-pack.txt
+++ b/Documentation/git-fetch-pack.txt
@@ -9,7 +9,10 @@ git-fetch-pack - Receive missing objects from another repository
 SYNOPSIS
 --------
 [verse]
-'git fetch-pack' [--all] [--quiet|-q] [--keep|-k] [--thin] [--include-tag] [--upload-pack=<git-upload-pack>] [--depth=<n>] [--no-progress] [-v] [<host>:]<directory> [<refs>...]
+'git fetch-pack' [--all] [--quiet|-q] [--keep|-k] [--thin] [--include-tag] 
+				[--upload-pack=<git-upload-pack>] 
+				[--depth=<n>] [--no-progress] 
+				[-v] [<host>:]<directory> [<refs>...]
 
 DESCRIPTION
 -----------
-- 
1.7.11.msysgit.1

[Patch 2/5] Create html documents for all files in Documentation/technical

[Thomas Ackermann]

- add missing files
- fix some asciidoc layout problems

Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
---
 Documentation/Makefile                    | 12 ++++++++++-
 Documentation/technical/index-format.txt  |  2 +-
 Documentation/technical/pack-format.txt   |  8 +++----
 Documentation/technical/pack-protocol.txt |  7 +++---
 Documentation/technical/shallow.txt       |  8 ++++++-
 Documentation/technical/trivial-merge.txt | 36 +++++++++++++++----------------
 6 files changed, 45 insertions(+), 28 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 267dfe1..86594f6 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -25,6 +25,16 @@ SP_ARTICLES += howto/revert-branch-rebase
 SP_ARTICLES += howto/using-merge-subtree
 SP_ARTICLES += howto/using-signed-tag-in-pull-request
 API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
+API_DOCS += technical/index-format
+API_DOCS += technical/pack-format
+API_DOCS += technical/pack-heuristics
+API_DOCS += technical/pack-protocol
+API_DOCS += technical/protocol-capabilities
+API_DOCS += technical/protocol-common
+API_DOCS += technical/racy-git
+API_DOCS += technical/send-pack-pipeline
+API_DOCS += technical/shallow
+API_DOCS += technical/trivial-merge
 SP_ARTICLES += $(API_DOCS)
 SP_ARTICLES += technical/api-index
 
@@ -231,7 +241,7 @@ clean:
 	$(RM) *.texi *.texi+ *.texi++ git.info gitman.info
 	$(RM) *.pdf
 	$(RM) howto-index.txt howto/*.html doc.dep
-	$(RM) technical/api-*.html technical/api-index.txt
+	$(RM) technical/*.html technical/api-index.txt
 	$(RM) $(cmds_txt) *.made
 	$(RM) manpage-base-url.xsl
 
diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt
index 9d25b30..57d6f91 100644
--- a/Documentation/technical/index-format.txt
+++ b/Documentation/technical/index-format.txt
@@ -1,7 +1,7 @@
 GIT index format
 ================
 
-= The git index file has the following format
+== The git index file has the following format
 
   All binary numbers are in network byte order. Version 2 is described
   here unless stated otherwise.
diff --git a/Documentation/technical/pack-format.txt b/Documentation/technical/pack-format.txt
index 1803e64..a7871fb 100644
--- a/Documentation/technical/pack-format.txt
+++ b/Documentation/technical/pack-format.txt
@@ -1,7 +1,7 @@
 GIT pack format
 ===============
 
-= pack-*.pack files have the following format:
+== pack-*.pack files have the following format:
 
    - A header appears at the beginning and consists of the following:
 
@@ -34,7 +34,7 @@ GIT pack format
 
   - The trailer records 20-byte SHA1 checksum of all of the above.
 
-= Original (version 1) pack-*.idx files have the following format:
+== Original (version 1) pack-*.idx files have the following format:
 
   - The header consists of 256 4-byte network byte order
     integers.  N-th entry of this table records the number of
@@ -123,8 +123,8 @@ Pack file entry: <+
 
 
 
-= Version 2 pack-*.idx files support packs larger than 4 GiB, and
-  have some other reorganizations.  They have the format:
+== Version 2 pack-*.idx files support packs larger than 4 GiB, and
+   have some other reorganizations.  They have the format:
 
   - A 4-byte magic number '\377tOc' which is an unreasonable
     fanout[0] value.
diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt
index d51e20f..25e1fbe 100644
--- a/Documentation/technical/pack-protocol.txt
+++ b/Documentation/technical/pack-protocol.txt
@@ -117,7 +117,7 @@ A few things to remember here:
 - The repository path is always quoted with single quotes.
 
 Fetching Data From a Server
-===========================
+---------------------------
 
 When one Git repository wants to get data that a second repository
 has, the first can 'fetch' from the second.  This operation determines
@@ -134,7 +134,8 @@ with the object name that each reference currently points to.
 
    $ echo -e -n "0039git-upload-pack /schacon/gitbook.git\0host=example.com\0" |
       nc -v example.com 9418
-   00887217a7c7e582c46cec22a130adf4b9d7d950fba0 HEAD\0multi_ack thin-pack side-band side-band-64k ofs-delta shallow no-progress include-tag
+   00887217a7c7e582c46cec22a130adf4b9d7d950fba0 HEAD\0multi_ack thin-pack 
+                side-band side-band-64k ofs-delta shallow no-progress include-tag
    00441d3fcd5ced445d1abc402225c0b8a1299641f497 refs/heads/integration
    003f7217a7c7e582c46cec22a130adf4b9d7d950fba0 refs/heads/master
    003cb88d2441cac0977faf98efc80305012112238d9d refs/tags/v0.9
@@ -421,7 +422,7 @@ entire packfile without multiplexing.
 
 
 Pushing Data To a Server
-========================
+------------------------
 
 Pushing data to a server will invoke the 'receive-pack' process on the
 server, which will allow the client to tell it which references it should
diff --git a/Documentation/technical/shallow.txt b/Documentation/technical/shallow.txt
index 559263a..0502a54 100644
--- a/Documentation/technical/shallow.txt
+++ b/Documentation/technical/shallow.txt
@@ -1,6 +1,12 @@
-Def.: Shallow commits do have parents, but not in the shallow
+Shallow commits
+===============
+
+.Definition
+*********************************************************
+Shallow commits do have parents, but not in the shallow
 repo, and therefore grafts are introduced pretending that
 these commits have no parents.
+*********************************************************
 
 The basic idea is to write the SHA1s of shallow commits into
 $GIT_DIR/shallow, and handle its contents like the contents
diff --git a/Documentation/technical/trivial-merge.txt b/Documentation/technical/trivial-merge.txt
index 24c8410..c79d4a7 100644
--- a/Documentation/technical/trivial-merge.txt
+++ b/Documentation/technical/trivial-merge.txt
@@ -74,24 +74,24 @@ For multiple ancestors, a '+' means that this case applies even if
 only one ancestor or remote fits; a '^' means all of the ancestors
 must be the same.
 
-case  ancest    head    remote    result
-----------------------------------------
-1     (empty)+  (empty) (empty)   (empty)
-2ALT  (empty)+  *empty* remote    remote
-2     (empty)^  (empty) remote    no merge
-3ALT  (empty)+  head    *empty*   head
-3     (empty)^  head    (empty)   no merge
-4     (empty)^  head    remote    no merge
-5ALT  *         head    head      head
-6     ancest+   (empty) (empty)   no merge
-8     ancest^   (empty) ancest    no merge
-7     ancest+   (empty) remote    no merge
-10    ancest^   ancest  (empty)   no merge
-9     ancest+   head    (empty)   no merge
-16    anc1/anc2 anc1    anc2      no merge
-13    ancest+   head    ancest    head
-14    ancest+   ancest  remote    remote
-11    ancest+   head    remote    no merge
+ case  ancest    head    remote    result
+ ----------------------------------------
+ 1     (empty)+  (empty) (empty)   (empty)
+ 2ALT  (empty)+  *empty* remote    remote
+ 2     (empty)^  (empty) remote    no merge
+ 3ALT  (empty)+  head    *empty*   head
+ 3     (empty)^  head    (empty)   no merge
+ 4     (empty)^  head    remote    no merge
+ 5ALT  *         head    head      head
+ 6     ancest+   (empty) (empty)   no merge
+ 8     ancest^   (empty) ancest    no merge
+ 7     ancest+   (empty) remote    no merge
+ 10    ancest^   ancest  (empty)   no merge
+ 9     ancest+   head    (empty)   no merge
+ 16    anc1/anc2 anc1    anc2      no merge
+ 13    ancest+   head    ancest    head
+ 14    ancest+   ancest  remote    remote
+ 11    ancest+   head    remote    no merge
 
 Only #2ALT and #3ALT use *empty*, because these are the only cases
 where there can be conflicts that didn't exist before. Note that we
-- 
1.7.11.msysgit.1

[Patch 3/5] Create html documents for all files in Documentation/RelNotes

[Thomas Ackermann]

- create html for all release note files
- fix some asciidoc layout problems

Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
---
 Documentation/Makefile             | 2 ++
 Documentation/RelNotes/1.5.2.1.txt | 6 ------
 Documentation/RelNotes/1.6.0.2.txt | 6 ------
 Documentation/RelNotes/1.6.1.3.txt | 4 ----
 Documentation/RelNotes/1.6.1.4.txt | 3 ---
 Documentation/RelNotes/1.6.1.txt   | 6 ------
 6 files changed, 2 insertions(+), 25 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 86594f6..80eb06d 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -24,6 +24,7 @@ SP_ARTICLES = user-manual
 SP_ARTICLES += howto/revert-branch-rebase
 SP_ARTICLES += howto/using-merge-subtree
 SP_ARTICLES += howto/using-signed-tag-in-pull-request
+RELNOTES = $(patsubst %.txt,%,$(wildcard RelNotes/*.txt))
 API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
 API_DOCS += technical/index-format
 API_DOCS += technical/pack-format
@@ -35,6 +36,7 @@ API_DOCS += technical/racy-git
 API_DOCS += technical/send-pack-pipeline
 API_DOCS += technical/shallow
 API_DOCS += technical/trivial-merge
+API_DOCS += $(RELNOTES)
 SP_ARTICLES += $(API_DOCS)
 SP_ARTICLES += technical/api-index
 
diff --git a/Documentation/RelNotes/1.5.2.1.txt b/Documentation/RelNotes/1.5.2.1.txt
index ebf20e2..d41984d 100644
--- a/Documentation/RelNotes/1.5.2.1.txt
+++ b/Documentation/RelNotes/1.5.2.1.txt
@@ -45,9 +45,3 @@ Fixes since v1.5.2
   - git-fastimport --import-marks was broken; fixed.
 
   - A lot of documentation updates, clarifications and fixes.
-
---
-exec >/var/tmp/1
-O=v1.5.2-65-g996e2d6
-echo O=`git describe refs/heads/maint`
-git shortlog --no-merges $O..refs/heads/maint
diff --git a/Documentation/RelNotes/1.6.0.2.txt b/Documentation/RelNotes/1.6.0.2.txt
index e1e24b3..7d8fb85 100644
--- a/Documentation/RelNotes/1.6.0.2.txt
+++ b/Documentation/RelNotes/1.6.0.2.txt
@@ -79,9 +79,3 @@ Fixes since v1.6.0.1
   packfile.
 
 Also contains many documentation updates.
-
---
-exec >/var/tmp/1
-O=v1.6.0.1-78-g3632cfc
-echo O=$(git describe maint)
-git shortlog --no-merges $O..maint
diff --git a/Documentation/RelNotes/1.6.1.3.txt b/Documentation/RelNotes/1.6.1.3.txt
index 6f0bde1..cd08d81 100644
--- a/Documentation/RelNotes/1.6.1.3.txt
+++ b/Documentation/RelNotes/1.6.1.3.txt
@@ -26,7 +26,3 @@ Fixes since v1.6.1.2
 * RPM binary package installed the html manpages in a wrong place.
 
 Also includes minor documentation fixes and updates.
-
-
---
-git shortlog --no-merges v1.6.1.2-33-gc789350..
diff --git a/Documentation/RelNotes/1.6.1.4.txt b/Documentation/RelNotes/1.6.1.4.txt
index 0ce6316..ccbad79 100644
--- a/Documentation/RelNotes/1.6.1.4.txt
+++ b/Documentation/RelNotes/1.6.1.4.txt
@@ -39,6 +39,3 @@ Fixes since v1.6.1.3
   This fix was first merged to 1.6.2.3.
 
 Also includes minor documentation fixes and updates.
-
---
-git shortlog --no-merges v1.6.1.3..
diff --git a/Documentation/RelNotes/1.6.1.txt b/Documentation/RelNotes/1.6.1.txt
index adb7cca..7b152a6 100644
--- a/Documentation/RelNotes/1.6.1.txt
+++ b/Documentation/RelNotes/1.6.1.txt
@@ -278,9 +278,3 @@ release, unless otherwise noted.
 
 * "gitweb" did not mark non-ASCII characters imported from external HTML fragments
   correctly.
-
---
-exec >/var/tmp/1
-O=v1.6.1-rc3-74-gf66bc5f
-echo O=$(git describe master)
-git shortlog --no-merges $O..master ^maint
-- 
1.7.11.msysgit.1

[Patch 4/5] Create html documents for all files in Documentation/howto

[Thomas Ackermann]

- add missing files
- fix some asciidoc layout problems

Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
---
 Documentation/Makefile                             | 10 +++++
 Documentation/howto/maintain-git.txt               |  4 ++
 .../howto/rebase-from-internal-branch.txt          | 11 ++---
 Documentation/howto/rebuild-from-update-hook.txt   |  4 ++
 .../howto/recover-corrupted-blob-object.txt        | 10 +++++
 Documentation/howto/revert-a-faulty-merge.txt      |  4 ++
 Documentation/howto/separating-topic-branches.txt  |  4 ++
 Documentation/howto/setup-git-server-over-http.txt |  4 ++
 Documentation/howto/update-hook-example.txt        | 50 +++++++++++-----------
 Documentation/howto/use-git-daemon.txt             |  3 ++
 .../howto/using-signed-tag-in-pull-request.txt     |  4 +-
 11 files changed, 76 insertions(+), 32 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 80eb06d..abd27b5 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -24,6 +24,16 @@ SP_ARTICLES = user-manual
 SP_ARTICLES += howto/revert-branch-rebase
 SP_ARTICLES += howto/using-merge-subtree
 SP_ARTICLES += howto/using-signed-tag-in-pull-request
+SP_ARTICLES += howto/use-git-daemon
+SP_ARTICLES += howto/update-hook-example
+SP_ARTICLES += howto/setup-git-server-over-http
+SP_ARTICLES += howto/separating-topic-branches
+SP_ARTICLES += howto/revert-a-faulty-merge
+SP_ARTICLES += howto/recover-corrupted-blob-object
+SP_ARTICLES += howto/rebuild-from-update-hook
+SP_ARTICLES += howto/rebuild-from-update-hook
+SP_ARTICLES += howto/rebase-from-internal-branch
+SP_ARTICLES += howto/maintain-git
 RELNOTES = $(patsubst %.txt,%,$(wildcard RelNotes/*.txt))
 API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
 API_DOCS += technical/index-format
diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt
index 8823a37..58fd809 100644
--- a/Documentation/howto/maintain-git.txt
+++ b/Documentation/howto/maintain-git.txt
@@ -5,6 +5,10 @@ Abstract: Imagine that git development is racing along as usual, when our friend
  neighborhood maintainer is struck down by a wayward bus. Out of the
  hordes of suckers (loyal developers), you have been tricked (chosen) to
  step up as the new maintainer. This howto will show you "how to" do it.
+Content-type: text/asciidoc
+
+Maintain Git
+============
 
 The maintainer's git time is spent on three activities.
 
diff --git a/Documentation/howto/rebase-from-internal-branch.txt b/Documentation/howto/rebase-from-internal-branch.txt
index 74a1c0c..577b9a7 100644
--- a/Documentation/howto/rebase-from-internal-branch.txt
+++ b/Documentation/howto/rebase-from-internal-branch.txt
@@ -8,7 +8,12 @@ Abstract: In this article, JC talks about how he rebases the
  the "master" branch, and how "rebase" works.  Also discussed
  is how this applies to individual developers who sends patches
  upstream.
+Content-type: text/asciidoc
 
+Rebase from internal branch
+===========================
+
+--------------------------------------
 Petr Baudis <pasky@suse.cz> writes:
 
 > Dear diary, on Sun, Aug 14, 2005 at 09:57:13AM CEST, I got a letter
@@ -19,6 +24,7 @@ Petr Baudis <pasky@suse.cz> writes:
 >> > branch to the real branches.
 >>
 > Actually, wouldn't this be also precisely for what StGIT is intended to?
+--------------------------------------
 
 Exactly my feeling.  I was sort of waiting for Catalin to speak
 up.  With its basing philosophical ancestry on quilt, this is
@@ -156,8 +162,3 @@ you continue on starting from the new "master" head, which is
 the #1' commit.
 
 -jc
-
--
-To unsubscribe from this list: send the line "unsubscribe git" in
-the body of a message to majordomo@vger.kernel.org
-More majordomo info at  http://vger.kernel.org/majordomo-info.html
diff --git a/Documentation/howto/rebuild-from-update-hook.txt b/Documentation/howto/rebuild-from-update-hook.txt
index 48c6756..7aa13ac 100644
--- a/Documentation/howto/rebuild-from-update-hook.txt
+++ b/Documentation/howto/rebuild-from-update-hook.txt
@@ -5,6 +5,10 @@ Date: Fri, 26 Aug 2005 18:19:10 -0700
 Abstract: In this how-to article, JC talks about how he
  uses the post-update hook to automate git documentation page
  shown at http://www.kernel.org/pub/software/scm/git/docs/.
+Content-type: text/asciidoc
+
+Rebuild from update hook
+========================
 
 The pages under http://www.kernel.org/pub/software/scm/git/docs/
 are built from Documentation/ directory of the git.git project
diff --git a/Documentation/howto/recover-corrupted-blob-object.txt b/Documentation/howto/recover-corrupted-blob-object.txt
index 323b513..2af4ad7 100644
--- a/Documentation/howto/recover-corrupted-blob-object.txt
+++ b/Documentation/howto/recover-corrupted-blob-object.txt
@@ -3,11 +3,17 @@ From: Linus Torvalds <torvalds@linux-foundation.org>
 Subject: corrupt object on git-gc
 Abstract: Some tricks to reconstruct blob objects in order to fix
  a corrupted repository.
+Content-type: text/asciidoc
 
+Recover corrupted blob object
+=============================
+
+-----------------------------------------------------------
 On Fri, 9 Nov 2007, Yossi Leybovich wrote:
 >
 > Did not help still the repository look for this object?
 > Any one know how can I track this object and understand which file is it
+-----------------------------------------------------------
 
 So exactly *because* the SHA1 hash is cryptographically secure, the hash
 itself doesn't actually tell you anything, in order to fix a corrupt
@@ -31,19 +37,23 @@ original object, so right now the corrupt object is useless, but it's very
 interesting for the future, in the hope that you can re-create a
 non-corrupt version.
 
+-----------------------------------------------------------
 So:
 
 > ib]$ mv .git/objects/4b/9458b3786228369c63936db65827de3cc06200 ../
+-----------------------------------------------------------
 
 This is the right thing to do, although it's usually best to save it under
 it's full SHA1 name (you just dropped the "4b" from the result ;).
 
 Let's see what that tells us:
 
+-----------------------------------------------------------
 > ib]$ git-fsck --full
 > broken link from    tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8
 >              to    blob 4b9458b3786228369c63936db65827de3cc06200
 > missing blob 4b9458b3786228369c63936db65827de3cc06200
+-----------------------------------------------------------
 
 Ok, I removed the "dangling commit" messages, because they are just
 messages about the fact that you probably have rebased etc, so they're not
diff --git a/Documentation/howto/revert-a-faulty-merge.txt b/Documentation/howto/revert-a-faulty-merge.txt
index 6fd7119..936c3a9 100644
--- a/Documentation/howto/revert-a-faulty-merge.txt
+++ b/Documentation/howto/revert-a-faulty-merge.txt
@@ -7,6 +7,10 @@ Abstract: Sometimes a branch that was already merged to the mainline
  after the offending branch is fixed.
 Message-ID: <7vocz8a6zk.fsf@gitster.siamese.dyndns.org>
 References: <alpine.LFD.2.00.0812181949450.14014@localhost.localdomain>
+Content-type: text/asciidoc
+
+Revert a faulty merge
+=====================
 
 Alan <alan@clueserver.org> said:
 
diff --git a/Documentation/howto/separating-topic-branches.txt b/Documentation/howto/separating-topic-branches.txt
index 6d3eb8e..17c1602 100644
--- a/Documentation/howto/separating-topic-branches.txt
+++ b/Documentation/howto/separating-topic-branches.txt
@@ -1,6 +1,10 @@
 From: Junio C Hamano <gitster@pobox.com>
 Subject: Separating topic branches
 Abstract: In this article, JC describes how to separate topic branches.
+Content-type: text/asciidoc
+
+Separating topic branches
+=========================
 
 This text was originally a footnote to a discussion about the
 behaviour of the git diff commands.
diff --git a/Documentation/howto/setup-git-server-over-http.txt b/Documentation/howto/setup-git-server-over-http.txt
index 622ee5c..69dab4b 100644
--- a/Documentation/howto/setup-git-server-over-http.txt
+++ b/Documentation/howto/setup-git-server-over-http.txt
@@ -1,6 +1,10 @@
 From: Rutger Nijlunsing <rutger@nospam.com>
 Subject: Setting up a git repository which can be pushed into and pulled from over HTTP(S).
 Date: Thu, 10 Aug 2006 22:00:26 +0200
+Content-type: text/asciidoc
+
+Setup git server over http
+==========================
 
 Since Apache is one of those packages people like to compile
 themselves while others prefer the bureaucrat's dream Debian, it is
diff --git a/Documentation/howto/update-hook-example.txt b/Documentation/howto/update-hook-example.txt
index b7f8d41..063d967 100644
--- a/Documentation/howto/update-hook-example.txt
+++ b/Documentation/howto/update-hook-example.txt
@@ -5,6 +5,10 @@ Message-ID: <7vfypumlu3.fsf@assigned-by-dhcp.cox.net>
 Abstract: An example hooks/update script is presented to
  implement repository maintenance policies, such as who can push
  into which branch and who can make a tag.
+Content-type: text/asciidoc
+
+Update hook example
+===================
 
 When your developer runs git-push into the repository,
 git-receive-pack is run (either locally or over ssh) as that
@@ -32,8 +36,7 @@ like this as your hooks/update script.
 [jc: editorial note.  This is a much improved version by Carl
 since I posted the original outline]
 
--- >8 -- beginning of script -- >8 --
-
+----------------------------------------------------
 #!/bin/bash
 
 umask 002
@@ -111,12 +114,12 @@ then
 
       info "Found matching head pattern: '$head_pattern'"
       for user_pattern in $user_patterns; do
-	info "Checking user: '$username' against pattern: '$user_pattern'"
-	matchlen=$(expr "$username" : "$user_pattern")
-	if test "$matchlen" = "${#username}"
-	then
-	  grant "Allowing user: '$username' with pattern: '$user_pattern'"
-	fi
+	    info "Checking user: '$username' against pattern: '$user_pattern'"
+	    matchlen=$(expr "$username" : "$user_pattern")
+	    if test "$matchlen" = "${#username}"
+	    then
+	      grant "Allowing user: '$username' with pattern: '$user_pattern'"
+	    fi
       done
       deny "The user is not in the access list for this branch"
     done
@@ -149,13 +152,13 @@ then
 
       info "Found matching head pattern: '$head_pattern'"
       for group_pattern in $group_patterns; do
-	for groupname in $groups; do
-	  info "Checking group: '$groupname' against pattern: '$group_pattern'"
-	  matchlen=$(expr "$groupname" : "$group_pattern")
-	  if test "$matchlen" = "${#groupname}"
-	  then
-	    grant "Allowing group: '$groupname' with pattern: '$group_pattern'"
-	  fi
+	    for groupname in $groups; do
+	      info "Checking group: '$groupname' against pattern: '$group_pattern'"
+	      matchlen=$(expr "$groupname" : "$group_pattern")
+	      if test "$matchlen" = "${#groupname}"
+	      then
+	        grant "Allowing group: '$groupname' with pattern: '$group_pattern'"
+	      fi
         done
       done
       deny "None of the user's groups are in the access list for this branch"
@@ -169,24 +172,21 @@ then
 fi
 
 deny >/dev/null "There are no more rules to check.  Denying access"
-
--- >8 -- end of script -- >8 --
+----------------------------------------------------
 
 This uses two files, $GIT_DIR/info/allowed-users and
 allowed-groups, to describe which heads can be pushed into by
 whom.  The format of each file would look like this:
 
-        refs/heads/master	junio
-	+refs/heads/pu		junio
-        refs/heads/cogito$	pasky
-        refs/heads/bw/.*	linus
-        refs/heads/tmp/.*	.*
-        refs/tags/v[0-9].*	junio
+    refs/heads/master   junio
+    +refs/heads/pu      junio
+    refs/heads/cogito$  pasky
+    refs/heads/bw/.*    linus
+    refs/heads/tmp/.*   .*
+    refs/tags/v[0-9].*  junio
 
 With this, Linus can push or create "bw/penguin" or "bw/zebra"
 or "bw/panda" branches, Pasky can do only "cogito", and JC can
 do master and pu branches and make versioned tags.  And anybody
 can do tmp/blah branches. The '+' sign at the pu record means
 that JC can make non-fast-forward pushes on it.
-
-------------
diff --git a/Documentation/howto/use-git-daemon.txt b/Documentation/howto/use-git-daemon.txt
index 4e2f75c..23cdf35 100644
--- a/Documentation/howto/use-git-daemon.txt
+++ b/Documentation/howto/use-git-daemon.txt
@@ -1,4 +1,7 @@
+Content-type: text/asciidoc
+
 How to use git-daemon
+=====================
 
 Git can be run in inetd mode and in stand alone mode. But all you want is
 let a coworker pull from you, and therefore need to set up a git server
diff --git a/Documentation/howto/using-signed-tag-in-pull-request.txt b/Documentation/howto/using-signed-tag-in-pull-request.txt
index 98c0033..7670449 100644
--- a/Documentation/howto/using-signed-tag-in-pull-request.txt
+++ b/Documentation/howto/using-signed-tag-in-pull-request.txt
@@ -7,8 +7,8 @@ Abstract: Beginning v1.7.9, a contributor can push a signed tag to her
  later validate it.
 Content-type: text/asciidoc
 
-Using signed tag in pull requests
-=================================
+Using signed tag in pull request
+================================
 
 A typical distributed workflow using Git is for a contributor to fork a
 project, build on it, publish the result to her public repository, and ask
-- 
1.7.11.msysgit.1

[Patch 5/5] Create pdf from all html files

[Thomas Ackermann]

- use wkhtmltopdf to combine all html files into a single pdf file "git-doc.pdf"
- provide make target "fullpdf" to create "git-doc.pdf"

Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
---
 Documentation/.gitignore      |  1 +
 Documentation/Makefile        |  9 +++++++++
 Documentation/footerend.txt   |  4 ++++
 Documentation/footerstart.txt |  7 +++++++
 Documentation/makedocpdf.sh   | 25 +++++++++++++++++++++++++
 Makefile                      |  6 ++++++
 6 files changed, 52 insertions(+)
 create mode 100644 Documentation/footerend.txt
 create mode 100644 Documentation/footerstart.txt
 create mode 100644 Documentation/makedocpdf.sh

diff --git a/Documentation/.gitignore b/Documentation/.gitignore
index d62aebd..fba4730 100644
--- a/Documentation/.gitignore
+++ b/Documentation/.gitignore
@@ -10,3 +10,4 @@ howto-index.txt
 doc.dep
 cmds-*.txt
 manpage-base-url.xsl
+docfiles.txt
diff --git a/Documentation/Makefile b/Documentation/Makefile
index abd27b5..c4c2a30 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -189,6 +189,9 @@ info: git.info gitman.info
 
 pdf: user-manual.pdf
 
+fullpdf: pdf all
+	./makedocpdf.sh
+
 install: install-man
 
 install-man: man
@@ -213,6 +216,10 @@ install-pdf: pdf
 	$(INSTALL) -d -m 755 $(DESTDIR)$(pdfdir)
 	$(INSTALL) -m 644 user-manual.pdf $(DESTDIR)$(pdfdir)
 
+install-fullpdf: fullpdf install-pdf
+	$(INSTALL) -d -m 755 $(DESTDIR)$(pdfdir)
+	$(INSTALL) -m 644 git-doc.pdf $(DESTDIR)$(pdfdir)
+
 install-html: html
 	'$(SHELL_PATH_SQ)' ./install-webdoc.sh $(DESTDIR)$(htmldir)
 
@@ -252,6 +259,8 @@ clean:
 	$(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7
 	$(RM) *.texi *.texi+ *.texi++ git.info gitman.info
 	$(RM) *.pdf
+	$(RM) docfiles.txt
+	$(RM) RelNotes/*.html
 	$(RM) howto-index.txt howto/*.html doc.dep
 	$(RM) technical/*.html technical/api-index.txt
 	$(RM) $(cmds_txt) *.made
diff --git a/Documentation/footerend.txt b/Documentation/footerend.txt
new file mode 100644
index 0000000..ed16923
--- /dev/null
+++ b/Documentation/footerend.txt
@@ -0,0 +1,4 @@
+    </td>
+  </tr>
+</table>
+</body></html>
diff --git a/Documentation/footerstart.txt b/Documentation/footerstart.txt
new file mode 100644
index 0000000..a2746ef
--- /dev/null
+++ b/Documentation/footerstart.txt
@@ -0,0 +1,7 @@
+<html>
+<head></head>
+<body style="border:0; margin: 0;" onload="subst()">
+<table style="border-top: 1px solid black; width: 100%">
+  <tr>
+    <td class="section"></td>
+    <td style="text-align:center">
diff --git a/Documentation/makedocpdf.sh b/Documentation/makedocpdf.sh
new file mode 100644
index 0000000..fd9f5bb
--- /dev/null
+++ b/Documentation/makedocpdf.sh
@@ -0,0 +1,25 @@
+#!/bin/sh
+
+rm -f git-doc.pdf
+
+cat /dev/null >docfiles.txt
+
+ls gittutorial.html      >>docfiles.txt
+ls gittutorial-2.html    >>docfiles.txt
+ls everyday.html         >>docfiles.txt
+ls gitworkflows.html     >>docfiles.txt
+ls git-*.html            >>docfiles.txt
+ls git[acdghikmnr]*.html >>docfiles.txt
+ls gitweb*.html          >>docfiles.txt
+ls howto-index.html      >>docfiles.txt
+ls howto/*.html          >>docfiles.txt
+ls technical/*.html      >>docfiles.txt
+ls RelNotes/*.html       >>docfiles.txt
+
+cat /dev/null >footer.html
+
+cat footerstart.txt      >>footer.html
+cat ../GIT-VERSION-FILE  >>footer.html
+cat footerend.txt        >> footer.html
+
+cat docfiles.txt | xargs cat | wkhtmltopdf --book --footer-html footer.html --disable-external-links - git-doc.pdf
diff --git a/Makefile b/Makefile
index 8413606..2ddb3c9 100644
--- a/Makefile
+++ b/Makefile
@@ -2485,6 +2485,9 @@ info:
 pdf:
 	$(MAKE) -C Documentation pdf
 
+fullpdf:
+	$(MAKE) -C Documentation fullpdf
+
 XGETTEXT_FLAGS = \
 	--force-po \
 	--add-comments \
@@ -2796,6 +2799,9 @@ install-info:
 install-pdf:
 	$(MAKE) -C Documentation install-pdf
 
+install-fullpdf:
+	$(MAKE) -C Documentation install-fullpdf
+
 quick-install-doc:
 	$(MAKE) -C Documentation quick-install
 
-- 
1.7.11.msysgit.1

Re: [Patch 1/5] Fix some asciidoc layout problems

[Junio C Hamano]

Thomas Ackermann <th.acker66@arcor.de> writes:

> Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
> ---
>  Documentation/git-bisect-lk2009.txt | 12 ++++++------
>  Documentation/git-fetch-pack.txt    |  5 ++++-
>  2 files changed, 10 insertions(+), 7 deletions(-)

You didn't say what "layout problem" you are fixing, or what the
approach you took to "fix" it.  From the patch, I can guess that the
latter is to lengthen the lines that surround the displayed examples,
but as far as I know and can tell, the existing ones are long enough
so I cannot tell why you needed such a change to the source in the
first place.

A better explanation, please?

The synopsis section of git-fetch-pack manual is a long single line
which is unsightly.  A fix to that issue is indeed needed.  Please
make a separate patch only for that issue.  Is git-fetch-pack the
only one whose synopsis section is overlong, by the way?

Thanks.

>
> diff --git a/Documentation/git-bisect-lk2009.txt b/Documentation/git-bisect-lk2009.txt
> index 8a2ba37..99bdb46 100644
> --- a/Documentation/git-bisect-lk2009.txt
> +++ b/Documentation/git-bisect-lk2009.txt
> @@ -248,7 +248,7 @@ Bisecting: 5480 revisions left to test after this (roughly 13 steps)
>  And after a few more steps like that, "git bisect" will eventually
>  find a first bad commit:
>  
> --------------
> +------------------------------------------------------------------------------------------------------------
>  $ git bisect bad
>  2ddcca36c8bcfa251724fe342c8327451988be0d is the first bad commit
>  commit 2ddcca36c8bcfa251724fe342c8327451988be0d
> @@ -257,8 +257,8 @@ Date:   Sat May 3 11:59:44 2008 -0700
>  
>      Linux 2.6.26-rc1
>  
> -:100644 100644 5cf8258195331a4dbdddff08b8d68642638eea57 4492984efc09ab72ff6219a7bc21fb6a957c4cd5 M      Makefile
> --------------
> +:100644 100644 5cf8258195331a4dbdddff08b8d68642638eea57 4492984efc09ab72ff6219a7bc21fb6a957c4cd5 M  Makefile
> +------------------------------------------------------------------------------------------------------------
>  
>  At this point we can see what the commit does, check it out (if it's
>  not already checked out) or tinker with it, for example:
> @@ -305,7 +305,7 @@ to launch a script or command at each bisection step to know if the
>  current commit is "good" or "bad". To do that, we use the "git bisect
>  run" command. For example:
>  
> --------------
> +------------------------------------------------------------------------------------------------------------
>  $ git bisect start v2.6.27 v2.6.25
>  Bisecting: 10928 revisions left to test after this (roughly 14 steps)
>  [2ec65f8b89ea003c27ff7723525a2ee335a2b393] x86: clean up using max_low_pfn on 32-bit
> @@ -331,9 +331,9 @@ Date:   Sat May 3 11:59:44 2008 -0700
>  
>      Linux 2.6.26-rc1
>  
> -:100644 100644 5cf8258195331a4dbdddff08b8d68642638eea57 4492984efc09ab72ff6219a7bc21fb6a957c4cd5 M      Makefile
> +:100644 100644 5cf8258195331a4dbdddff08b8d68642638eea57 4492984efc09ab72ff6219a7bc21fb6a957c4cd5 M  Makefile
>  bisect run success
> --------------
> +------------------------------------------------------------------------------------------------------------
>  
>  In this example, we passed "grep '^SUBLEVEL = 25' Makefile" as
>  parameter to "git bisect run". This means that at each step, the grep
> diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt
> index 474fa30..12cd8a2 100644
> --- a/Documentation/git-fetch-pack.txt
> +++ b/Documentation/git-fetch-pack.txt
> @@ -9,7 +9,10 @@ git-fetch-pack - Receive missing objects from another repository
>  SYNOPSIS
>  --------
>  [verse]
> -'git fetch-pack' [--all] [--quiet|-q] [--keep|-k] [--thin] [--include-tag] [--upload-pack=<git-upload-pack>] [--depth=<n>] [--no-progress] [-v] [<host>:]<directory> [<refs>...]
> +'git fetch-pack' [--all] [--quiet|-q] [--keep|-k] [--thin] [--include-tag] 
> +				[--upload-pack=<git-upload-pack>] 
> +				[--depth=<n>] [--no-progress] 
> +				[-v] [<host>:]<directory> [<refs>...]
>  
>  DESCRIPTION
>  -----------

Re: [Patch 2/5] Create html documents for all files in Documentation/technical

[Philip Oakley]

From: "Thomas Ackermann" <th.acker66@arcor.de>
>- add missing files
> - fix some asciidoc layout problems
>
> Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
> ---
> Documentation/Makefile                    | 12 ++++++++++-
> Documentation/technical/index-format.txt  |  2 +-
> Documentation/technical/pack-format.txt   |  8 +++----
> Documentation/technical/pack-protocol.txt |  7 +++---
> Documentation/technical/shallow.txt       |  8 ++++++-
> Documentation/technical/trivial-merge.txt | 36 
> +++++++++++++++----------------
> 6 files changed, 45 insertions(+), 28 deletions(-)
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 267dfe1..86594f6 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -25,6 +25,16 @@ SP_ARTICLES += howto/revert-branch-rebase
> SP_ARTICLES += howto/using-merge-subtree
> SP_ARTICLES += howto/using-signed-tag-in-pull-request
> API_DOCS = $(patsubst %.txt,%,$(filter-out 
> technical/api-index-skel.txt technical/api-index.txt, $(wildcard 
> technical/api-*.txt)))
> +API_DOCS += technical/index-format

Would it not be better to create a separate TECH_DOCS list, rather than 
confuse the API_DOCS list?

> +API_DOCS += technical/pack-format
> +API_DOCS += technical/pack-heuristics
> +API_DOCS += technical/pack-protocol
> +API_DOCS += technical/protocol-capabilities
> +API_DOCS += technical/protocol-common
> +API_DOCS += technical/racy-git
> +API_DOCS += technical/send-pack-pipeline
> +API_DOCS += technical/shallow
> +API_DOCS += technical/trivial-merge
> SP_ARTICLES += $(API_DOCS)
> SP_ARTICLES += technical/api-index
>
> @@ -231,7 +241,7 @@ clean:
>  $(RM) *.texi *.texi+ *.texi++ git.info gitman.info
>  $(RM) *.pdf
>  $(RM) howto-index.txt howto/*.html doc.dep
> - $(RM) technical/api-*.html technical/api-index.txt
> + $(RM) technical/*.html technical/api-index.txt
>  $(RM) $(cmds_txt) *.made
>  $(RM) manpage-base-url.xsl
>
> diff --git a/Documentation/technical/index-format.txt 
> b/Documentation/technical/index-format.txt
> index 9d25b30..57d6f91 100644
> --- a/Documentation/technical/index-format.txt
> +++ b/Documentation/technical/index-format.txt
> @@ -1,7 +1,7 @@
> GIT index format
> ================
>
> -= The git index file has the following format
> +== The git index file has the following format
>
<snip> 

Re: [Patch 3/5] Create html documents for all files in Documentation/RelNotes

[Philip Oakley]

From: "Thomas Ackermann" <th.acker66@arcor.de>
>- create html for all release note files
> - fix some asciidoc layout problems
>
> Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
> ---
> Documentation/Makefile             | 2 ++
> Documentation/RelNotes/1.5.2.1.txt | 6 ------
> Documentation/RelNotes/1.6.0.2.txt | 6 ------
> Documentation/RelNotes/1.6.1.3.txt | 4 ----
> Documentation/RelNotes/1.6.1.4.txt | 3 ---
> Documentation/RelNotes/1.6.1.txt   | 6 ------
> 6 files changed, 2 insertions(+), 25 deletions(-)
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 86594f6..80eb06d 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -24,6 +24,7 @@ SP_ARTICLES = user-manual
> SP_ARTICLES += howto/revert-branch-rebase
> SP_ARTICLES += howto/using-merge-subtree
> SP_ARTICLES += howto/using-signed-tag-in-pull-request
> +RELNOTES = $(patsubst %.txt,%,$(wildcard RelNotes/*.txt))
> API_DOCS = $(patsubst %.txt,%,$(filter-out 
> technical/api-index-skel.txt technical/api-index.txt, $(wildcard 
> technical/api-*.txt)))
> API_DOCS += technical/index-format
> API_DOCS += technical/pack-format
> @@ -35,6 +36,7 @@ API_DOCS += technical/racy-git
> API_DOCS += technical/send-pack-pipeline
> API_DOCS += technical/shallow
> API_DOCS += technical/trivial-merge
> +API_DOCS += $(RELNOTES)

Again, is this the right docs list?

> SP_ARTICLES += $(API_DOCS)
> SP_ARTICLES += technical/api-index
>
<snip> 

Re: [Patch 1/5] Fix some asciidoc layout problems

[Jeff King]

On Sat, Oct 06, 2012 at 11:39:13AM -0700, Junio C Hamano wrote:

> Thomas Ackermann <th.acker66@arcor.de> writes:
> 
> > Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
> > ---
> >  Documentation/git-bisect-lk2009.txt | 12 ++++++------
> >  Documentation/git-fetch-pack.txt    |  5 ++++-
> >  2 files changed, 10 insertions(+), 7 deletions(-)
> 
> You didn't say what "layout problem" you are fixing, or what the
> approach you took to "fix" it.  From the patch, I can guess that the
> latter is to lengthen the lines that surround the displayed examples,
> but as far as I know and can tell, the existing ones are long enough
> so I cannot tell why you needed such a change to the source in the
> first place.
> 
> A better explanation, please?

I had the same question. Also, some of the lines convert tabs in literal
output into spaces, which is actively wrong (or maybe they were
converted already to spaces in the current code, but they should at
least align with 8-space tabstops):

> > -:100644 100644 5cf8258195331a4dbdddff08b8d68642638eea57 4492984efc09ab72ff6219a7bc21fb6a957c4cd5 M      Makefile
> > +:100644 100644 5cf8258195331a4dbdddff08b8d68642638eea57 4492984efc09ab72ff6219a7bc21fb6a957c4cd5 M  Makefile

-Peff

Re: [Patch 5/5] Create pdf from all html files

[Jeff King]

On Sat, Oct 06, 2012 at 05:58:01PM +0200, Thomas Ackermann wrote:

> - use wkhtmltopdf to combine all html files into a single pdf file "git-doc.pdf"
> - provide make target "fullpdf" to create "git-doc.pdf"
> 
> Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
> ---
>  Documentation/.gitignore      |  1 +
>  Documentation/Makefile        |  9 +++++++++
>  Documentation/footerend.txt   |  4 ++++
>  Documentation/footerstart.txt |  7 +++++++
>  Documentation/makedocpdf.sh   | 25 +++++++++++++++++++++++++
>  Makefile                      |  6 ++++++
>  6 files changed, 52 insertions(+)
>  create mode 100644 Documentation/footerend.txt
>  create mode 100644 Documentation/footerstart.txt
>  create mode 100644 Documentation/makedocpdf.sh

The makedocpdf script has no execute bit, but...

> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index abd27b5..c4c2a30 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -189,6 +189,9 @@ info: git.info gitman.info
>  
>  pdf: user-manual.pdf
>  
> +fullpdf: pdf all
> +	./makedocpdf.sh

Here we try to run it.

-Peff

Re: [Patch 3/5] Create html documents for all files in Documentation/RelNotes

[Jeff King]

On Sat, Oct 06, 2012 at 05:55:58PM +0200, Thomas Ackermann wrote:

> - create html for all release note files
> [...]
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 86594f6..80eb06d 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -24,6 +24,7 @@ SP_ARTICLES = user-manual
>  SP_ARTICLES += howto/revert-branch-rebase
>  SP_ARTICLES += howto/using-merge-subtree
>  SP_ARTICLES += howto/using-signed-tag-in-pull-request
> +RELNOTES = $(patsubst %.txt,%,$(wildcard RelNotes/*.txt))
>  API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
>  API_DOCS += technical/index-format
>  API_DOCS += technical/pack-format
> @@ -35,6 +36,7 @@ API_DOCS += technical/racy-git
>  API_DOCS += technical/send-pack-pipeline
>  API_DOCS += technical/shallow
>  API_DOCS += technical/trivial-merge
> +API_DOCS += $(RELNOTES)

Yuck. This means that anyone generating the html documentation will have
to format all of the release notes, too, even though they are much less
likely to be useful[1]. If this is only useful for the fullpdf target,
can we omit it from the regular html target (and maybe add a "relnotes"
target or something for people who really want them formatted)?

-Peff

[1] I would not be surprised if they do not actually format all that
    well. Though they are written in an asciidoc-ish style, they have
    not traditionally been formatted, and I suspect there are many small
    errors (like improper quoting of metacharacters) in them.

Re: [Patch 0/5] Create single PDF for all HTML files

[Jeff King]

On Sat, Oct 06, 2012 at 05:51:15PM +0200, Thomas Ackermann wrote:

> I wanted to have a single PDF file which contains the complete Git documentation 
> (except user-manual) for easier reading on my tablet. The simplest way to do 
> this was by using wkhtmltopdf which can combine a set of HTML files into a sinlge 
> PDF file and also apply some reformatting. To this end HTML files for all the missing 
> files in Documentation/technical and Documentation/howto and also for all the 
> release notes in Documentation/RelNotes were created. 

It seems like a reasonable goal. I do not have a strong opinion on the
approach or how the final output looks, but I wasn't able to actually
get output at all after applying your patches. Running "make fullpdf"
(after installing dblatex) got me:

  The switch --book, is not support using unpatched qt, and will be
  ignored.The switch --footer-html, is not support using unpatched qt,
  and will be ignored.The switch --disable-external-links, is not
  support using unpatched qt, and will be ignored.

after which wkhtmltopdf began pegging my CPU. I let it run for 10
minutes before giving up.

Another way of doing this would be to format the individual troff
manpages into dvi or postscript, convert that into pdf, and then
concatenate that. Something like:

  for i in *.[157]; do
    man -Tdvi -l "$i" >"$i.dvi"
    dvipdfm "$i"
  done
  pdftk *.[157].pdf cat output full.pdf

works for me, though obviously that does not handle some of the non-man
items you included. No idea on how the output compares to yours, but
it's something you may want to look at.

-Peff

Aw: Re: [Patch 1/5] Fix some asciidoc layout problems

[Thomas Ackermann]

 
Making the dashed lines longer was unnecessary and I will remove this.

There were in general the following "layout problems" I encountered while trying to create git-doc.pdf:

- Wrong sectioning syntax (e.g. "===" instead of "---")
- Left-over shell scripting commands (in some release notes files)
- Over-long lines which caused very wide right margins in the resulting pdf

The later is the case here and I tried to fix this by either splitting the offending line in several lines
or removing as much spaces as possible.

I will be more specific about these things in my commit messages.


----- Original Nachricht ----
Von:     Jeff King <peff@peff.net>
An:      Junio C Hamano <gitster@pobox.com>
Datum:   06.10.2012 21:10
Betreff: Re: [Patch 1/5] Fix some asciidoc layout problems

> On Sat, Oct 06, 2012 at 11:39:13AM -0700, Junio C Hamano wrote:
> 
> > Thomas Ackermann <th.acker66@arcor.de> writes:
> > 
> > > Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
> > > ---
> > >  Documentation/git-bisect-lk2009.txt | 12 ++++++------
> > >  Documentation/git-fetch-pack.txt    |  5 ++++-
> > >  2 files changed, 10 insertions(+), 7 deletions(-)
> > 
> > You didn't say what "layout problem" you are fixing, or what the
> > approach you took to "fix" it.  From the patch, I can guess that the
> > latter is to lengthen the lines that surround the displayed examples,
> > but as far as I know and can tell, the existing ones are long enough
> > so I cannot tell why you needed such a change to the source in the
> > first place.
> > 
> > A better explanation, please?
> 
> I had the same question. Also, some of the lines convert tabs in literal
> output into spaces, which is actively wrong (or maybe they were
> converted already to spaces in the current code, but they should at
> least align with 8-space tabstops):
> 
> > > -:100644 100644 5cf8258195331a4dbdddff08b8d68642638eea57
> 4492984efc09ab72ff6219a7bc21fb6a957c4cd5 M      Makefile
> > > +:100644 100644 5cf8258195331a4dbdddff08b8d68642638eea57
> 4492984efc09ab72ff6219a7bc21fb6a957c4cd5 M  Makefile
> 
> -Peff
> 

---
Thomas

Aw: Re: [Patch 0/5] Create single PDF for all HTML files

[Thomas Ackermann]

There are "patched QT" and "unpatched QT" versions of wkhtmltopdf
(see http://code.google.com/p/wkhtmltopdf/). I am using V0.9.9 for Windows
which is "patched QT".

There is one drawback with wkhtmltopdf: At least on my Netbook (Win7 64bit,
Pentium 1.5GHz) it is very slow. It takes more than 3 hrs to create git-doc.pdf.

If you want to have a quick look on the resulting pdf just clone 
https://github.com/tacker66/git-docpdf.git. This repo contains
a current version of user.manual.pdf and git-doc.pdf 


----- Original Nachricht ----
Von:     Jeff King <peff@peff.net>
An:      Thomas Ackermann <th.acker66@arcor.de>
Datum:   06.10.2012 21:32
Betreff: Re: [Patch 0/5] Create single PDF for all HTML files

> On Sat, Oct 06, 2012 at 05:51:15PM +0200, Thomas Ackermann wrote:
> 
> > I wanted to have a single PDF file which contains the complete Git
> documentation 
> > (except user-manual) for easier reading on my tablet. The simplest way to
> do 
> > this was by using wkhtmltopdf which can combine a set of HTML files into a
> sinlge 
> > PDF file and also apply some reformatting. To this end HTML files for all
> the missing 
> > files in Documentation/technical and Documentation/howto and also for all
> the 
> > release notes in Documentation/RelNotes were created. 
> 
> It seems like a reasonable goal. I do not have a strong opinion on the
> approach or how the final output looks, but I wasn't able to actually
> get output at all after applying your patches. Running "make fullpdf"
> (after installing dblatex) got me:
> 
>   The switch --book, is not support using unpatched qt, and will be
>   ignored.The switch --footer-html, is not support using unpatched qt,
>   and will be ignored.The switch --disable-external-links, is not
>   support using unpatched qt, and will be ignored.
> 
> after which wkhtmltopdf began pegging my CPU. I let it run for 10
> minutes before giving up.
> 
> Another way of doing this would be to format the individual troff
> manpages into dvi or postscript, convert that into pdf, and then
> concatenate that. Something like:
> 
>   for i in *.[157]; do
>     man -Tdvi -l "$i" >"$i.dvi"
>     dvipdfm "$i"
>   done
>   pdftk *.[157].pdf cat output full.pdf
> 
> works for me, though obviously that does not handle some of the non-man
> items you included. No idea on how the output compares to yours, but
> it's something you may want to look at.
> 
> -Peff
> 

---
Thomas

Re: [Patch 3/5] Create html documents for all files in Documentation/RelNotes

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> [1] I would not be surprised if they do not actually format all that
>     well. Though they are written in an asciidoc-ish style, they have
>     not traditionally been formatted, and I suspect there are many small
>     errors (like improper quoting of metacharacters) in them.

They aren't even "errors". As far as I (who writes the release
notes) am concerned, they are straight text without any asciidoc
or markdown mark-up.

Re: [Patch 0/5] Create single PDF for all HTML files

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> Another way of doing this would be to format the individual troff
> manpages into dvi or postscript, convert that into pdf, and then
> concatenate that. Something like:
>
>   for i in *.[157]; do
>     man -Tdvi -l "$i" >"$i.dvi"
>     dvipdfm "$i"
>   done
>   pdftk *.[157].pdf cat output full.pdf
>
> works for me, though obviously that does not handle some of the non-man
> items you included. No idea on how the output compares to yours, but
> it's something you may want to look at.

Yes, that would be far more straight-forward and less error prone
way to do this.

Re: Re: [Patch 0/5] Create single PDF for all HTML files

[Jeff King]

On Sun, Oct 07, 2012 at 10:14:28AM +0200, Thomas Ackermann wrote:

> There are "patched QT" and "unpatched QT" versions of wkhtmltopdf
> (see http://code.google.com/p/wkhtmltopdf/). I am using V0.9.9 for Windows
> which is "patched QT".

That's a definite compatibility question for taking your patches into
upstream git.

> There is one drawback with wkhtmltopdf: At least on my Netbook (Win7 64bit,
> Pentium 1.5GHz) it is very slow. It takes more than 3 hrs to create git-doc.pdf.
> 
> If you want to have a quick look on the resulting pdf just clone 
> https://github.com/tacker66/git-docpdf.git. This repo contains
> a current version of user.manual.pdf and git-doc.pdf 

It does look better than the output generated by the "man -Tdvi" loop I
posted. It retains more styling from the HTML and it has a nice table of
contents. But 3 hours? Yeesh. Mine took 11 seconds.

I wonder if a more sane route is to drop HTML entirely, convert the
asciidoc to docbook (which we already do for manpages), and then create
a docbook document that is a collection of all elements, which can then
be converted to pdf, epub, or whatever. I would not be surprised if
somebody has solved this problem before (but it is not really my itch,
so I did not look very far).

-Peff

Re: Re: [Patch 0/5] Create single PDF for all HTML files

[Philip Oakley]

From: "Thomas Ackermann" <th.acker66@arcor.de>
>
> There are "patched QT" and "unpatched QT" versions of wkhtmltopdf
> (see http://code.google.com/p/wkhtmltopdf/). I am using V0.9.9 for 
> Windows
> which is "patched QT".
>
> There is one drawback with wkhtmltopdf: At least on my Netbook (Win7 
> 64bit,
> Pentium 1.5GHz) it is very slow. It takes more than 3 hrs to create 
> git-doc.pdf.
>
> If you want to have a quick look on the resulting pdf just clone
> https://github.com/tacker66/git-docpdf.git. This repo contains
> a current version of user.manual.pdf and git-doc.pdf
>

Even as a 'draft' I found it to be useful to see all the documentation 
collated together in one place/pdf. All 763 pages!

Even just reading through the contents list (34 pages) showed the scale 
of the git documentation, and areas of documentation I wasn't aware of.

Putting the Tutorials, Everyday GIT and workflows at the beginning 
looked good.

For a polished version it would be good if the major breaks (e.g. 
between ToC, gittutorial, git-add [should start with git(1)], 
gitattributes, GIT Howto, API, Git Index Format, ReleaseNotes) could 
start on a new page.

A few minor nits: I wasn't sure if the 'fighting regressions with git 
bisect', and 'a short git tools survey' were in the right place. There 
appear to be two 'git-send-pack' titles, though they are different. And 
the HowTo section would need some beefed up headings to give them enough 
prominence in the ToC once it all hangs together.

>
> ----- Original Nachricht ----
> Von:     Jeff King <peff@peff.net>
> An:      Thomas Ackermann <th.acker66@arcor.de>
> Datum:   06.10.2012 21:32
> Betreff: Re: [Patch 0/5] Create single PDF for all HTML files
>
>> On Sat, Oct 06, 2012 at 05:51:15PM +0200, Thomas Ackermann wrote:
>>
>> > I wanted to have a single PDF file which contains the complete Git
>> documentation
>> > (except user-manual) for easier reading on my tablet. The simplest 
>> > way to
>> do
>> > this was by using wkhtmltopdf which can combine a set of HTML files 
>> > into a
>> sinlge
>> > PDF file and also apply some reformatting. To this end HTML files 
>> > for all
>> the missing
>> > files in Documentation/technical and Documentation/howto and also 
>> > for all
>> the
>> > release notes in Documentation/RelNotes were created.
>>
>> It seems like a reasonable goal. I do not have a strong opinion on 
>> the
>> approach or how the final output looks, but I wasn't able to actually
>> get output at all after applying your patches. Running "make fullpdf"
>> (after installing dblatex) got me:
>>
>>   The switch --book, is not support using unpatched qt, and will be
>>   ignored.The switch --footer-html, is not support using unpatched 
>> qt,
>>   and will be ignored.The switch --disable-external-links, is not
>>   support using unpatched qt, and will be ignored.
>>
>> after which wkhtmltopdf began pegging my CPU. I let it run for 10
>> minutes before giving up.
>>
>> Another way of doing this would be to format the individual troff
>> manpages into dvi or postscript, convert that into pdf, and then
>> concatenate that. Something like:
>>
>>   for i in *.[157]; do
>>     man -Tdvi -l "$i" >"$i.dvi"
>>     dvipdfm "$i"
>>   done
>>   pdftk *.[157].pdf cat output full.pdf
>>
>> works for me, though obviously that does not handle some of the 
>> non-man
>> items you included. No idea on how the output compares to yours, but
>> it's something you may want to look at.
>>
>> -Peff
>>
>
> ---
> Thomas
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>
>
> -----
> No virus found in this message.
> Checked by AVG - www.avg.com
> Version: 2013.0.2677 / Virus Database: 2591/5813 - Release Date: 
> 10/06/12
> 

Re: [Patch 3/5] Create html documents for all files in Documentation/RelNotes

[Michael J Gruber]

Junio C Hamano venit, vidit, dixit 07.10.2012 22:53:
> Jeff King <peff@peff.net> writes:
> 
>> [1] I would not be surprised if they do not actually format all that
>>     well. Though they are written in an asciidoc-ish style, they have
>>     not traditionally been formatted, and I suspect there are many small
>>     errors (like improper quoting of metacharacters) in them.
> 
> They aren't even "errors". As far as I (who writes the release
> notes) am concerned, they are straight text without any asciidoc
> or markdown mark-up.

I'm wondering: If it's neither markdown nor markup then what is it:
marklevel, markeven or markstraight?

Seriously, if Thomas converts them into asciidoc it's an added benefit
(and I don't think you'd have to change your writing by much), but
RelNotes should not be in the standard make target.

On a different note: Is pdf really the format of choice for mobile
platforms? I'd expect something that is "formatted" (markup) but can
reflow text intrinsically, not only by making your pdf reader jump
through hoops. HTML?

Michael

Re: [Patch 0/5] Create single PDF for all HTML files

[Michael J Gruber]

Jeff King venit, vidit, dixit 08.10.2012 00:52:
> On Sun, Oct 07, 2012 at 10:14:28AM +0200, Thomas Ackermann wrote:
> 
>> There are "patched QT" and "unpatched QT" versions of wkhtmltopdf
>> (see http://code.google.com/p/wkhtmltopdf/). I am using V0.9.9 for Windows
>> which is "patched QT".
> 
> That's a definite compatibility question for taking your patches into
> upstream git.
> 
>> There is one drawback with wkhtmltopdf: At least on my Netbook (Win7 64bit,
>> Pentium 1.5GHz) it is very slow. It takes more than 3 hrs to create git-doc.pdf.
>>
>> If you want to have a quick look on the resulting pdf just clone 
>> https://github.com/tacker66/git-docpdf.git. This repo contains
>> a current version of user.manual.pdf and git-doc.pdf 
> 
> It does look better than the output generated by the "man -Tdvi" loop I
> posted. It retains more styling from the HTML and it has a nice table of
> contents. But 3 hours? Yeesh. Mine took 11 seconds.
> 
> I wonder if a more sane route is to drop HTML entirely, convert the
> asciidoc to docbook (which we already do for manpages), and then create
> a docbook document that is a collection of all elements, which can then

Hmm, I think the html output often looks better than the man output
(tables and such), and it is a formatted, reflowable, interlinked format
fit for many puposes.

> be converted to pdf, epub, or whatever. I would not be surprised if
> somebody has solved this problem before (but it is not really my itch,
> so I did not look very far).

I'd rather ditch docbook and have one toolchain (asciidoc, unless we
want to switch to something else) only... We've been hunting asciidoc as
well as docbook compatibility (between versions) and interoperability
(between them) issues again and again.

In fact, if I remember correctly, that's what has been keeping us from
using *real* tables in the doc (but hasn't kept us from using tables ;) ).

Michael

Re: [Patch 0/5] Create single PDF for all HTML files

[Jeff King]

On Mon, Oct 15, 2012 at 01:55:51PM +0200, Michael J Gruber wrote:

> > I wonder if a more sane route is to drop HTML entirely, convert the
> > asciidoc to docbook (which we already do for manpages), and then create
> > a docbook document that is a collection of all elements, which can then
> 
> Hmm, I think the html output often looks better than the man output
> (tables and such), and it is a formatted, reflowable, interlinked format
> fit for many puposes.

It does look better, but that is because the docbook->roff step is where
things get ugly. In theory, docbook is at least as expressive as HTML,
and has lots of nice semantic markup that gives us flexibility in what
the final product looks like.

There are docbook->epub converters (I think xmlto will do this out of
the box), as well as a host of other formats. But convincing docbook to
create a collection of "refentry" (their term for manpage) articles is
harder than you'd think. I tried a few things when this thread started
and couldn't get anything simple to work (xml has managed to make the
simple act of "include this document in this other document" insanely
complex). But I only spent a few minutes on it.

> > be converted to pdf, epub, or whatever. I would not be surprised if
> > somebody has solved this problem before (but it is not really my itch,
> > so I did not look very far).
> 
> I'd rather ditch docbook and have one toolchain (asciidoc, unless we
> want to switch to something else) only... We've been hunting asciidoc as
> well as docbook compatibility (between versions) and interoperability
> (between them) issues again and again.

Yeah, I really hate our doc toolchain. It just seems like everything
else is even worse. We can ditch docbook, but then how do we make
manpages?

-Peff

Re: [Patch 3/5] Create html documents for all files in Documentation/RelNotes

[Junio C Hamano]

Michael J Gruber <git@drmicha.warpmail.net> writes:

> Junio C Hamano venit, vidit, dixit 07.10.2012 22:53:
>> Jeff King <peff@peff.net> writes:
>> 
>>> [1] I would not be surprised if they do not actually format all that
>>>     well. Though they are written in an asciidoc-ish style, they have
>>>     not traditionally been formatted, and I suspect there are many small
>>>     errors (like improper quoting of metacharacters) in them.
>> 
>> They aren't even "errors". As far as I (who writes the release
>> notes) am concerned, they are straight text without any asciidoc
>> or markdown mark-up.
>
> I'm wondering: If it's neither markdown nor markup then what is it:
> marklevel, markeven or markstraight?

They are called plain text.

> On a different note: Is pdf really the format of choice for mobile
> platforms? I'd expect something that is "formatted" (markup) but can
> reflow text intrinsically, not only by making your pdf reader jump
> through hoops. HTML?

Yeah, I've been wondering if epub or something might be a better
target myself.