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

From: Thomas Schneider <thosch97@gmail.com>
Date: Mar 20, 2015, 21:18 UTC
Message-ID: <CAJUTLVUK4+OiS_LDaFsRo_pwxF4nO2vR0zyumHBxBc9+8C3FUw@mail.gmail.com>
In-Reply-To: <xmqq4mpfe7xm.fsf@gitster.dls.corp.google.com>

2015-03-20 21:21 GMT+01:00 Junio C Hamano <gitster@pobox.com>:

Show 6 quoted lines

> 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.

Show 5 quoted lines

> 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.