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

[benn]

Hi,

On Mon, 2021-06-07 at 19:37 +0100, James Madgwick wrote:
> 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.
Go ahead. No more work this evening for me.

> > > 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.
Agreed. Experience, however, reveals that as we keep adding just one 
more small feature, we have a problem in the asymptote. But lets save
the time until it is needed.

> > > 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.
Great, looking forward to this. While the style is really something for 
the future, i.e.,  not the highest of priority, I personally still think
it is important.

Cheers
Benny