Re: [PATCH] Documentation: Add target to build PDF manpages
Philip Oakley philipoak...@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 gits...@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. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Documentation: Add target to build PDF manpages
From: Michael J Gruber g...@drmicha.warpmail.net Junio C Hamano venit, vidit, dixit 20.03.2015 23:38: Stefan Beller sbel...@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 -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@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 venit, vidit, dixit 20.03.2015 23:38: Stefan Beller sbel...@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 -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Documentation: Add target to build PDF manpages
On Fri, Mar 20, 2015 at 4:23 AM, Thomas Schneider thosc...@gmail.com wrote: Signed-off-by: Thomas Schneider thosc...@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 majord...@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 majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Documentation: Add target to build PDF manpages
From: Stefan Beller sbel...@google.com On Fri, Mar 20, 2015 at 4:23 AM, Thomas Schneider thosc...@gmail.com wrote: Signed-off-by: Thomas Schneider thosc...@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 majord...@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 majord...@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 majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Documentation: Add target to build PDF manpages
Stefan Beller sbel...@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. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Documentation: Add target to build PDF manpages
Thomas Schneider thosc...@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. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Documentation: Add target to build PDF manpages
2015-03-20 22:28 GMT+01:00 Junio C Hamano gits...@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. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Documentation: Add target to build PDF manpages
2015-03-20 21:21 GMT+01:00 Junio C Hamano gits...@pobox.com: Stefan Beller sbel...@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. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Documentation: Add target to build PDF manpages
From: Junio C Hamano gits...@pobox.com Stefan Beller sbel...@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 -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Documentation: Add target to build PDF manpages
On Fri, Mar 20, 2015 at 1:21 PM, Junio C Hamano gits...@pobox.com wrote: Stefan Beller sbel...@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. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Documentation: Add target to build PDF manpages
Stefan Beller sbel...@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). -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Documentation: Add target to build PDF manpages
Stefan Beller sbel...@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. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
