[oi-dev] PR #184: Support for epub and pandoc version problems

[James Madgwick]

On Wed, 02 Jun 2021 23:19:27 +0200
benn <benny.lyons at gmx.net> wrote:

> Hi,
> I've added a Pull Request, 'Add support for epub and different pandoc
> versions #184', which resolves a number of problems with the current
> makepdf.sh script.
> 
> I thought support for epub generation had been added, but this was
> only done locally for my own use. I tried to add this feature with
> the most recent changes to makepdf.sh, but discovered that pdf
> generation was broken on my system. 

It looks like you did submit a PR some time ago for this
(https://github.com/OpenIndiana/oi-docs/pull/94) which was never merged.

> After some investigation, I discovered that pandoc was the culprit.
> The recent update to makepdf.sh  caused pandoc to fail on my system
> because the version of pandoc that I was using did not support the
> changes to makepdf.sh.

Only after some struggling with errors in the Lua filter did I realize
the features needed to make the PDF presentable required the latest
version of pandoc, or at least a version newer than the one found in
Debian stable. I installed the deb directly from the pandoc GitHub
releases.

> pandoc introduced new features in 2.3.0, and the latest Debian
> version of pandoc did not support these features, which caused the
> failure. The PR contains a makepdf.sh that should work with pandoc
> versions prior to 2.3.0 and later versions; although the results of
> the pdf created will be different. We do not have a pandoc package
> for OI which would ease the problem.  However, pandoc is big and it
> might not be trivial to create such a package for OI.

I don't know much about packaging, though I agree that it would be
useful to have in OI - maybe I will look into this. However, I'm not
sure if it's worth generating PDFs at all without a recent version of
pandoc, given the poor quality of the output.

> The generation of the epub format of the manuals provided, in the
> past, output that was sufficient for me to proof read. Alas with the
> newer versions of pandoc I have not been able to review this.

Using the latest version of pandoc, the epubs appeared to be ok, though
I have no experience with the format.

> The quality of the pdf produced needs to be improved and the quality
> of epub has still to be examined.

The PDF is quite ok with the latest pandoc I would say (example:
https://github.com/OpenIndiana/oi-docs/files/6566753/getting-started.pdf).
It could do with a few tweaks to the LaTex, but nothing much is needed
urgently. Unlike LaTex I don't know about epub, it does seem like there
are extra settings which can be tweaked in padoc, but far fewer than
for LaTex/PDF.

> Looks like the build for this PR is failing, but the failure appears
> to arise from elsewhere.

I've pushed a fix for this. I think you can just rebase your fork and
it will pass.


-- 
Regards,
James