search

theopensourceway / guidebook

Guidebook of open source community management best practices; is somewhat opinionated.
Other
168 stars 41 forks source link

Adds epub to the build process. #217

Closed rbowen closed 3 years ago

rbowen commented 3 years ago

This adds epub to the output of the build process, using the asciidoctor-epub3 tool.

rbowen commented 3 years ago

Adds .mobi and .epub to the build process. Note that it spits out errors during build:

asciidoctor: WARNING: Warning(prcgen):W14016: Cover not specified asciidoctor: ERROR: KindleGen failed to write MOBI to /home/rbowen/devel/OpenSourceWay/the_open_source_way-guidebook-2.0.mobi

but does in fact build the file. I'll look into what's expected in terms of a cover, but I'm not yet sure what the ERROR means, since it clearly does write the .mobi file, which, in turn, does work on my Kindle.

rbowen commented 3 years ago

Further investigation (--verbose flag) reveals that the ERROR just means "didn't exit with success status", which is, in this case, completely because of the lack of a cover. So, not actually a failure. But we probably do want, at some point, to provide a cover.

Details about creating a cover are here: https://docs.asciidoctor.org/epub3-converter/latest/#adding-the-cover-image

quaid commented 3 years ago

Thanks for chasing this down, I too really want this support in the project's toolchain. I also want the .epub and .mobi available for people to download. I'm seeing those as distinct right now because we aren't running a build service or pipeline, meaning building the artifacts (HTML, PDF, EPUB, MOBI, etc.) is done by rendering them locally, then checking those in to be automatically deployed to the website.

This was never the intended place to stop, it was just epidient. So let's figure out a way forward!

Publishing the new artifact

I will try to get this running myself, then test and publish the results, if good. Read on for more on that.

Toolchain

I am running a stock Fedora 33 system and couldn't test your patch locally because there is not an asciidoctor-epub3 package in any Fedora repo. I know I can potentially solve this with installing the gem with Ruby, but I haven't always had good luck with that either But the point is, it's not a contributor-friendly toolchain if it requires extra hoops.

A few years ago I would have wanted it packaged in Fedora or Copr, now I would want a Toolbox with the whole dev/build environment.

But the real solution is to ask @mscherer for help in bringing this to the next level, so that a check-in to the repo does something like rebuild all the artifacts in build_book.sh and drops them into theopensourceway.org/2354a6c/ for final approval (where 2354a6c is the uni. Another bot command triggers a promotion of artifacts to theopensourceway.org/, cleaning up old folders as it goes. So giving someone permissions in the git repo allows them to test changes and commit them. Perhaps a final step is they create a pull request against main? And two people have to ack the changes or something?

quaid commented 3 years ago

OK, I can get the build environment working by following the upstream install directions, and then I also had to install kindlegen. At that point, it performed as @rbowen described, except for the creation of a the_open_source_way-guidebook-2.0-kf8.epub file.

I wasn't familiar with the kf8 acronym, apparently "KF8 is Amazons new Kindle Format 8 used on the Kindle Fire." If I read that correctly, this includes Amazon's DRM. I also see it's intended to be a default format by Kindle, so KindleGen might make that the default output.

Since I'm guessing others in the project are interested in avoiding releasing an artifact encumbered by DRM, what I'm going to do for now is include a step in the build script to vaporize that artifact so it doesn't get released from the website. We can discuss all this on the mailing list, too.