[PATCH] Documentation: Add target to build PDF manpages

[PATCH] Documentation: Add target to build PDF manpages

[Thomas Schneider]

Signed-off-by: Thomas Schneider <thosch97@gmail.com>
---
dblatex does print some warnings, but they seem to be irrelevant.
Besides, first patch I submit to git or even to any project using a
mailing list … let’s hope I did everything right :)

 Documentation/Makefile | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 3e39e28..158cbd9 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -38,6 +38,7 @@ MAN7_TXT += gitworkflows.txt
 MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
 MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))
 MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))
+MAN_PDF = $(patsubst %.txt,%.pdf,$(MAN_TXT))
 
 OBSOLETE_HTML += everyday.html
 OBSOLETE_HTML += git-remote-helpers.html
@@ -223,7 +224,7 @@ man7: $(DOC_MAN7)
 
 info: git.info gitman.info
 
-pdf: user-manual.pdf
+pdf: user-manual.pdf $(MAN_PDF)
 
 install: install-man
 
@@ -248,6 +249,7 @@ install-info: info
 install-pdf: pdf
 	$(INSTALL) -d -m 755 $(DESTDIR)$(pdfdir)
 	$(INSTALL) -m 644 user-manual.pdf $(DESTDIR)$(pdfdir)
+	$(INSTALL) -m 644 $(MAN_PDF) $(DESTDIR)$(pdfdir)
 
 install-html: html
 	'$(SHELL_PATH_SQ)' ./install-webdoc.sh $(DESTDIR)$(htmldir)
@@ -328,6 +330,11 @@ manpage-base-url.xsl: manpage-base-url.xsl.in
 	$(QUIET_XMLTO)$(RM) $@ && \
 	$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
 
+%.pdf: %.xml
+	$(QUIET_DBLATEX)$(RM) $@+ $@ && \
+	$(DBLATEX) -o $@+ -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty $< && \
+	mv $@+ $@
+
 %.xml : %.txt asciidoc.conf
 	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
 	$(TXT_TO_XML) -d manpage -o $@+ $< && \
-- 
2.1.0

Re: [PATCH] Documentation: Add target to build PDF manpages

[Stefan Beller]

On Fri, Mar 20, 2015 at 4:23 AM, Thomas Schneider <thosch97@gmail.com> wrote:
> Signed-off-by: Thomas Schneider <thosch97@gmail.com>
> ---
> dblatex does print some warnings, but they seem to be irrelevant.
> Besides, first patch I submit to git or even to any project using a
> mailing list … let’s hope I did everything right :)

Welcome to the git community!

The patch itself applies cleanly and the generated pdfs look
really great, though how would I read man pages in pdf
format? I tried searching the web and all I can find is how
to convert the a man page to pdf. So is there a conveniant
way to tell `man` to prefer opening pdfs when available?

>
>  Documentation/Makefile | 9 ++++++++-
>  1 file changed, 8 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 3e39e28..158cbd9 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -38,6 +38,7 @@ MAN7_TXT += gitworkflows.txt
>  MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
>  MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))
>  MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))
> +MAN_PDF = $(patsubst %.txt,%.pdf,$(MAN_TXT))
>
>  OBSOLETE_HTML += everyday.html
>  OBSOLETE_HTML += git-remote-helpers.html
> @@ -223,7 +224,7 @@ man7: $(DOC_MAN7)
>
>  info: git.info gitman.info
>
> -pdf: user-manual.pdf
> +pdf: user-manual.pdf $(MAN_PDF)
>
>  install: install-man
>
> @@ -248,6 +249,7 @@ install-info: info
>  install-pdf: pdf
>         $(INSTALL) -d -m 755 $(DESTDIR)$(pdfdir)
>         $(INSTALL) -m 644 user-manual.pdf $(DESTDIR)$(pdfdir)
> +       $(INSTALL) -m 644 $(MAN_PDF) $(DESTDIR)$(pdfdir)
>
>  install-html: html
>         '$(SHELL_PATH_SQ)' ./install-webdoc.sh $(DESTDIR)$(htmldir)
> @@ -328,6 +330,11 @@ manpage-base-url.xsl: manpage-base-url.xsl.in
>         $(QUIET_XMLTO)$(RM) $@ && \
>         $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
>
> +%.pdf: %.xml
> +       $(QUIET_DBLATEX)$(RM) $@+ $@ && \
> +       $(DBLATEX) -o $@+ -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty $< && \
> +       mv $@+ $@
> +
>  %.xml : %.txt asciidoc.conf
>         $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
>         $(TXT_TO_XML) -d manpage -o $@+ $< && \
> --
> 2.1.0
>
> --
> 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

Re: [PATCH] Documentation: Add target to build PDF manpages

[Philip Oakley]

From: "Stefan Beller" <sbeller@google.com>
> On Fri, Mar 20, 2015 at 4:23 AM, Thomas Schneider <thosch97@gmail.com> 
> wrote:
>> Signed-off-by: Thomas Schneider <thosch97@gmail.com>
>> ---
>> dblatex does print some warnings, but they seem to be irrelevant.
>> Besides, first patch I submit to git or even to any project using a
>> mailing list … let’s hope I did everything right :)
>
> Welcome to the git community!
>
> The patch itself applies cleanly and the generated pdfs look
> really great, though how would I read man pages in pdf
> format? I tried searching the web and all I can find is how
> to convert the a man page to pdf. So is there a conveniant
> way to tell `man` to prefer opening pdfs when available?

My remembering of the help code (from when I added help's ability to 
list the guides), there isn't currently a mechanism to fire up a pdf 
reader of whatever hue. The MsysGit version encodes --web (html) as it's 
preferred reader.

So if anyone wants to have a go it shouldn't be that hard to add a --pdf 
option ;-)

>>
>>  Documentation/Makefile | 9 ++++++++-
>>  1 file changed, 8 insertions(+), 1 deletion(-)
>>
>> diff --git a/Documentation/Makefile b/Documentation/Makefile
>> index 3e39e28..158cbd9 100644
>> --- a/Documentation/Makefile
>> +++ b/Documentation/Makefile
>> @@ -38,6 +38,7 @@ MAN7_TXT += gitworkflows.txt
>>  MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
>>  MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))
>>  MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))
>> +MAN_PDF = $(patsubst %.txt,%.pdf,$(MAN_TXT))
>>
>>  OBSOLETE_HTML += everyday.html
>>  OBSOLETE_HTML += git-remote-helpers.html
>> @@ -223,7 +224,7 @@ man7: $(DOC_MAN7)
>>
>>  info: git.info gitman.info
>>
>> -pdf: user-manual.pdf
>> +pdf: user-manual.pdf $(MAN_PDF)
>>
>>  install: install-man
>>
>> @@ -248,6 +249,7 @@ install-info: info
>>  install-pdf: pdf
>>         $(INSTALL) -d -m 755 $(DESTDIR)$(pdfdir)
>>         $(INSTALL) -m 644 user-manual.pdf $(DESTDIR)$(pdfdir)
>> +       $(INSTALL) -m 644 $(MAN_PDF) $(DESTDIR)$(pdfdir)
>>
>>  install-html: html
>>         '$(SHELL_PATH_SQ)' ./install-webdoc.sh $(DESTDIR)$(htmldir)
>> @@ -328,6 +330,11 @@ manpage-base-url.xsl: manpage-base-url.xsl.in
>>         $(QUIET_XMLTO)$(RM) $@ && \
>>         $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
>>
>> +%.pdf: %.xml
>> +       $(QUIET_DBLATEX)$(RM) $@+ $@ && \
>> +       $(DBLATEX) -o $@+ -p 
>> $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s 
>> $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty $< && \
>> +       mv $@+ $@
>> +
>>  %.xml : %.txt asciidoc.conf
>>         $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
>>         $(TXT_TO_XML) -d manpage -o $@+ $< && \
>> --
>> 2.1.0
>>
>> --
>> 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
> --
> 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
> 

Re: [PATCH] Documentation: Add target to build PDF manpages

[Junio C Hamano]

Stefan Beller <sbeller@google.com> writes:

> ... though how would I read man pages in pdf
> format? I tried searching the web and all I can find is how
> to convert the a man page to pdf. So is there a conveniant
> way to tell `man` to prefer opening pdfs when available?

I presume that "man -Tpdf git.1" is not what you are looking for, as
that would literally be how you get the manpages in PDF format?

Personally, I honestly am not quite sure why anybody wants to
generate manpages in the PDF format like this patch does, unless
they are planning to print them on paper, in which case the existing
manpages (git.1 and friends) or html pages (git.html and friends)
should be an already available source format.

Re: [PATCH] Documentation: Add target to build PDF manpages

[Thomas Schneider]

2015-03-20 21:21 GMT+01:00 Junio C Hamano <gitster@pobox.com>:
> Stefan Beller <sbeller@google.com> writes:
>
>> ... though how would I read man pages in pdf
>> format? I tried searching the web and all I can find is how
>> to convert the a man page to pdf. So is there a conveniant
>> way to tell `man` to prefer opening pdfs when available?
Make man(1) open your PDF viewer?  As far as I know, you’d have to
either patch man or write a wrapper around it.

> Personally, I honestly am not quite sure why anybody wants to
> generate manpages in the PDF format like this patch does, unless
> they are planning to print them on paper, in which case the existing
> manpages (git.1 and friends) or html pages (git.html and friends)
> should be an already available source format.
Somebody in the #git IRC channel, called “IIT”, asked how to get PDF
manpages, so I found out respectively mostly already knew how to and
wrote this patch.
Their usecase was “read manpages offline on an iPad and make
annotations and highlights.”  I do not know iOS and the available
apps, so making annotations to documents might indeed be cumbersome
with HTML documents, not to mention troff.  I could also imagine
making an EPUB or mobipocket file from the AsciiDoc (which is quite
easy, both formats are more or less HTML), there are of course
dedicated eBook readers, which mostly support some sort of
annotations, and I’m sure there are decent apps for iOS as well.

So, maybe most people are fine with the other formats, but those who
need PDF can directly generate them.  And those who don’t will
probably not even notice.  Fedora does not seem to include any PDFs
(find /usr/share/doc/git* -iname "*pdf") and the Gentoo ebuild doesn’t
have any hints on PDF either, I suppose most other distros are
similar.

Re: [PATCH] Documentation: Add target to build PDF manpages

[Junio C Hamano]

Thomas Schneider <thosch97@gmail.com> writes:

>> Personally, I honestly am not quite sure why anybody wants to
>> generate manpages in the PDF format like this patch does, unless
>> they are planning to print them on paper, in which case the existing
>> manpages (git.1 and friends) or html pages (git.html and friends)
>> should be an already available source format.
> Somebody in the #git IRC channel...
> ... So, maybe most people are fine with the other formats, but those who
> need PDF can directly generate them.

I think you misunderstood me.  I am not dismissing the need for PDF;
I am just saying that there is no need to directly generate them
from asciidoc sources, especially when there are already manpages
and html pages available as source to "print" to PDF.

Re: [PATCH] Documentation: Add target to build PDF manpages

[Thomas Schneider]

2015-03-20 22:28 GMT+01:00 Junio C Hamano <gitster@pobox.com>:
> I think you misunderstood me.  I am not dismissing the need for PDF;
> I am just saying that there is no need to directly generate them
> from asciidoc sources, especially when there are already manpages
> and html pages available as source to "print" to PDF.

Oh, I might indeed have misunderstood you there.
Yes, you can indeed also generate nice-looking PDFs from HTML or
troff.  But if you need all of git’s manpages as PDF, a make target to
generate them surely comes in handy, so you don’t have to do it on
your own.  Also, if you are bulk-compiling all of the manpages, it
makes more sense to build them from the DocBook XML AsciiDoc generates
rather than from HTML or troff, simply because of one step less in the
toolchain and hence a way faster build.  It does not make a big
difference if you just compile one document, but for 169, it’s a
considerable difference.

Re: [PATCH] Documentation: Add target to build PDF manpages

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
> Stefan Beller <sbeller@google.com> writes:
>
>> ... though how would I read man pages in pdf
>> format? I tried searching the web and all I can find is how
>> to convert the a man page to pdf. So is there a conveniant
>> way to tell `man` to prefer opening pdfs when available?
>
> I presume that "man -Tpdf git.1" is not what you are looking for, as
> that would literally be how you get the manpages in PDF format?
>
I'd expect 'git help --pdf git' to simply feed the path of git.pdf 
(probably in the same directory as the .html versions) to the web 
browser and let it determine the users prefered reader.

> Personally, I honestly am not quite sure why anybody wants to
> generate manpages in the PDF format like this patch does, unless
> they are planning to print them on paper, in which case the existing
> manpages (git.1 and friends) or html pages (git.html and friends)
> should be an already available source format.
> --
Despite the scare stories and problems that pdf format can bring it is 
quite popular as a way of 'freezing' what is displayed (I use it a lot 
to capture web confirmations;-), so I don't see it as being too 
outlandish, though I wouldn't expect the project to automatically 
generate the pdfs in the same way the man and web pages are.

--
Philip 

Re: [PATCH] Documentation: Add target to build PDF manpages

[Stefan Beller]

On Fri, Mar 20, 2015 at 1:21 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Stefan Beller <sbeller@google.com> writes:
>
>> ... though how would I read man pages in pdf
>> format? I tried searching the web and all I can find is how
>> to convert the a man page to pdf. So is there a conveniant
>> way to tell `man` to prefer opening pdfs when available?
>
> I presume that "man -Tpdf git.1" is not what you are looking for, as
> that would literally be how you get the manpages in PDF format?

Not quite as that is producing a pdf. So I could do

    man -Tpdf git add >tmpfile && evince tmpfile && rm tmpfile

but that is inconvenient to type, so I'd rather be looking for

   man_or_pdf_when_possible git add

and I could alias man_or_pdf_when_possible to a short name.

>
> Personally, I honestly am not quite sure why anybody wants to
> generate manpages in the PDF format like this patch does, unless
> they are planning to print them on paper, in which case the existing
> manpages (git.1 and friends) or html pages (git.html and friends)
> should be an already available source format.

This is what I was wondering about as well and my conclusion was
it is nicer than the output of man itself to look at, so there must be an
obvious command to read pdf instead of man.

Thomas referencing reading the man page offline, made me wonder
why you wouldn't read the man pages itself as they can also be
carried around offline. But the striking point is "on an iPad", which
doesn't offer you the convenience of a shell etc, but pdf is fine to read
there. Also you can add comments to pdfs more easily that html pages
I'd guess.

So the patch makes sense to me now. It's just a use case I'm personally
not interested in for now, but I don't oppose it as is.

Re: [PATCH] Documentation: Add target to build PDF manpages

[Junio C Hamano]

Stefan Beller <sbeller@google.com> writes:

> Thomas referencing reading the man page offline, made me wonder
> why you wouldn't read the man pages itself as they can also be
> carried around offline. But the striking point is "on an iPad", which
> doesn't offer you the convenience of a shell etc, but pdf is fine to read
> there. Also you can add comments to pdfs more easily that html pages
> I'd guess.
>
> So the patch makes sense to me now. It's just a use case I'm personally
> not interested in for now, but I don't oppose it as is.

Well, my comment was not about opposing to it, but was about
questioning the usefulness of it, iow, who would
benefit from having this patch in my tree?

I didn't see (and I still do not quite see) why people would want to
have separate pdf files for all the subcommands (instead of say an
.epub or .pdf that binds all the man pages and perhaps user-manual,
just like we do for .texi/.info).

Re: [PATCH] Documentation: Add target to build PDF manpages

[Michael J Gruber]

Junio C Hamano venit, vidit, dixit 20.03.2015 23:38:
> Stefan Beller <sbeller@google.com> writes:
> 
>> Thomas referencing reading the man page offline, made me wonder
>> why you wouldn't read the man pages itself as they can also be
>> carried around offline. But the striking point is "on an iPad", which
>> doesn't offer you the convenience of a shell etc, but pdf is fine to read
>> there. Also you can add comments to pdfs more easily that html pages
>> I'd guess.
>>
>> So the patch makes sense to me now. It's just a use case I'm personally
>> not interested in for now, but I don't oppose it as is.
> 
> Well, my comment was not about opposing to it, but was about
> questioning the usefulness of it, iow, who would
> benefit from having this patch in my tree?
> 
> I didn't see (and I still do not quite see) why people would want to
> have separate pdf files for all the subcommands (instead of say an
> .epub or .pdf that binds all the man pages and perhaps user-manual,
> just like we do for .texi/.info).

Exactly. For PDF, a combined document is more natural and will hopefully
make crosslinks work as crossrefs within one document, rather than links
to external documents. I'd say that would make a valuable target.

Michael

Re: [PATCH] Documentation: Add target to build PDF manpages

[Philip Oakley]

From: "Michael J Gruber" <git@drmicha.warpmail.net>
> Junio C Hamano venit, vidit, dixit 20.03.2015 23:38:
>> Stefan Beller <sbeller@google.com> writes:
>>
>>> Thomas referencing reading the man page offline, made me wonder
>>> why you wouldn't read the man pages itself as they can also be
>>> carried around offline. But the striking point is "on an iPad", 
>>> which
>>> doesn't offer you the convenience of a shell etc, but pdf is fine to 
>>> read
>>> there. Also you can add comments to pdfs more easily that html pages
>>> I'd guess.
>>>
>>> So the patch makes sense to me now. It's just a use case I'm 
>>> personally
>>> not interested in for now, but I don't oppose it as is.
>>
>> Well, my comment was not about opposing to it, but was about
>> questioning the usefulness of it, iow, who would
>> benefit from having this patch in my tree?
>>
>> I didn't see (and I still do not quite see) why people would want to
>> have separate pdf files for all the subcommands (instead of say an
>> .epub or .pdf that binds all the man pages and perhaps user-manual,
>> just like we do for .texi/.info).
>
> Exactly. For PDF, a combined document is more natural and will 
> hopefully
> make crosslinks work as crossrefs within one document, rather than 
> links
> to external documents. I'd say that would make a valuable target.

As per the original request, it is useful to some, and the usefulness of 
a very large pdf containing all the documentation shouldn't be a reason 
to not have such a 'one at a time' target available (though personally I 
would suggest that it is the users responsibility to 'make' such a 
target, not the maintainers!).

The single large pdf has also been discussed 
(http://thread.gmane.org/gmane.comp.version-control.git/207151/focus=207165) 
but didn't get into the code base either.

The user-manual is available as a pdf target.

Philip 

Re: [PATCH] Documentation: Add target to build PDF manpages

[Thomas Schneider]

Philip Oakley <philipoakley@iee.org> wrote:
> I'd expect 'git help --pdf git' to simply feed the path of git.pdf
> (probably in the same directory as the .html versions) to the web
> browser and let it determine the users prefered reader.
Yes, this is what I would do as well.  Unfortunately I don’t really
know C, so I can’t implement this.  But for someone who is familiar
with C, it should be easy---just call `xdg-open` (X11), `open` (OS X)
or `start` (Windows) and thus the user’s preferred PDF reader, and
maybe some common programs (evince, okular, …) as fallback.

Junio C Hamano <gitster@pobox.com> wrote:
> I didn't see (and I still do not quite see) why people would want to
> have separate pdf files for all the subcommands (instead of say an
> .epub or .pdf that binds all the man pages and perhaps user-manual,
> just like we do for .texi/.info).
Because it’s a good start :-)
I see your point, and I agree that a combined PDF/EPUB/etc would make
more sense.  This should be not too difficult with the
AsciiDoc-DocBook-Toolchain (or maybe even without DocBook), I just
need to dig into it a bit further.

Re: [PATCH] Documentation: Add target to build PDF manpages

[Junio C Hamano]

Stefan Beller <sbeller@google.com> writes:

> ... I'd rather be looking for
>
>    man_or_pdf_when_possible git add
>
> and I could alias man_or_pdf_when_possible to a short name.

The help framework can choose the backend and the format and it
wouldn't be too outlandish to do "git help --pdf add" as Philip
mentioned already.

In any case, this, together with some patches on unrelated topics
that didn't cut today's "What's cooking" are parked on 'pu', so
hopefully people will play with it and report how they find it
useful.

Thanks, all.