search

alan-if / alan-docs

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

Moving Shared AsciiDoc Assets to Git Submodule #83

Open tajmone opened 4 years ago

tajmone commented 4 years ago

Since many of the Asciidoctor assets used in this repository are also employed by other ALAN related projects (AlanStdLib, Alan3-Italian, and possibly others in the future), I would like to move all the common assets into a Git submodule that can then be shared by all these repos, rendering the maintenance work for these assets much easier to deal with.

This is going to be multi-step delicate operation, and I'll begin its work on the StdLib repository (see #103) because it contains many useful Shell scripts for the toolchain that I'd like to also adopt here (see #81).

Once I've managed to move all the StdLib shareable assets into a Git submodule, I'll proceed by adding the module to this repository and gradually edit the build scripts of the various documents to switch to the new shared assets, and finally get rid of any redundant contents in _assets/.

So we'll be facing a transitional period in which some documents will be still using the old assets while others are switching to their new counterparts from the shared module. We can either carry out the switch work on a temp dev branch, or just do it in master — whichever turns out to be easier to handle.

For the above reasons, we should postpone switching the ALAN Manual from highlight.js to Highlight (see #50) until the module is ready — the same goes for other docs in this project that we were planning to switch to HL (see #49).

tajmone commented 4 years ago

Replacing Bash Scripts with Tcl/Tk or Ruby?

@thoni56, while working in the StdLib repo to improve the toolchain via Bash functions that can handle all the nitty gritty, I start to realize that maybe adopting another scripted language might be a better solution in terms of portability.

So far, I've been targeting Bash in the scripts because Git for Windows ships with Bash, and most Linux and macOS systems should support Bash fairly well, but I'm aware that there often some compatibility issues when it comes to some Bash features terminal emulations.

Tcl/Tk

I've noticed that Git for Windows also ships the latest Tcl/Tk, which could be a good choice as an alternative for Bash scripts. I haven't used Tcl before, but from what I know so far it's a powerful scripting language, and also allows to create some GUI interfaces, which is quite cool. Since Tcl/Tk should be present also on most Linux and macOS distributions, I was wondering if switching the toolchain from Bash scripts to Tcl would be a better idea.

Ruby

Alternatively, we could use Ruby, which is required by all the ALAN repos that use Asciidoctor anyway. I could convert all the present Bash functions that deal handle ALAN files conversions to UTF-8, and sanitation of the ADoc comments, etc., to Ruby functions and even create a dedicate Ruby Gem offering a bunch of ALAN related CLI commands to easily setup the build toolchains for ALAN repositories.

The prospect of having a dedicated Gem to offer ALAN CLI helper commands is quite inviting — not just for the Asciidoctor toolchain, but for other uses as well. Installing a Ruby Gem in a repository might be a better alternative to having to host a Git submodule, and sound more portable in general too.

Since I don't know neither Tcl nor Ruby, I'd have to start learning them anyways, so either choice would be fine with me — and from I gather, they are both beautiful languages which are useful to know. Our needs are not so sophisticated, it all boils down to common file I/O operations, so it shouldn't be hard to switch (actually, I think less harder than trying to create Bash scripts that will work across all OSs).

Also, I'm counting on the fact that I'll be able to find ready-made scripts and libraries for many common tasks (e.g. ISO to UTF-8 conversion, etc.) in both Tcl and Ruby (whereas for Bash, it always requires searching the web for examples, which can be quite time consuming, and when it comes to the problems specific to Bash on Windows, answers are rarely found).

Based on your experience, what's your advise on this? Is the switch worth the hurdle? Is Tcl/Tk a better choice over Ruby?

thoni56 commented 4 years ago

Replacing Bash Scripts with Tcl/Tk or Ruby?

@thoni56, while working in the StdLib repo to improve the toolchain via Bash functions that can handle all the nitty gritty, I start to realize that maybe adopting another scripted language might be a better solution in terms of portability.

So far, I've been targeting Bash in the scripts because Git for Windows ships with Bash, and most Linux and macOS systems should support Bash fairly well, but I'm aware that there often some compatibility issues when it comes to some Bash features terminal emulations.

Yes, this is sometimes a problem. Native MacOS uses an old version of Bash which is a bit incompatible (because of copyrights as I understand it) and is promoting zsh for newer versions.

Tcl/Tk

I've noticed that Git for Windows also ships the latest Tcl/Tk, which could be a good choice as an alternative for Bash scripts. I haven't used Tcl before, but from what I know so far it's a powerful scripting language, and also allows to create some GUI interfaces, which is quite cool. Since Tcl/Tk should be present also on most Linux and macOS distributions, I was wondering if switching the toolchain from Bash scripts to Tcl would be a better idea.

Also surprised to see that odd bird there, probably it is needed for some other Git for Windows things...

Ruby

Alternatively, we could use Ruby, which is required by all the ALAN repos that use Asciidoctor anyway. I could convert all the present Bash functions that deal handle ALAN files conversions to UTF-8, and sanitation of the ADoc comments, etc., to Ruby functions and even create a dedicate Ruby Gem offering a bunch of ALAN related CLI commands to easily setup the build toolchains for ALAN repositories.

The prospect of having a dedicated Gem to offer ALAN CLI helper commands is quite inviting — not just for the Asciidoctor toolchain, but for other uses as well. Installing a Ruby Gem in a repository might be a better alternative to having to host a Git submodule, and sound more portable in general too.

Since I don't know neither Tcl nor Ruby, I'd have to start learning them anyways, so either choice would be fine with me — and from I gather, they are both beautiful languages which are useful to know. Our needs are not so sophisticated, it all boils down to common file I/O operations, so it shouldn't be hard to switch (actually, I think less harder than trying to create Bash scripts that will work across all OSs).

Also, I'm counting on the fact that I'll be able to find ready-made scripts and libraries for many common tasks (e.g. ISO to UTF-8 conversion, etc.) in both Tcl and Ruby (whereas for Bash, it always requires searching the web for examples, which can be quite time consuming, and when it comes to the problems specific to Bash on Windows, answers are rarely found).

Based on your experience, what's your advise on this? Is the switch worth the hurdle? Is Tcl/Tk a better choice over Ruby?

I don't know either either ,-)

I'm unsure of the level of scripting here, but my gut feeling is that it is not worth the work. I would rather considering detecting possible incompatibilities in bash versions that we encounter and handle those, as I am assuming the level of scripting here is not so advanced. (But I know I've had some issues with quoting...)

tajmone commented 4 years ago

Thanks for the reply and clarifications.

True, there isn't anything huge at stake here, mostly file I/O operations, piping and invoking processes; which is also why I thought that a cross platform scripting language (like Ruby) would ensure standard OS interfaces abstractions, and better support for similar operations.

Anyhow, right now I'll carry on with the Bash scripts, since they're almost ready and work fine; but I'll keep an eye open on other solutions, for the long term.