{"thread":{"id":"38865","subject":"[PATCH] Documentation: Add target to build PDF manpages","startedAt":"2015-03-20T11:23:04Z","lastAt":"2015-03-25T11:43:57Z","messageCount":14,"participants":["Thomas Schneider","Stefan Beller","Philip Oakley","Junio C Hamano","Michael J Gruber"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"258125","messageId":"1426850584-9951-1-git-send-email-thosch97@gmail.com","threadId":"38865","inReplyTo":null,"subject":"[PATCH] Documentation: Add target to build PDF manpages","fromName":"Thomas Schneider","fromEmail":"thosch97@gmail.com","sentAt":"2015-03-20T11:23:04Z","receivedAt":"2015-03-20T11:23:04Z","isPatch":true,"sender":{"key":"thosch97@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1690172?v=4"},"body":"Signed-off-by: Thomas Schneider \n---\ndblatex does print some warnings, but they seem to be irrelevant.\nBesides, first patch I submit to git or even to any project using a\nmailing list … let’s hope I did everything right :)\n\n Documentation/Makefile | 9 ++++++++-\n 1 file changed, 8 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 3e39e28..158cbd9 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -38,6 +38,7 @@ MAN7_TXT += gitworkflows.txt\n MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)\n MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))\n MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))\n+MAN_PDF = $(patsubst %.txt,%.pdf,$(MAN_TXT))\n \n OBSOLETE_HTML += everyday.html\n OBSOLETE_HTML += git-remote-helpers.html\n@@ -223,7 +224,7 @@ man7: $(DOC_MAN7)\n \n info: git.info gitman.info\n \n-pdf: user-manual.pdf\n+pdf: user-manual.pdf $(MAN_PDF)\n \n install: install-man\n \n@@ -248,6 +249,7 @@ install-info: info\n install-pdf: pdf\n \t$(INSTALL) -d -m 755 $(DESTDIR)$(pdfdir)\n \t$(INSTALL) -m 644 user-manual.pdf $(DESTDIR)$(pdfdir)\n+\t$(INSTALL) -m 644 $(MAN_PDF) $(DESTDIR)$(pdfdir)\n \n install-html: html\n \t'$(SHELL_PATH_SQ)' ./install-webdoc.sh $(DESTDIR)$(htmldir)\n@@ -328,6 +330,11 @@ manpage-base-url.xsl: manpage-base-url.xsl.in\n \t$(QUIET_XMLTO)$(RM) $@ && \\\n \t$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n \n+%.pdf: %.xml\n+\t$(QUIET_DBLATEX)$(RM) $@+ $@ && \\\n+\t$(DBLATEX) -o $@+ -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty $< && \\\n+\tmv $@+ $@\n+\n %.xml : %.txt asciidoc.conf\n \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n \t$(TXT_TO_XML) -d manpage -o $@+ $< && \\\n-- \n2.1.0\n"},{"id":"258135","messageId":"CAGZ79ka7tPA17Y-vPPp5W_4-0UMnHMfM9+eQ8jc4eu23FpM2ug@mail.gmail.com","threadId":"38865","inReplyTo":"1426850584-9951-1-git-send-email-thosch97@gmail.com","subject":"Re: [PATCH] Documentation: Add target to build PDF manpages","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2015-03-20T17:19:36Z","receivedAt":"2015-03-20T17:19:36Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Fri, Mar 20, 2015 at 4:23 AM, Thomas Schneider wrote:\n> Signed-off-by: Thomas Schneider \n> ---\n> dblatex does print some warnings, but they seem to be irrelevant.\n> Besides, first patch I submit to git or even to any project using a\n> mailing list … let’s hope I did everything right :)\n\nWelcome to the git community!\n\nThe patch itself applies cleanly and the generated pdfs look\nreally great, though how would I read man pages in pdf\nformat? I tried searching the web and all I can find is how\nto convert the a man page to pdf. So is there a conveniant\nway to tell `man` to prefer opening pdfs when available?\n\n>\n> Documentation/Makefile | 9 ++++++++-\n> 1 file changed, 8 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/Makefile b/Documentation/Makefile\n> index 3e39e28..158cbd9 100644\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -38,6 +38,7 @@ MAN7_TXT += gitworkflows.txt\n> MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)\n> MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))\n> MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))\n> +MAN_PDF = $(patsubst %.txt,%.pdf,$(MAN_TXT))\n>\n> OBSOLETE_HTML += everyday.html\n> OBSOLETE_HTML += git-remote-helpers.html\n> @@ -223,7 +224,7 @@ man7: $(DOC_MAN7)\n>\n> info: git.info gitman.info\n>\n> -pdf: user-manual.pdf\n> +pdf: user-manual.pdf $(MAN_PDF)\n>\n> install: install-man\n>\n> @@ -248,6 +249,7 @@ install-info: info\n> install-pdf: pdf\n> $(INSTALL) -d -m 755 $(DESTDIR)$(pdfdir)\n> $(INSTALL) -m 644 user-manual.pdf $(DESTDIR)$(pdfdir)\n> + $(INSTALL) -m 644 $(MAN_PDF) $(DESTDIR)$(pdfdir)\n>\n> install-html: html\n> '$(SHELL_PATH_SQ)' ./install-webdoc.sh $(DESTDIR)$(htmldir)\n> @@ -328,6 +330,11 @@ manpage-base-url.xsl: manpage-base-url.xsl.in\n> $(QUIET_XMLTO)$(RM) $@ && \\\n> $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n>\n> +%.pdf: %.xml\n> + $(QUIET_DBLATEX)$(RM) $@+ $@ && \\\n> + $(DBLATEX) -o $@+ -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty $< && \\\n> + mv $@+ $@\n> +\n> %.xml : %.txt asciidoc.conf\n> $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n> $(TXT_TO_XML) -d manpage -o $@+ $< && \\\n> --\n> 2.1.0\n>\n> --\n> To unsubscribe from this list: send the line \"unsubscribe git\" in\n> the body of a message to majordomo@vger.kernel.org\n> More majordomo info at http://vger.kernel.org/majordomo-info.html\n"},{"id":"258177","messageId":"E4A75513C64F43B5A03A05B043426F55@PhilipOakley","threadId":"38865","inReplyTo":"CAGZ79ka7tPA17Y-vPPp5W_4-0UMnHMfM9+eQ8jc4eu23FpM2ug@mail.gmail.com","subject":"Re: [PATCH] Documentation: Add target to build PDF manpages","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":null,"receivedAt":"2015-03-20T19:28:22Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Stefan Beller\" \n> On Fri, Mar 20, 2015 at 4:23 AM, Thomas Schneider \n> wrote:\n>> Signed-off-by: Thomas Schneider \n>> ---\n>> dblatex does print some warnings, but they seem to be irrelevant.\n>> Besides, first patch I submit to git or even to any project using a\n>> mailing list … let’s hope I did everything right :)\n>\n> Welcome to the git community!\n>\n> The patch itself applies cleanly and the generated pdfs look\n> really great, though how would I read man pages in pdf\n> format? I tried searching the web and all I can find is how\n> to convert the a man page to pdf. So is there a conveniant\n> way to tell `man` to prefer opening pdfs when available?\n\nMy remembering of the help code (from when I added help's ability to \nlist the guides), there isn't currently a mechanism to fire up a pdf \nreader of whatever hue. The MsysGit version encodes --web (html) as it's \npreferred reader.\n\nSo if anyone wants to have a go it shouldn't be that hard to add a --pdf \noption ;-)\n\n>>\n>> Documentation/Makefile | 9 ++++++++-\n>> 1 file changed, 8 insertions(+), 1 deletion(-)\n>>\n>> diff --git a/Documentation/Makefile b/Documentation/Makefile\n>> index 3e39e28..158cbd9 100644\n>> --- a/Documentation/Makefile\n>> +++ b/Documentation/Makefile\n>> @@ -38,6 +38,7 @@ MAN7_TXT += gitworkflows.txt\n>> MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)\n>> MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))\n>> MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))\n>> +MAN_PDF = $(patsubst %.txt,%.pdf,$(MAN_TXT))\n>>\n>> OBSOLETE_HTML += everyday.html\n>> OBSOLETE_HTML += git-remote-helpers.html\n>> @@ -223,7 +224,7 @@ man7: $(DOC_MAN7)\n>>\n>> info: git.info gitman.info\n>>\n>> -pdf: user-manual.pdf\n>> +pdf: user-manual.pdf $(MAN_PDF)\n>>\n>> install: install-man\n>>\n>> @@ -248,6 +249,7 @@ install-info: info\n>> install-pdf: pdf\n>> $(INSTALL) -d -m 755 $(DESTDIR)$(pdfdir)\n>> $(INSTALL) -m 644 user-manual.pdf $(DESTDIR)$(pdfdir)\n>> + $(INSTALL) -m 644 $(MAN_PDF) $(DESTDIR)$(pdfdir)\n>>\n>> install-html: html\n>> '$(SHELL_PATH_SQ)' ./install-webdoc.sh $(DESTDIR)$(htmldir)\n>> @@ -328,6 +330,11 @@ manpage-base-url.xsl: manpage-base-url.xsl.in\n>> $(QUIET_XMLTO)$(RM) $@ && \\\n>> $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n>>\n>> +%.pdf: %.xml\n>> + $(QUIET_DBLATEX)$(RM) $@+ $@ && \\\n>> + $(DBLATEX) -o $@+ -p \n>> $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s \n>> $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty $< && \\\n>> + mv $@+ $@\n>> +\n>> %.xml : %.txt asciidoc.conf\n>> $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n>> $(TXT_TO_XML) -d manpage -o $@+ $< && \\\n>> --\n>> 2.1.0\n>>\n>> --\n>> To unsubscribe from this list: send the line \"unsubscribe git\" in\n>> the body of a message to majordomo@vger.kernel.org\n>> More majordomo info at http://vger.kernel.org/majordomo-info.html\n> --\n> To unsubscribe from this list: send the line \"unsubscribe git\" in\n> the body of a message to majordomo@vger.kernel.org\n> More majordomo info at http://vger.kernel.org/majordomo-info.html\n> \n"},{"id":"258185","messageId":"xmqq4mpfe7xm.fsf@gitster.dls.corp.google.com","threadId":"38865","inReplyTo":"CAGZ79ka7tPA17Y-vPPp5W_4-0UMnHMfM9+eQ8jc4eu23FpM2ug@mail.gmail.com","subject":"Re: [PATCH] Documentation: Add target to build PDF manpages","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-03-20T20:21:41Z","receivedAt":"2015-03-20T20:21:41Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stefan Beller writes:\n\n> ... though how would I read man pages in pdf\n> format? I tried searching the web and all I can find is how\n> to convert the a man page to pdf. So is there a conveniant\n> way to tell `man` to prefer opening pdfs when available?\n\nI presume that \"man -Tpdf git.1\" is not what you are looking for, as\nthat would literally be how you get the manpages in PDF format?\n\nPersonally, I honestly am not quite sure why anybody wants to\ngenerate manpages in the PDF format like this patch does, unless\nthey are planning to print them on paper, in which case the existing\nmanpages (git.1 and friends) or html pages (git.html and friends)\nshould be an already available source format.\n"},{"id":"258187","messageId":"CAJUTLVUK4+OiS_LDaFsRo_pwxF4nO2vR0zyumHBxBc9+8C3FUw@mail.gmail.com","threadId":"38865","inReplyTo":"xmqq4mpfe7xm.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] Documentation: Add target to build PDF manpages","fromName":"Thomas Schneider","fromEmail":"thosch97@gmail.com","sentAt":"2015-03-20T21:18:25Z","receivedAt":"2015-03-20T21:18:25Z","isPatch":true,"sender":{"key":"thosch97@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1690172?v=4"},"body":"2015-03-20 21:21 GMT+01:00 Junio C Hamano :\n> Stefan Beller writes:\n>\n>> ... though how would I read man pages in pdf\n>> format? I tried searching the web and all I can find is how\n>> to convert the a man page to pdf. So is there a conveniant\n>> way to tell `man` to prefer opening pdfs when available?\nMake man(1) open your PDF viewer? As far as I know, you’d have to\neither patch man or write a wrapper around it.\n\n> Personally, I honestly am not quite sure why anybody wants to\n> generate manpages in the PDF format like this patch does, unless\n> they are planning to print them on paper, in which case the existing\n> manpages (git.1 and friends) or html pages (git.html and friends)\n> should be an already available source format.\nSomebody in the #git IRC channel, called “IIT”, asked how to get PDF\nmanpages, so I found out respectively mostly already knew how to and\nwrote this patch.\nTheir usecase was “read manpages offline on an iPad and make\nannotations and highlights.” I do not know iOS and the available\napps, so making annotations to documents might indeed be cumbersome\nwith HTML documents, not to mention troff. I could also imagine\nmaking an EPUB or mobipocket file from the AsciiDoc (which is quite\neasy, both formats are more or less HTML), there are of course\ndedicated eBook readers, which mostly support some sort of\nannotations, and I’m sure there are decent apps for iOS as well.\n\nSo, maybe most people are fine with the other formats, but those who\nneed PDF can directly generate them. And those who don’t will\nprobably not even notice. Fedora does not seem to include any PDFs\n(find /usr/share/doc/git* -iname \"*pdf\") and the Gentoo ebuild doesn’t\nhave any hints on PDF either, I suppose most other distros are\nsimilar.\n"},{"id":"258188","messageId":"xmqqzj77cq9p.fsf@gitster.dls.corp.google.com","threadId":"38865","inReplyTo":"CAJUTLVUK4+OiS_LDaFsRo_pwxF4nO2vR0zyumHBxBc9+8C3FUw@mail.gmail.com","subject":"Re: [PATCH] Documentation: Add target to build PDF manpages","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-03-20T21:28:34Z","receivedAt":"2015-03-20T21:28:34Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Thomas Schneider writes:\n\n>> Personally, I honestly am not quite sure why anybody wants to\n>> generate manpages in the PDF format like this patch does, unless\n>> they are planning to print them on paper, in which case the existing\n>> manpages (git.1 and friends) or html pages (git.html and friends)\n>> should be an already available source format.\n> Somebody in the #git IRC channel...\n> ... So, maybe most people are fine with the other formats, but those who\n> need PDF can directly generate them.\n\nI think you misunderstood me. I am not dismissing the need for PDF;\nI am just saying that there is no need to directly generate them\nfrom asciidoc sources, especially when there are already manpages\nand html pages available as source to \"print\" to PDF.\n"},{"id":"258193","messageId":"CAJUTLVXwR+-PBRHZSENryGxkAB--w+oskUDyHhj1Oz37aNcOMg@mail.gmail.com","threadId":"38865","inReplyTo":"xmqqzj77cq9p.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] Documentation: Add target to build PDF manpages","fromName":"Thomas Schneider","fromEmail":"thosch97@gmail.com","sentAt":"2015-03-20T21:54:56Z","receivedAt":"2015-03-20T21:54:56Z","isPatch":true,"sender":{"key":"thosch97@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1690172?v=4"},"body":"2015-03-20 22:28 GMT+01:00 Junio C Hamano :\n> I think you misunderstood me. I am not dismissing the need for PDF;\n> I am just saying that there is no need to directly generate them\n> from asciidoc sources, especially when there are already manpages\n> and html pages available as source to \"print\" to PDF.\n\nOh, I might indeed have misunderstood you there.\nYes, you can indeed also generate nice-looking PDFs from HTML or\ntroff. But if you need all of git’s manpages as PDF, a make target to\ngenerate them surely comes in handy, so you don’t have to do it on\nyour own. Also, if you are bulk-compiling all of the manpages, it\nmakes more sense to build them from the DocBook XML AsciiDoc generates\nrather than from HTML or troff, simply because of one step less in the\ntoolchain and hence a way faster build. It does not make a big\ndifference if you just compile one document, but for 169, it’s a\nconsiderable difference.\n"},{"id":"258196","messageId":"3037A3ADECA54FB2B56348E4F6F04A95@PhilipOakley","threadId":"38865","inReplyTo":"xmqq4mpfe7xm.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] Documentation: Add target to build PDF manpages","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":null,"receivedAt":"2015-03-20T22:12:39Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> Stefan Beller writes:\n>\n>> ... though how would I read man pages in pdf\n>> format? I tried searching the web and all I can find is how\n>> to convert the a man page to pdf. So is there a conveniant\n>> way to tell `man` to prefer opening pdfs when available?\n>\n> I presume that \"man -Tpdf git.1\" is not what you are looking for, as\n> that would literally be how you get the manpages in PDF format?\n>\nI'd expect 'git help --pdf git' to simply feed the path of git.pdf \n(probably in the same directory as the .html versions) to the web \nbrowser and let it determine the users prefered reader.\n\n> Personally, I honestly am not quite sure why anybody wants to\n> generate manpages in the PDF format like this patch does, unless\n> they are planning to print them on paper, in which case the existing\n> manpages (git.1 and friends) or html pages (git.html and friends)\n> should be an already available source format.\n> --\nDespite the scare stories and problems that pdf format can bring it is \nquite popular as a way of 'freezing' what is displayed (I use it a lot \nto capture web confirmations;-), so I don't see it as being too \noutlandish, though I wouldn't expect the project to automatically \ngenerate the pdfs in the same way the man and web pages are.\n\n--\nPhilip \n"},{"id":"258197","messageId":"CAGZ79kaDnRiUQ6=3gVvsPrkSzkNbACRvgQBSo8gmpRZ8bka84g@mail.gmail.com","threadId":"38865","inReplyTo":"xmqq4mpfe7xm.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] Documentation: Add target to build PDF manpages","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2015-03-20T22:19:04Z","receivedAt":"2015-03-20T22:19:04Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Fri, Mar 20, 2015 at 1:21 PM, Junio C Hamano wrote:\n> Stefan Beller writes:\n>\n>> ... though how would I read man pages in pdf\n>> format? I tried searching the web and all I can find is how\n>> to convert the a man page to pdf. So is there a conveniant\n>> way to tell `man` to prefer opening pdfs when available?\n>\n> I presume that \"man -Tpdf git.1\" is not what you are looking for, as\n> that would literally be how you get the manpages in PDF format?\n\nNot quite as that is producing a pdf. So I could do\n\n man -Tpdf git add >tmpfile && evince tmpfile && rm tmpfile\n\nbut that is inconvenient to type, so I'd rather be looking for\n\n man_or_pdf_when_possible git add\n\nand I could alias man_or_pdf_when_possible to a short name.\n\n>\n> Personally, I honestly am not quite sure why anybody wants to\n> generate manpages in the PDF format like this patch does, unless\n> they are planning to print them on paper, in which case the existing\n> manpages (git.1 and friends) or html pages (git.html and friends)\n> should be an already available source format.\n\nThis is what I was wondering about as well and my conclusion was\nit is nicer than the output of man itself to look at, so there must be an\nobvious command to read pdf instead of man.\n\nThomas referencing reading the man page offline, made me wonder\nwhy you wouldn't read the man pages itself as they can also be\ncarried around offline. But the striking point is \"on an iPad\", which\ndoesn't offer you the convenience of a shell etc, but pdf is fine to read\nthere. Also you can add comments to pdfs more easily that html pages\nI'd guess.\n\nSo the patch makes sense to me now. It's just a use case I'm personally\nnot interested in for now, but I don't oppose it as is.\n"},{"id":"258198","messageId":"xmqqmw37cn18.fsf@gitster.dls.corp.google.com","threadId":"38865","inReplyTo":"CAGZ79kaDnRiUQ6=3gVvsPrkSzkNbACRvgQBSo8gmpRZ8bka84g@mail.gmail.com","subject":"Re: [PATCH] Documentation: Add target to build PDF manpages","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-03-20T22:38:27Z","receivedAt":"2015-03-20T22:38:27Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stefan Beller writes:\n\n> Thomas referencing reading the man page offline, made me wonder\n> why you wouldn't read the man pages itself as they can also be\n> carried around offline. But the striking point is \"on an iPad\", which\n> doesn't offer you the convenience of a shell etc, but pdf is fine to read\n> there. Also you can add comments to pdfs more easily that html pages\n> I'd guess.\n>\n> So the patch makes sense to me now. It's just a use case I'm personally\n> not interested in for now, but I don't oppose it as is.\n\nWell, my comment was not about opposing to it, but was about\nquestioning the usefulness of it, iow, who would\nbenefit from having this patch in my tree?\n\nI didn't see (and I still do not quite see) why people would want to\nhave separate pdf files for all the subcommands (instead of say an\n.epub or .pdf that binds all the man pages and perhaps user-manual,\njust like we do for .texi/.info).\n"},{"id":"258199","messageId":"xmqqiodvcmuc.fsf@gitster.dls.corp.google.com","threadId":"38865","inReplyTo":"CAGZ79kaDnRiUQ6=3gVvsPrkSzkNbACRvgQBSo8gmpRZ8bka84g@mail.gmail.com","subject":"Re: [PATCH] Documentation: Add target to build PDF manpages","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-03-20T22:42:35Z","receivedAt":"2015-03-20T22:42:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stefan Beller writes:\n\n> ... I'd rather be looking for\n>\n> man_or_pdf_when_possible git add\n>\n> and I could alias man_or_pdf_when_possible to a short name.\n\nThe help framework can choose the backend and the format and it\nwouldn't be too outlandish to do \"git help --pdf add\" as Philip\nmentioned already.\n\nIn any case, this, together with some patches on unrelated topics\nthat didn't cut today's \"What's cooking\" are parked on 'pu', so\nhopefully people will play with it and report how they find it\nuseful.\n\nThanks, all.\n"},{"id":"258366","messageId":"55103565.9040000@drmicha.warpmail.net","threadId":"38865","inReplyTo":"xmqqmw37cn18.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] Documentation: Add target to build PDF manpages","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2015-03-23T15:46:45Z","receivedAt":"2015-03-23T15:46:45Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Junio C Hamano venit, vidit, dixit 20.03.2015 23:38:\n> Stefan Beller writes:\n> \n>> Thomas referencing reading the man page offline, made me wonder\n>> why you wouldn't read the man pages itself as they can also be\n>> carried around offline. But the striking point is \"on an iPad\", which\n>> doesn't offer you the convenience of a shell etc, but pdf is fine to read\n>> there. Also you can add comments to pdfs more easily that html pages\n>> I'd guess.\n>>\n>> So the patch makes sense to me now. It's just a use case I'm personally\n>> not interested in for now, but I don't oppose it as is.\n> \n> Well, my comment was not about opposing to it, but was about\n> questioning the usefulness of it, iow, who would\n> benefit from having this patch in my tree?\n> \n> I didn't see (and I still do not quite see) why people would want to\n> have separate pdf files for all the subcommands (instead of say an\n> .epub or .pdf that binds all the man pages and perhaps user-manual,\n> just like we do for .texi/.info).\n\nExactly. For PDF, a combined document is more natural and will hopefully\nmake crosslinks work as crossrefs within one document, rather than links\nto external documents. I'd say that would make a valuable target.\n\nMichael\n"},{"id":"258459","messageId":"DA8ADE6265034B1186A4D63318C6EF3C@PhilipOakley","threadId":"38865","inReplyTo":"55103565.9040000@drmicha.warpmail.net","subject":"Re: [PATCH] Documentation: Add target to build PDF manpages","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":null,"receivedAt":"2015-03-24T23:06:05Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Michael J Gruber\" \n> Junio C Hamano venit, vidit, dixit 20.03.2015 23:38:\n>> Stefan Beller writes:\n>>\n>>> Thomas referencing reading the man page offline, made me wonder\n>>> why you wouldn't read the man pages itself as they can also be\n>>> carried around offline. But the striking point is \"on an iPad\", \n>>> which\n>>> doesn't offer you the convenience of a shell etc, but pdf is fine to \n>>> read\n>>> there. Also you can add comments to pdfs more easily that html pages\n>>> I'd guess.\n>>>\n>>> So the patch makes sense to me now. It's just a use case I'm \n>>> personally\n>>> not interested in for now, but I don't oppose it as is.\n>>\n>> Well, my comment was not about opposing to it, but was about\n>> questioning the usefulness of it, iow, who would\n>> benefit from having this patch in my tree?\n>>\n>> I didn't see (and I still do not quite see) why people would want to\n>> have separate pdf files for all the subcommands (instead of say an\n>> .epub or .pdf that binds all the man pages and perhaps user-manual,\n>> just like we do for .texi/.info).\n>\n> Exactly. For PDF, a combined document is more natural and will \n> hopefully\n> make crosslinks work as crossrefs within one document, rather than \n> links\n> to external documents. I'd say that would make a valuable target.\n\nAs per the original request, it is useful to some, and the usefulness of \na very large pdf containing all the documentation shouldn't be a reason \nto not have such a 'one at a time' target available (though personally I \nwould suggest that it is the users responsibility to 'make' such a \ntarget, not the maintainers!).\n\nThe single large pdf has also been discussed \n(http://thread.gmane.org/gmane.comp.version-control.git/207151/focus=207165) \nbut didn't get into the code base either.\n\nThe user-manual is available as a pdf target.\n\nPhilip \n"},{"id":"258500","messageId":"CAJUTLVXC7b4svJ0N4sQGm3+eRpjcQ_8eSv0vSYff=K_x_7mO3A@mail.gmail.com","threadId":"38865","inReplyTo":"DA8ADE6265034B1186A4D63318C6EF3C@PhilipOakley","subject":"Re: [PATCH] Documentation: Add target to build PDF manpages","fromName":"Thomas Schneider","fromEmail":"thosch97@gmail.com","sentAt":"2015-03-25T11:43:57Z","receivedAt":"2015-03-25T11:43:57Z","isPatch":true,"sender":{"key":"thosch97@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1690172?v=4"},"body":"Philip Oakley wrote:\n> I'd expect 'git help --pdf git' to simply feed the path of git.pdf\n> (probably in the same directory as the .html versions) to the web\n> browser and let it determine the users prefered reader.\nYes, this is what I would do as well. Unfortunately I don’t really\nknow C, so I can’t implement this. But for someone who is familiar\nwith C, it should be easy---just call `xdg-open` (X11), `open` (OS X)\nor `start` (Windows) and thus the user’s preferred PDF reader, and\nmaybe some common programs (evince, okular, …) as fallback.\n\nJunio C Hamano wrote:\n> I didn't see (and I still do not quite see) why people would want to\n> have separate pdf files for all the subcommands (instead of say an\n> .epub or .pdf that binds all the man pages and perhaps user-manual,\n> just like we do for .texi/.info).\nBecause it’s a good start :-)\nI see your point, and I agree that a combined PDF/EPUB/etc would make\nmore sense. This should be not too difficult with the\nAsciiDoc-DocBook-Toolchain (or maybe even without DocBook), I just\nneed to dig into it a bit further.\n"}]}