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

[benn]

Hi,

On Thu, 2021-06-03 at 22:31 +0100, James Madgwick wrote:
> 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.
I think this can be scrapped, I've forgotten what, why, ...  And this was not a
_complete_ contribution, only non-complete information. Lets just dump it.

> > 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.
I think, I'm very much open to correction here, the settings in yaml (or xml) 
configuration files, can also be passed as command line options to the older
pandoc version (i.e., 2.2.1).
> > 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.
I want pdf and I can produce acceptable, very much readable pdfs. What I did not do
was do do _any_ tweaking with the pdf output. This tweaking is very important to
produce output to the style consistent with the OI defined style, which is, more or
less I think, the style set out by  Solaris/OpenSolaris.

> > 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.
Producing the appropriate format is important, difficult and time consuming. The
OpenSolaris produced a very nice guide indeed called 'Documentation Style Guide for
OpenSolaris.' It is over 250 pages long and contains a wealth of information. (It is
generally available somewhere, but if you---or anyone else contemplating doing docs
for OI--- cannot readily get your hands on a copy, just let me know and I'll send you
a copy. Moreover  they put a lot of time and, more importantly, experience into such
things as style, etc.

We should be aiming to use the style set out there.

Now to emulate this style, if the more recent pandoc version is easier for you,
great. I'll get makepdf to work for you. Anyway, it must be a goal with OI to support
 more recent versions of software and you are, currently, the only one tweaking the
pdf style
However, my old pdf generation mechanism was broken and I cannot easily update to a
newer version yet. Agreed, the old mechanism will have to die, but killing Debian (or
any other platform plagued) users ought to be avoided. Think of the unfortunate
Gentoo Linux user having to recompile pandoc just cause something they do not really
need breaks! So the old pdf generation mechanism will have to become deprecated; but
not quite yet.


> > 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.
The epub was, like the pdf, there for me, my personal use without any tweaking. It
has proved to be exceptionally handy. This needs serious tweaking to coincide with
the OpenSolaris style-guide.
> > 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.
>
>

The build fails because the lint syntax checker has some error. Run the following:
    mdl -s markdownlint-rules.rb .
fix the errors, rerun, ... Once this runs without errors, you can commit.

Maybe we should dump this check into the newer python makedoc, or whaterver we can
call makepdf, as I tend to by-pass the html stuff while working. 

Benny