search

alan-if / alan-docs

Alan IF Documentation Project
https://git.io/alan-docs
Other
4 stars 0 forks source link

Chunked HTML Manual #78

Closed tajmone closed 3 years ago

tajmone commented 4 years ago

We need to start experimenting with HTML chunking — i.e. splitting the single-file book into one file per chapter.

Currently, the only viable options seems the asciidoctor-chunker tool, created by @wshito.

Overview

Splitting the single file The ALAN Manual into one file per chapter would allow us to achieve the following goals:

  1. Publish the book on the GitHub Pages repository website in a more orderly manner.
  2. Create an executable eBook for Windows (using a commercial eBook compiler, I have a few of them already).

Roadmap

We need to carry out some local tests first, and once (if) we get good results, we could start looking into automating the whole process of chunking the output book and updating the GH Pages website via some CI service (of course, the eBook creation will have to be done locally).

If we get to that stage, we could then think of publishing all ALAN-related documents (including the StdLib Manual, by fetching a pre-processed "coalesced" single-doc AsciiDoc source and build it inside this repo, since they share common assets).

A Few Side Notes

  1. Installing asciidoctor-chunker under Windows also requires installing additional dependencies:

    1. Roswell — Common Lisp environment setup Utility.
    2. Scoop — A command-line installer for Windows.

    Unfortunately there doesn't seem to be any shortcut to this, since asciidoctor-chunker depends on a Roswell script, so there's no standalone binary version at the end of the line.

    Once we've tested enough to come up with a safe "recipe" on how to use asciidoctor-chunker, we should be able to unload the burden on some CI service — but for creating the executable eBook I'll still need to have asciidoctor-chunker running locally, because of the proprietary book compiler software.

  2. Maybe in the future, when we have more time at hand (and successfully managed to publish the chunked book both online and as an exe-book) we might look into creating a standalone binary tool to chunk the HTML documents, which possibly could be tailored to our needs.

This shouldn't be too hard, but it will definitely take time. I've peeked at the Lisp sources of asciidoctor-chunker, and the tasks it carries out are fairly straight forward (obviously, relying on some external libraries). So, we could use any language that supports similar libraries for parsing XML/HTML documents (e.g. Expat), etc.

  1. Also, we should really get rid of the highlight.js dependency before taking this step, and use a static highlighter — e.g. Highlight or Rogue. Regarding the current problems which are preventing the switch to Highlight for the ALAN Manual, see Issues #49, #50, and #36 (in particular).

References

tajmone commented 3 years ago

asciidoctor-multipage

A new Ruby gem has been just released to create multipage books:

https://github.com/owenh000/asciidoctor-multipage

This project looks promising and we should consider using it instead of the other alternative tools, once it's ready to be used in production.

Right now, asciidoctor-multipage is not mature enough to handle the ALAN Manual, due to some missing features and limitations:

... and possibly other missing features which we'll have to wait that are implemented before we can adopt this gem in our toolchain.

But I believe it's worth waiting for this gem to be ready, rather than invest time and energy on the other workaround tools mentioned above — which would be dropped once asciidoctor-multipage is adopted.

wshito commented 3 years ago

@tajmone I have just released the new JavaScript version of asciidoctor-chunker. The single bundled script is available under the lates release. You can simply run it with NodeJS.

This is the enhanced and faster version. The depth of extraction can be as deep as asciidoctor's maximum subsection level. And you can also control the depth of extraction in each chapter if you want. Of course the footnotes are supported.

I haven't finished cosmetic part for the page navigation. The help is always welcome. If it is too much hassle to write a code, you can send me an additional CSS and I can always put that into the code. Or maybe I can add a theme support.

Feedback is always welcome. Feel free to request the enhancement.

tajmone commented 3 years ago

Thanks a lot for kindly pointing this out @wshito! it really helps.

wshito commented 3 years ago

@tajmone I am pleased to help! I have just published a pre-release build. The page navigation at the bottom of page is also available.