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

[James Madgwick]

On Mon, 07 Jun 2021 19:19:35 +0200
benn <benny.lyons at gmx.net> wrote:

> Hi,
> Didn't get any time over the weekend until now.
> 
> I've just cleaned up my epub branch, but PR #184 was automatically
> closed, so I generated a new PR #186, which is just PR #184 with my
> very old merge conflicts hopefully correctly resolved.

Something seems to have gone wrong the new PR #186. It seems GitHub
wants to merge 109 commits instead of just the latest one (where you've
added epub) and some conflicts seem to have appeared. I think this might
be because of how the branch was fast forwarded. It could probably be
fixed by making a new clone of the latest oi-docs master and adding your
changes to a new branch.

I can see what the changes are and I already tested them last week, so
I can make a PR myself which includes them if you're happy with that.
I'm not sure why the old PR was closed.

> > I'm not opposed to keeping support for older versions of pandoc if
> > we think it's worthwhile. My main concern was the general quality
> > of the output, it's unfortunate that changes to formatting will not
> > be reflected in that case. The best solution to this would be, I
> > think, to provide already compiled PDFs & epub as downloads from
> > the docs website. This way only those who wished to make their own
> > changes would need to run pandoc themselves - thus avoiding
> > difficulties for a general user in getting hold of the correct
> > versions of program.
> Yes, a very good idea. Ultimately, users will not require the source,
> only a button for html, dvi, pdf, epub, ...  but we've a long way to
> go yet.

I don't think it would be too hard. In theory GitHub actions or
similar CI/CD should be able to generate these just as they would
binaries. In practice though installing dependencies such as texlive
may be an issue. Certainly worth exploring.

> > Changing the pandoc PDF formatting to be closer to the OpenSolaris
> > style-guide is probably possible. This could be done with separate
> > yaml and lua pandoc config and potentially an option in the script
> > to chose the PDF formatting style.
> No problem, I can add an option.
> Once I get some time, I'll replace the Bash script with a Python
> version and add a few things in the process like logging, tests, ...

I agree that Python might be more suitable, although I think bash is
probably ok for what we're doing at the moment.

> > As it is now, the PDF output is
> > presentable and look similar to the web docs (when the latest
> > pandoc is used) and without the latest pandoc it's at least
> > readable. For the time being, it would be simple to write up some
> > information on how to pipe the markdown through pandoc, xsltproc
> > and fop to get the example PDF above which is closer to the
> > OpenSolaris doc style - without actually including scripts to do
> > this.
> Maybe if we were to add the options required to generate the
> OpenSolaris style to makepdf.sh -s OpenIndiana, -s OpenSolaris,
> whereby OpenIndiana would be default? I could do this, just send me
> the pandoc command line options, and yaml configuration file.

That would work fine. I made some progress over the weekend on
replicating the OpenSolaris style (officially SolBook) in LaTex. It's
not quite the same as the example PDF in my last email (page breaks are
used, plus a title page). This is actually quite difficult to achieve
in LaTex due to the offset paragraphs. It can be done though and I'll
hopefully have it finished later this week.


-- 
Regards,
James