Move Shared AsciiDoc Assets to Git Submodule

[tajmone]

Because many of the AsciiDoc related resources in the assets/ folder are almost identical to those used in other ALAN project (alan-docs, Alan3-Italian), we need to move them to an independent repository and then include it here as a Git submodule. This will greatly simplify the maintenance of those assets.

Commonly shared assets will be stored into the _assets/shared/ folder, which will be the Git submodule and contain all the Asciidoctor related resources that can be shared by different projects:

• Highlight syntaxes
• Sass and CSS assets and generated docinfo files
• Asciidoctor extensions and Haml templates
• All Shell scripts for env initialization and custom functions

This operation is going to require some tweaks to the assets in order to make them portable and reusable (e.g. the scripts) and also to the repositories' structure and its build scripts.

We should begin the work in this repository, which has better toolchain scripts, and carry on until all the assets are in a single folder that can be moved to an independent repository. Once this is achieved, we'll add the thus created Git submodule to the alan-docs repos and start editing it until it uses only the assets of the new Git submodule, and get rid of the previous assets.

---

• Rename assets/ and assets_src/ into _assets/ and _assets_src/, and adapt all scripts and READMEs accordingly.
• Edit scripts in _assets/sh/ to make them fully portable and not tied to the any particular repository:
  • Rename init-env.sh to init-core.sh and move to a new local init-env.sh all repository-specific definitions.
  • Edit all functions to use parameters instead of relying on env-vars, and ensure that they are portable across repositories.
• Move all shareable assets into the _assets/shared/ directory tree, and tweak build scripts accordingly.
• Sass/CSS: all the Sass sources should go in the common folder, even if this means that the shared module will contain the CSS of some documents which are not part of the host repository.
  • Find a way to ensure that every repository can build and deploy the docinfo files via the shared assets.

[tajmone]

@AnssiR66, I realize that the above proposed operations are going to take away some time from the current v2.2.0 work, but I really need to move in that direction in order to also keep up with the other repos (alan-docs and ALAN Italian) which rely on the same assets. Keeping multiple versions of the same assets is just to hard, not only because of the redundant work, but also because of tracking the different versions of the various assets can be easily overlooked.

Now that we'll be updating the ALAN syntax definition to optionally support the StdLib keywords, I'll need to update all the Sass/CSS themes too, the Asciidoctor assets and the toolchain scripts; so this is the right time to make the move toward a Git submodule of shared assets, once and for all.

[tajmone]

Using Gem Instead?

The reason this work has halted is due to the recent efforts in moving toward using Rakefiles instead of Shell scripts for the toolchain, and the possibility of creating a Ruby gem for sharing assets, instead of a repository being sub-moduled.

The switch to Rake is already happening on some repositories, as for the Gem option, that still needs some thinking about.