Publishing Chunked Book, Split by Chapter

[tajmone]

@SicroAtGit, in the past week I've been experimenting with a new tool that allows chunking AsciiDoc generated HTML files into multi-parts. The results are good, so I was thinking that we could split the Git Book into chapters on the GHPages website, and maybe offer the single-file stand-alone version for download and offline reading.

What do you think?

If it's OK with you, I'll proceed to publish the book split by chapters, and also work out a way to include into the repository a single-file version (embedded images, to be portable) and add some conditional directives so that on the website version a direct download link is provided for those who wish to download the single HTML file for offline reading.

It might take some time, since I'll have to fiddle with Rake, do some tests, etc., but it's doable.

Unfortunately the chunker tool is a Node.js app, which means that we'll be adding Node.js to the project dependencies:

https://github.com/wshito/asciidoctor-chunker/

[SicroAtGit]

Good idea.

The multi-pages are better for the search engines and they will increase the loading speed.

The disadvantage is that you have to switch pages afterwards, which could be annoying over time. On PC, fortunately, you can also use the keyboard keys ← and →, but on tablet, screen swipe to left or right doesn't work. Maybe the side menu is causing the problem. BTW: It would be good if it was possible to hide this side menu to have more space for the actual content of the page on small screens.

Node.js is already required for SVGO, but yes, as you mentioned before, diagram creation is not part of the main build process.

[tajmone]

The multi-pages are better for the search engines and they will increase the loading speed.

Especially the loading speed, which can be problematic on portable devices. It's also more practical when searching for a term, so you can restrict the search to the current chapter (although sometimes one might need to search the whole book).

In any case, we'll still offer the single-document (fully standalone) for download, so this is for online consultation mostly.

The disadvantage is that you have to switch pages afterwards, which could be annoying over time. On PC, fortunately, you can also use the keyboard keys ← and →, but on tablet, screen swipe to left or right doesn't work.

The chunker adds a the bottom of the page a navigation bar with the "previous" and "next" arrows, so that's fairly practical (only need to jump at the bottom of the page and click).

Maybe the side menu is causing the problem.

I'm not sure about this, but there is a JavaScript file associated with the sidebar, so it might be that.

BTW: It would be good if it was possible to hide this side menu to have more space for the actual content of the page on small screens.

Right now the options in this respect are somewhat limited, but the author of the chunker is planning to add a templating system which would allow to customize many aspects of the final look & feel of the chunked pages, which should include an improved sidebar (via JQuery) that handles auto folding and unfolding the TOC according to which chapter is currently being navigated, and hiding the sidebar via a dedicated button, plus other things like dark/light theme, etc. But it might take a while for this to happen, since the author has limited free time (but discussion on these feature are actively taking place).

Node.js is already required for SVGO, but yes, as you mentioned before, diagram creation is not part of the main build process.

Yes, and I'd like to keep it that way. In fact, contributors can still build the preview and standalone documents even if they don't have Node.js — we'll have to add to the repository the standalone single-file version too, with embedded assets, for the preview document by design uses external images (to allow refreshing the page to see changes in the images).

I think I'll start working on this in a dedicated branch, because there is some post-processing work to do on the chunked files, to overcome some limitations of the chunker:

• Every page has the same title, we should change that to Section title. (Preserve Section Title in Chunked Pages wshito/asciidoctor-chunker#30).
• Chunked pages are named chap-<nn>.html, but we should use GitBook-<nn>.html instead. (Alternative Chunked Files Naming Scheme wshito/asciidoctor-chunker#29)

I'd like to fix these using Ruby (possible via Rake) instead of SED, so the build doesn't depend on OS specific tools (different versions of SED ship with different OSs). The latter is a bit of a pain because renaming the documents requires fixing every cross-link too, but unfortunately the request to preserve the original filename (as intended by the author) or provide a CLI option to control the chunked filenames has been rejected.

Probably the quickest solution for the files naming problem is to tweak the chunker so that it uses GitBook instead of chap during the chunking process. Since the chunker builds to a single JS file, I could create a modded version, which can store in the repository and invoke via Node.js, so there's no need for contributors to install the chunker via NPM (but then we'll have to update it manually if we want to keep enjoying new versions of the tool).

So it might take some time before the branch is ready for production.

Quite frankly, I've been tinkering with the idea of creating a Ruby chunker similar to asciidoctor-chunker (i.e. working on the generated HTML doc) but with more options, because I'll be needing this a lot for my eBooks projects, and because I see that there are irresolvable differences in opinion on which options and features should go into a chunker.

E.g. I can't understand why the chunker should arbitrarily rename the original file into chap-<nn>.html instead of preserving the original filename as intended by the author, especially since it's a bad semantic choice given that not all files are chapters (appendices are not chapters), but my proposal to retain the original filename has been turned down.

It probably boils down to differences in the way we use the chunker in everyday life, for it seems to me that the Node.js chunker is designed mostly to convert single-documents into websites (main page becoming index.html), rather then targeting editorial work in the publishing sector, where multiple chunked documents might need to coexist in a same folder, and where editorial guidelines are stricter and demand fine-grain control over various aspects of the generated documents (file-naming convention, title tags, footnotes at end of each chapter vs dedicated section at end of the book, etc.).

[SicroAtGit]

The disadvantage is that you have to switch pages afterwards, which could be annoying over time. On PC, fortunately, you can also use the keyboard keys ← and →, but on tablet, screen swipe to left or right doesn't work.

The chunker adds a the bottom of the page a navigation bar with the "previous" and "next" arrows, so that's fairly practical (only need to jump at the bottom of the page and click).

Yes, it's not a problem, just a convenience feature.

I have seen why screen swipe does not work on the Tablet PC: The HTML/JavaScript code does not handle the required events, only the keyboard arrow key events.

But it is not a task for this project, I will submit the feature request in the asciidoctor-chunker repository.

E.g. I can't understand why the chunker should arbitrarily rename the original file into chap-<nn>.html instead of preserving the original filename as intended by the author, especially since it's a bad semantic choice given that not all files are chapters (appendices are not chapters), but my proposal to retain the original filename has been turned down.

I have read your issues in the asciidoctor-chunker repository and I also can not understand why the author does not make it customizable.