Major Changes on the Horizon...

[tajmone]

@thoni56,

I wanted to share with you some significant updates to the project I had in mind.

Styles Renaming

Currently, we have three different styles (roles) for ALAN code blocks:

1. The default (GitHub styles greyish).
2. lib (dark theme).
3. tutorial (light theme).

The whole idea was to allow some documents to easily distinguish from generic code examples, library excerpts and snippets of the tutorial's source code.

With hindsight, it would have been a much better choice to use dark and light instead, separating any functional meaning from the actual style, and sticking instead to the theme being dark, light or neutral. Probably what I originally had in mind was to allow end users to customize/override the styles to their liking, so that tutorial code would not necessarily have to be light, etc.

But I think that having the default theme as a neutral greyish, and providing the dark and light roles are a better approach, for they allow more freedom of use without sacrificing accuracy of representation (whilst still allowing customizations, e.g. by using alternative themes that are dark, light or neutral).

So, I was thinking of updating these roles in all the source documents, here and across other repos, and update the Sass/CSS stylesheets accordingly, as well as the DocBook template.

Because it's a delicate operation involving synchronization across multiple projects I might need to proceed with caution, especially for the ALAN Manual, since these changes in role names might lead to potential conflicts between the master and alpha man branch.

Maybe the right time to do this would be when the next Beta is out, and the Alpha branch is merged into master and we'll have a few days where the two branches are synched.

These changes are also in view of the upcoming move of all shared assets into a common repository (to be submoduled — See #81, #83) or a dedicated Ruby Gem (more on that below), in either case these solutions are intended to avoid redundancy in maintenance across projects.

Adopting Rake for Building

The more I look into Ruby, the more I'm convinced that we should rely on Ruby for our toolchain. Rake is Ruby's alternative to Make — it's Make without the quirks, problems, hacks and troublesome problems of two different versions being in use.

Rake is not only powerful and simple to use, but it's ideal for our use cases since we need Ruby for Asciidoctor anyway.

Also, relying on Bash scripts to interface with Asciidoctor via the command line doesn't give us the full power of invoking Asciidoctor via Ruby scripts. E.g., if we want to integrate our new custom ALAN syntax for Rouge, the simpler way is to invoke Asciidoctor via its Ruby API.

Rake is more powerful than Make, and its "rakefiles" are just Ruby code on steroids, allowing invoking system libraries, shell commands, etc. In terms of cross platform compatibility, it's definitely a better choice, since Ruby libraries are OS aware — probably the FoPub toolchain would work on all OSs out of the box with Rake.

Furthermore, I was thinking of creating a small Ruby Gem for ALAN projects, which would contain shared assets like the CSS stylesheets, DocBook styles and templates, the syntax highlighters, etc. Being a Gem, we wouldn't need to include it as a Git submodule in every repository, since gems are installed globally, and are easy to update too.

This Gem could also contain some dedicated Rake modules for Alan and Asciidoc specific tasks, like checking that the correct ALAN SDK is present in the repository, based on a settings file (in the repository) and branch-based rules. Various ALAN-related build commands could be simplified via this Gem's modules, especially the complex stuff from the StdLib repository which extracts code examples from real sources (with tag comments that need to stripped off in the final package) and dynamically generated transcripts. All these tasks could be handled by custom commands.

A rakefile would then be created for each repository, in the root folder, allowing to use rake from the root (or even in subfolders) to execute various tasks (tests, builds, publishing on GHPages, etc.) via single commands, and let Rake handle downloading and unpacking the required Alan SDKs, etc.

What's your view on this?

[thoni56]

Styles

I like semantic style naming. I like to separate semantics from presentation. This means that I'd prefer a semantic meaning in the documentation, because it's easier both to be consistent (if the names are good), and to decide about presentation/design separately and ultimately change it everywhere if needed/wanted.

I don't know if there is an "intermediate layer" of names possible here. I'd like the document source to use styles that describe the usage, not the design. So if we could find a way to have a translation from, say, "example" to some presentation style name like "lightgrey" with a single editing of a "mapping" somewhere, that would be my preference.

You say "in hindsight, it would have been better...", do you mean that it is better to give the author of the document source to design the presentation?

Because I think it depends on what we are trying to do. Semantic style names in documents would emphasise that design/presentation is done elsewhere, and probably also a common such design/presentation. Having presentation guiding style names emphasise the authors design/presentation ambitions.

Rake

I have no deep knowledge of Ruby, eventhough I have coded some in it. The use of make or scripts I think is selected with portability in mind, but I agree that they are not always as portable as one might hope, and make.... , well..., it has been overused (by me also) for "scripting".

And as you say, we need Ruby anyway. If there is a scenario where you don't need asciidoctor but still want to do some scripted work, say "linting" the document source, but not generating, that might be a thing to consider, but I think it is unlikely that we find an important such case. And if so, we could just say "install Ruby..."

So, I'd be interested in a rake-ification of the scripts in alan-docs. That would be educational, and it would be possible to have those in parallel for a time before deprecating and removing the older scripts.

[tajmone]

Styles

Having presentation guiding style names emphasise the authors design/presentation ambitions.

Then we are good as we are, since I believe that the roles lib (library) and tutorial cover all the use cases for Alan documents — a block of Alan code is either a generic code snippet, presented for the sake of example; an excerpt from the tutorial being discussed (or built step by step); or a quotation of some external library code (StdLib, Lib 0.6, etc.).

For some reason I started to doubt my original decision to name these styles according to their role, instead of their colour presentation. In any case, I wanted your view on this because ,if we needed to change these, the transition to UTF8, Rouge and Rake would have been the right time to do so.

Rake

I have no deep knowledge of Ruby, eventhough I have coded some in it.

I'm no expert either, but after started reading an eBook on Ruby that I purchased lately (for this goal), I started to realize that Ruby is really simple to learn by design. Also, third party code is easy to read too.

One of the things that impressed me most about Ruby are its syntactic sugar and semantics, which are similar to ALAN philosophy in that they aim to keep programming as close to English prose as possible — keywords like until or unless are good examples of this, they make the code easier to read and more intuitive (until x == 1 is simpler than while x < 1, and unless x == false easier than if x != true) and they make me wonder why other languages didn't think of them too.

It would be fair to say that ALAN and Ruby share a common philosophy, and that if someone loves either of them he/she will probably also love the other one, because of their affinity in design.

As for Rake, it really takes only a five minutes tutorial to be able to use it for a basic built, its syntactic sugar is so intuitive as to be almost self explaining (if you know how tools like Make work, that is). Any previous knowledge of Make is automatically transferable to Rake, in a lossless manner — there are only the gains of rakefiles being Ruby scripts, which allow all the freedom of mixing Make concepts with a real OOP scripting language.

So, I'd be interested in a rake-ification of the scripts in alan-docs. That would be educational, and it would be possible to have those in parallel for a time before deprecating and removing the older scripts.

Indeed, a gradual shift (one doc at the time, beginning with the smaller and simpler ones) is advisable.

If there is a scenario where you don't need asciidoctor but still want to do some scripted work, say "linting" the document source, but not generating, that might be a thing to consider, but I think it is unlikely that we find an important such case. And if so, we could just say "install Ruby..."

Indeed, the Gem I had in mind would probably called "a3make", and provide also non-Asciidoc build helpers, e.g. to quickly compile every ALAN source in a project via a single settings file, or running smart test-suites (i.e. if a folder contain a single Alan source, all solutions should be fed to its storyfile, otherwise each storyfile's solution should have its solutions starting with the same base name, as we're doing in the StdLib test suite). Other features might include auto-conversion from ISO to UTF8+BOM, checking for non-ISO chars in UTF-8 files, and other useful helpers like extracting the IFID from a storyfile, or some other info — none of these would really bloat the Gem, since Ruby code is slim.

As for installing Ruby, this only affects Windows really, since most OSs natively ship with Ruby today. The days of painful Ruby installations on Windows are long gone now, thanks to Ruby for Windows and Chocolatey (and very soon, Win 10's native package manager). Although Windows' Ruby still doesn't offer an easy way to install Ruby Env, switching Ruby version in the shell (any shell, be it CMD, Bash of PS) only requires a single ridk use command (e.g. ridk use 2.7).

The ridk command also installs MSYS2 and handles all MSYS2 operations in the background (the Ruby Choco packages abstracts all this away from end users). While having to install the whole MSYS2 package might be a deterrent for many users (it's huge and takes up a increasingly bigger disk share) its introduction definitely made Ruby usage under Windows better and simpler.

But at least Ruby is much safer than Node JS, and the language doesn't change every month, so a script or Gem written in Ruby 2.7 is most likely going to work also in Ruby 3.x (but execute three times as fast). And Ruby is known to be a safe language to use, even for concurrency.

Although there are differences between Ruby and Python, you can basically achieve the same goals in both. The main differences lie in their design philosophy, the former promoting freedom of expression, the latter the idea that there should be "one and only one correct way to do anything". The impact of these philosophical differences are easier to perceive when joining the online communities, rather than when programming with the langs, for each language appeals to different types of characters. I personally find the Python communities a bit too rigid for my taste, with all its focus on the "right way" to do any bit of code, which necessary emphasizes idiomacy and results in a lot of "you're doing it wrong" (i.e. it works fine, but it's not conformant to our benevolent dictator's guidelines). Ruby, like Alan, promotes freedom, and whilst it advises toward wise usage, it doesn't impose anything (not even an official Ruby distribution, for there are multiple versions of Ruby too).

[tajmone]

Rake Examples at ALAN Testbed

Now the ALAN Testbed repository contains a dedicated folder for testing Rake usage with ALAN projects:

https://github.com/alan-if/Alan-Testbed/tree/master/Rake

The current example is very basic, but as I'm studying Rake more I'll gradually try more complex tests, until eventually we'll be able to use Rake in our ALAN repositories.

So far, I'm really liking Rake a lot. I just have to come up with some tricks on how to handle some details of our toolchains.