[RFC/PATCH] Add support for a pdf version of the user manual

[RFC/PATCH] Add support for a pdf version of the user manual

[Miklos Vajna]

Use dblatex in order to create a pdf version of the git user manual.  No
existing Makefile targets (including "all") are touched, so you need to
explicitly say

make pdf
sudo make install-pdf

to get user-manual.pdf created and installed.

Signed-off-by: Miklos Vajna <vmiklos@frugalware.org>
---

Hi,

It turns out that people prefer reading long documents (such as the User
Manual) in a pdf reader, rather then in a web browser. This patch makes
them happy.

I marked it RFC as I'm not sure if using the asciidoc dblatex sty and
xsl file is a good idea or not.

(Oh and because we are in the rc period and this is not a bugfix.)

The other (info/man/html) formats do not make use of the config files in
/etc/asciidoc, so maybe it would be better to just copy them in the
Documentation dir. OTOH I did not want to cause a duplication without a
good reason.

Opinions?

Thanks.

 Documentation/Makefile |   13 +++++++++++++
 INSTALL                |    3 +++
 Makefile               |    6 ++++++
 3 files changed, 22 insertions(+), 0 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index c34c1ca..69f4ade 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -32,6 +32,7 @@ DOC_MAN7=$(patsubst %.txt,%.7,$(MAN7_TXT))
 prefix?=$(HOME)
 bindir?=$(prefix)/bin
 htmldir?=$(prefix)/share/doc/git-doc
+pdfdir?=$(prefix)/share/doc/git-doc
 mandir?=$(prefix)/share/man
 man1dir=$(mandir)/man1
 man5dir=$(mandir)/man5
@@ -50,6 +51,7 @@ infodir?=$(prefix)/share/info
 MAKEINFO=makeinfo
 INSTALL_INFO=install-info
 DOCBOOK2X_TEXI=docbook2x-texi
+DBLATEX=dblatex
 ifndef PERL_PATH
 	PERL_PATH = /usr/bin/perl
 endif
@@ -87,6 +89,8 @@ man7: $(DOC_MAN7)
 
 info: git.info gitman.info
 
+pdf: user-manual.pdf
+
 install: install-man
 
 install-man: man
@@ -107,6 +111,10 @@ install-info: info
 	  echo "No directory found in $(DESTDIR)$(infodir)" >&2 ; \
 	fi
 
+install-pdf: pdf
+	$(INSTALL) -d -m 755 $(DESTDIR)$(pdfdir)
+	$(INSTALL) -m 644 user-manual.pdf $(DESTDIR)$(pdfdir)
+
 install-html: html
 	sh ./install-webdoc.sh $(DESTDIR)$(htmldir)
 
@@ -190,6 +198,11 @@ user-manual.texi: user-manual.xml
 	$(DOCBOOK2X_TEXI) user-manual.xml --to-stdout | $(PERL_PATH) fix-texi.perl >$@+
 	mv $@+ $@
 
+user-manual.pdf: user-manual.xml
+	$(RM) $@+ $@
+	$(DBLATEX) -o $@+ -p /etc/asciidoc/dblatex/asciidoc-dblatex.xsl -s /etc/asciidoc/dblatex/asciidoc-dblatex.sty $<
+	mv $@+ $@
+
 gitman.texi: $(MAN_XML) cat-texi.perl
 	$(RM) $@+ $@
 	($(foreach xml,$(MAN_XML),$(DOCBOOK2X_TEXI) --to-stdout $(xml);)) | \
diff --git a/INSTALL b/INSTALL
index d1deb0b..ae7f750 100644
--- a/INSTALL
+++ b/INSTALL
@@ -101,6 +101,9 @@ Issues of note:
    Building and installing the info file additionally requires
    makeinfo and docbook2X.  Version 0.8.3 is known to work.
 
+   Building and installing the pdf file additionally requires
+   dblatex.  Version 0.2.7 with asciidoc >= 8.2.7 is known to work.
+
    The documentation is written for AsciiDoc 7, but "make
    ASCIIDOC8=YesPlease doc" will let you format with AsciiDoc 8.
 
diff --git a/Makefile b/Makefile
index 5158197..b1456a2 100644
--- a/Makefile
+++ b/Makefile
@@ -1306,6 +1306,9 @@ html:
 info:
 	$(MAKE) -C Documentation info
 
+pdf:
+	$(MAKE) -C Documentation pdf
+
 TAGS:
 	$(RM) TAGS
 	$(FIND) . -name '*.[hcS]' -print | xargs etags -a
@@ -1448,6 +1451,9 @@ install-html:
 install-info:
 	$(MAKE) -C Documentation install-info
 
+install-pdf:
+	$(MAKE) -C Documentation install-pdf
+
 quick-install-doc:
 	$(MAKE) -C Documentation quick-install
 
-- 
1.6.1.rc1.35.gae26e.dirty

Re: [RFC/PATCH] Add support for a pdf version of the user manual

[Leo Razoumov]

On 12/10/08, Miklos Vajna <vmiklos@frugalware.org> wrote:
> Use dblatex in order to create a pdf version of the git user manual.  No
>  existing Makefile targets (including "all") are touched, so you need to
>  explicitly say
>
>  make pdf
>  sudo make install-pdf
>
>  to get user-manual.pdf created and installed.
>

Thanks a lot! Having manual in pdf forms rocks!
BTW, for those of us without dblatex, is it possible to have pdf
manual pregenerated the same way html and man pages are pregenerated
for official releases in the git repo?? I would love to have pdf (and
'info' for that matter) branch in addition to html and man branches.

--Leo--

Re: [RFC/PATCH] Add support for a pdf version of the user manual

[Junio C Hamano]

"Leo Razoumov" <slonik.az@gmail.com> writes:

> BTW, for those of us without dblatex, is it possible to have pdf
> manual pregenerated the same way html and man pages are pregenerated
> for official releases in the git repo?

Those of us includes myself, so...

Re: [RFC/PATCH] Add support for a pdf version of the user manual

[Leo Razoumov]

On 12/10/08, Junio C Hamano <gitster@pobox.com> wrote:
> "Leo Razoumov" <slonik.az@gmail.com> writes:
>
>  > BTW, for those of us without dblatex, is it possible to have pdf
>  > manual pregenerated the same way html and man pages are pregenerated
>  > for official releases in the git repo?
>
>
> Those of us includes myself, so...

Ouch:-) Does it mean that such a useful patch has a low probability of
being accepted?

Re: [RFC/PATCH] Add support for a pdf version of the user manual

[Miklos Vajna]

[-- Attachment #1: Type: text/plain, Size: 1073 bytes --]

On Wed, Dec 10, 2008 at 07:20:42PM -0500, Leo Razoumov <slonik.az@gmail.com> wrote:
> On 12/10/08, Junio C Hamano <gitster@pobox.com> wrote:
> > "Leo Razoumov" <slonik.az@gmail.com> writes:
> >
> >  > BTW, for those of us without dblatex, is it possible to have pdf
> >  > manual pregenerated the same way html and man pages are pregenerated
> >  > for official releases in the git repo?
> >
> >
> > Those of us includes myself, so...
> 
> Ouch:-) Does it mean that such a useful patch has a low probability of
> being accepted?

First, just like the info pages, I don't think it's a problem at all if
the autogenerated pdf version is not part of git.git. I sent the patch
to provide an easy way to do the pdf generation, not to request the
autobuild of it as well.

Second, I think the autogeneration for pdf should not be done similar to
the man/html versions, as the pdf itself is 421K.

However, I'm happy to set up a nightly cron job to build the pdf in case
master is updated and/or there is a new release - in case there is
demand for that.

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: [RFC/PATCH] Add support for a pdf version of the user manual

[Junio C Hamano]

"Leo Razoumov" <slonik.az@gmail.com> writes:

> On 12/10/08, Junio C Hamano <gitster@pobox.com> wrote:
>> "Leo Razoumov" <slonik.az@gmail.com> writes:
>>
>>  > BTW, for those of us without dblatex, is it possible to have pdf
>>  > manual pregenerated the same way html and man pages are pregenerated
>>  > for official releases in the git repo?
>>
>>
>> Those of us includes myself, so...
>
> Ouch:-) Does it mean that such a useful patch has a low probability of
> being accepted?

As an optional "make" target, as long as it works for people with the
necessary toolchain, I have no problem with the patch, but I would
complain if the usual "make doc" try to run the tool I do not want to run
with my regular build.  I didn't check.