Support direct pdf generation with asciidoc

For code related discussions and questions

Support direct pdf generation with asciidoc

Postby nick87720z » 23 Feb 2018, 12:51

For now a2x is used only to create html, while to create pdf - this html is processed by wkhtmltopdf.

I have live ebuild for warzone2100 under gentoo, in local overlay.
Last time i faced problem with wkhtmltopdf - since it requires X environment. Appart that it also needs home directory with write permission.
Without that i get this error:
Code: Select all
wkhtmltopdf ./quickstartguide.html ./quickstartguide.pdf
QStandardPaths: wrong ownership on runtime directory /var/run/user/0, 0 instead of 250


Since it happens just when wkhtmltopdf is installed, temporary solution would be to uninstall it (i installed it to see, how it will work during wz2100 installation).

It would be not problem, if building with root access, however portage has FEATURES to do as much job as possible (sources fetch, build, etc) under special "portage" user. Problem, is that this user doesn't have own home directory, instead using root's home, where it can't write. Though this particular issue doesn't look unsolvable, i tried to create two pdf versions manually, one with wkhtmltopdf and second - with a2x:
Code: Select all
a2x -f pdf ./quickstartguide.asciidoc

To be able to create pdf in this way you need dblatex: http://dblatex.sourceforge.net/

Resulting pdfs differ slightly by style - for me a2x output has a very slightly wider space between text lines. Generated TOC has much wider line spacing as well, but for pros - it creates pdf TOC, so you can use it through document viewer sidebar - so, you don't even need to watch TOC pages in begining, no matter how much they occupy.

Both results are in attachement.
I did not experiment with options yet, so i think style may be improved.

Would be good to add options to control, what tool is used for pdf generation: like --with-pdf-tool=asciidoc/wkhtmltopdf.
Attachments
quickstartguide-dblatex.pdf
(1.46 MiB) Downloaded 28 times
quickstartguide-wkhtmltopdf.pdf
(1.55 MiB) Downloaded 27 times
nick87720z
Trained
Trained
 
Posts: 52
Joined: 25 Feb 2014, 16:37

Re: Support direct pdf generation with asciidoc

Postby Forgon » 23 Feb 2018, 13:38

Your proposal has merit, but the new dependency dblatex requires far more packages to be installed than the old dependency wkhtmltopdf.
On ArchLinux, install sizes are:
I believe we should rather abolish PDF generation, because:
  • we only use it for the (dated) Quick Start Guide which most users never read.
  • most casual users probably open PDFs in a browser, for which there is already the HTML Quick Start Guide.
  • a lot of skilled users hate PDFs.
    The only excuse for them to have ever existed, i.e. the limitations for website appearance in the 1990s, is no longer relevant.
    PDFs still demand the installation of programs like Adobe Reader, are quite hard to edit and load slowly.
Review my new green assignment crosshair cursor: ticket #4778
Forgon
Code contributor
Code contributor
 
Posts: 123
Joined: 07 Dec 2016, 22:23

Re: Support direct pdf generation with asciidoc

Postby nick87720z » 23 Feb 2018, 14:56

Yep, automatic generation from make install doesn't look important. For those, who prefer it from sources, build instruction mention all steps to generate pdf manually.

As for pdf view on windows / osx, there are alternatives for acrobat:
Below are known for me free/opensource viewers:
- Sumatra PDF (win-only, nearly most lightweight): https://www.sumatrapdfreader.org https://github.com/sumatrapdfreader/sumatrapdf
- Evince for windows: https://wiki.gnome.org/Apps/Evince/Downloads
- Okular 4 win (requires kde4win): https://sourceforge.net/projects/okularinst4win/
- Modern windows versions have default document viewer, though i'm not sure in its pdf support, as only once used for XPS, not more.

So, at least downloadable version would be good to present.

p.s. As for lot of pdf haters - various groups of skilled users also hate browsers :)
nick87720z
Trained
Trained
 
Posts: 52
Joined: 25 Feb 2014, 16:37

Re: Support direct pdf generation with asciidoc

Postby Forgon » 23 Feb 2018, 15:19

nick87720z wrote: [...] As for pdf view on windows / osx, there are alternatives for acrobat:
Below are known for me free/opensource viewers:
- Sumatra PDF (win-only, nearly most lightweight): https://www.sumatrapdfreader.org https://github.com/sumatrapdfreader/sumatrapdf
- Evince for windows: https://wiki.gnome.org/Apps/Evince/Downloads
- Okular 4 win (requires kde4win): https://sourceforge.net/projects/okularinst4win/
- Modern windows versions have default document viewer, though i'm not sure in its pdf support, as only once used for XPS, not more.
[...]

You forgot the best viewer, MuPDF :)
And there is of course also Fbpdf for those Unix users who need no Xorg.
Review my new green assignment crosshair cursor: ticket #4778
Forgon
Code contributor
Code contributor
 
Posts: 123
Joined: 07 Dec 2016, 22:23

Re: Support direct pdf generation with asciidoc

Postby nick87720z » 23 Feb 2018, 17:52

Yeah, and MuPDF too. :) (i never focused attention on it as windows document viewer, just had it in gentoo by dependencies)
Yet did not look specially for what is available for osx - sure, mac users never have such issue.

I just responded to statement about Adobe Reader dependency... don't know, could it be some kind of joke :) ... so, i limited self by just few floss tools, available in windows.
nick87720z
Trained
Trained
 
Posts: 52
Joined: 25 Feb 2014, 16:37


Return to Coding