You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
I wanted to share what I think could be the work ahead of us for 2022. A lot has been done in the ALAN Docs repository, which is now mature and has been in production for quite a while, so it's time to pump some steroids into it, enhance its toolchain, and expand its goals and services.
I believe that all the goals presented below could be achieved in the arch of year 2022; so hopefully in a year's time all the tasks in this list will be checked as done.
Switching to Rake
After the great results seen by adopting Rake in the alan-i18n and StdLib repositories, we should switch to Rake also in the ALAN Docs repository, and drop all bash/batch scripts in favour of a shell-agnostic toolchain (if well conceived, the Rakefile should run identically in Bash, CMD, and any other terminal/shell, regardless of the OS).
But this is going to be a multi-step process, since there are many publications here as well as different toolchains and the publishing script. So we'll have to cope with having build scripts being gradually replaced by a single Rakefile.
I've already began tweaking the Rake modules at alan-i18n to make them usable here, so we should now be able to cover all the HTML publications out of the box.
Publications' Rake Adoption Order
My suggestion is to proceed by "raking" first the HTML-only publications, starting with the dev and WIP docs, and then look into moving the ALAN Manual build to Rake last, since for the Manual we'll have to also handle the asciidoctor-fopub toolchain, which has been problematic so far in terms of having a single cross platform script (see #66). So, in this order:
Dev Test Docs — in _dev/styles-tests/, which cover various backends:
HTML.
PDF/asciidoctor-fopub.
ALAN Design Docs —in /alan-design/:
Actors in containers
Alan Design Documentation
Alan Rules
Conversion Guide
ALAN 3 Beginner's Guide
HTML.
PDF/asciidoctor-fopub.
The ALAN Author's Guide
The ALAN Manual
HTML.
PDF/asciidoctor-fopub.
(the Alan IDE Guide doesn't need building)
Other Toolchain Tasks
We'll then have to switch to Rake all other toolchain scripts:
Sass & Docinfo file builder.
Dia Diagrams to SVG.
For the Sass tasks, I've already written some ad hoc tasks in other repos, which we can recycle here.
As for the Dia task, that's more problematic since currently it can only be done under Windows, so it might not be a good idea to integrate that task into the main Rakefile since it would end up blocking non-Win users, as well as adding complex dependencies (see Fossy-Cats/Git-Buch_EN#26).
Toolchain Fine Tuning
Once we've managed to achieve all of the above, and replaced all the build scripts with Rake tasks, we'll have to look into some further fine-tuning.
GHPages publishing — use Rake.
Chunked Manual — Create a multi-part chunked version of the Beta ALAN Manual for online reading (see Chunked HTML Version for Website Fossy-Cats/Git-Buch_EN#35) which will also be the starting point for the creation of an executable eBook version of the Manual.
ALAN SDKs — Enforce specific SDK versions according to branch (latest Beta for master, latest Alpha for dev branches).
...other tasks...
GHPages Website Revisited
After having some research, local tests, etc., I've come to the conclusion that we could improve the way we're handling the repository website by using pandoc and custom HTML5 templates to control how the website page is generated. I've also found a few very nice FOSS website templates which we could adapt for this, making the website much nicer.
The website will still be served by a dedicated GHPages branch (i.e. our published branch), but we'd be hosting the website source file in the main repo:
/www/ — a new directory tree with all the pandoc source files, templates, build scripts, etc., which will generate the full website locally (HTML page, CSS, the actual ebooks and Zip files, all in a folder ignored by Git).
A Rake task to publish/update the website will then simply clone in a temp folder the published branch, copy in it all the update website contents, commit and push.
So, the only difference from the current system is that instead of using Jekyll and a default GHPage template, we'd be using a pandoc markdown source file, a custom website template, our own HTML build script — and possibly some PP macros to have finer control over the generated HTML page.
The new publish task will also create the required downloadable Zip archives — e.g. the Beginner's Guide book + code, all editions of the Manual (Beta/Alpha, HTML/PDF, etc.), and even a single archive with all the publications together in one single download.
Rake and Ruby are going to make all this very easy on us, since Rake already has dedicated packaging tasks, and Ruby can handle any level of complexity.
In any case, I've given much thought to this new website approach, and since it's something I've already used in other project I know it's going to provide us with a much nicer website. I also had in mind some elegant ways to present the books, but I'll need to design some book covers first.
Design covers for all publications.
This new website is going to take some time, and will be developed first locally, then tested in a dev branch (we'll be able to build it and preview it locally, without having to actually publish it until it's production ready).
The ALAN Logo (again)
Design the ALAN logo.
But before going for the new website, I really wanted to come up with an official ALAN logo — I know, I know ... the logo was already proposed a few years ago, but everyone seemed to have a completely different idea on how it should look like.
But trust me, if I start brainstorming and sketching draft, I'll eventually come up with the right image, it's just a matter of time and inspiration. I'm good at graphics, and really love working on them, but lately I haven't had much of a chance to work on graphics at all, so it's something I really want to do, even if the logo is finally rejected.
I'm confident that eventually I'll have that Eureka! inspiration moment where the right image simple comes to me, capturing the abstract nature of text adventures and ALAN's identity in a single image which is small enough to be used also for application icons.
Other Ideas
Once all of the above is achieved, I think we could consider the following:
ALAN Docs exeBook — Create a Windows binary publication with all the documents in a single application, for offline reading. You've seen the sample exeBook I've created for the ALAN Manual, so you know the general idea. I could also create a custom tool, instead of using the eBook compiler, and make this binary ebook cross platform, and possibly more feature rich (but that would be more work, so it depends on whether I'll be creating this app for other projects too).
Yearly ISO Image — it would be nice to collect all the latest ALAN tools (for every OS) and ALAN libraries, all the ALAN adventures, along with the documentation, and publish an ISO file which users can download and burn into a CD, or a USB pen. A sort of yearly ALAN edition, with a copy of all the latest ALAN tools and assets. This could be released near one of the main IF contents, to promote IF authors using ALAN. Once all the material is ready, it only requires a toolchain to package it together in any ISO file, add an HTML menu with some intro text and the latest news, and you're ready to publish.
I think that these last two steps are important, since they establish some fixed references for IF authors and ALAN users, acting as reminders that ALAN is alive and kicking, and ever evolving (unlike other major IF systems, which are either stale or in patch-maintenance mode).
Although some of the above points are projection into the long term, I think that's good to have clear goals and a vision of where we're heading. After all, in the past years we've seen that the ALAN project is managing well its advancement, with it's own steady rhythm and pace, more or less constant along the course of the year, and has definitely been picking up a significant momentum in the last two years, in terms of the expansion of its ecosystem and the reunification of scattered projects under a joint umbrella project.
So, why not "dream big" and be optimistic that these goals can and will be achieved — if not in 2022, maybe the year after, it's fine.
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
-
I wanted to share what I think could be the work ahead of us for 2022. A lot has been done in the ALAN Docs repository, which is now mature and has been in production for quite a while, so it's time to pump some steroids into it, enhance its toolchain, and expand its goals and services.
I believe that all the goals presented below could be achieved in the arch of year 2022; so hopefully in a year's time all the tasks in this list will be checked as done.
Switching to Rake
After the great results seen by adopting Rake in the alan-i18n and StdLib repositories, we should switch to Rake also in the ALAN Docs repository, and drop all bash/batch scripts in favour of a shell-agnostic toolchain (if well conceived, the
Rakefile
should run identically in Bash, CMD, and any other terminal/shell, regardless of the OS).But this is going to be a multi-step process, since there are many publications here as well as different toolchains and the publishing script. So we'll have to cope with having build scripts being gradually replaced by a single
Rakefile
.I've already began tweaking the Rake modules at alan-i18n to make them usable here, so we should now be able to cover all the HTML publications out of the box.
Publications' Rake Adoption Order
My suggestion is to proceed by "raking" first the HTML-only publications, starting with the dev and WIP docs, and then look into moving the ALAN Manual build to Rake last, since for the Manual we'll have to also handle the asciidoctor-fopub toolchain, which has been problematic so far in terms of having a single cross platform script (see #66). So, in this order:
_dev/styles-tests/
, which cover various backends:/alan-design/
:(the Alan IDE Guide doesn't need building)
Other Toolchain Tasks
We'll then have to switch to Rake all other toolchain scripts:
For the Sass tasks, I've already written some ad hoc tasks in other repos, which we can recycle here.
As for the Dia task, that's more problematic since currently it can only be done under Windows, so it might not be a good idea to integrate that task into the main
Rakefile
since it would end up blocking non-Win users, as well as adding complex dependencies (see Fossy-Cats/Git-Buch_EN#26).Toolchain Fine Tuning
Once we've managed to achieve all of the above, and replaced all the build scripts with Rake tasks, we'll have to look into some further fine-tuning.
master
, latest Alpha for dev branches).GHPages Website Revisited
After having some research, local tests, etc., I've come to the conclusion that we could improve the way we're handling the repository website by using pandoc and custom HTML5 templates to control how the website page is generated. I've also found a few very nice FOSS website templates which we could adapt for this, making the website much nicer.
The website will still be served by a dedicated GHPages branch (i.e. our
published
branch), but we'd be hosting the website source file in the main repo:/www/
— a new directory tree with all the pandoc source files, templates, build scripts, etc., which will generate the full website locally (HTML page, CSS, the actual ebooks and Zip files, all in a folder ignored by Git).published
branch, copy in it all the update website contents, commit and push.So, the only difference from the current system is that instead of using Jekyll and a default GHPage template, we'd be using a pandoc markdown source file, a custom website template, our own HTML build script — and possibly some PP macros to have finer control over the generated HTML page.
The new publish task will also create the required downloadable Zip archives — e.g. the Beginner's Guide book + code, all editions of the Manual (Beta/Alpha, HTML/PDF, etc.), and even a single archive with all the publications together in one single download.
Rake and Ruby are going to make all this very easy on us, since Rake already has dedicated packaging tasks, and Ruby can handle any level of complexity.
In any case, I've given much thought to this new website approach, and since it's something I've already used in other project I know it's going to provide us with a much nicer website. I also had in mind some elegant ways to present the books, but I'll need to design some book covers first.
This new website is going to take some time, and will be developed first locally, then tested in a dev branch (we'll be able to build it and preview it locally, without having to actually publish it until it's production ready).
The ALAN Logo (again)
But before going for the new website, I really wanted to come up with an official ALAN logo — I know, I know ... the logo was already proposed a few years ago, but everyone seemed to have a completely different idea on how it should look like.
But trust me, if I start brainstorming and sketching draft, I'll eventually come up with the right image, it's just a matter of time and inspiration. I'm good at graphics, and really love working on them, but lately I haven't had much of a chance to work on graphics at all, so it's something I really want to do, even if the logo is finally rejected.
I'm confident that eventually I'll have that Eureka! inspiration moment where the right image simple comes to me, capturing the abstract nature of text adventures and ALAN's identity in a single image which is small enough to be used also for application icons.
Other Ideas
Once all of the above is achieved, I think we could consider the following:
I think that these last two steps are important, since they establish some fixed references for IF authors and ALAN users, acting as reminders that ALAN is alive and kicking, and ever evolving (unlike other major IF systems, which are either stale or in patch-maintenance mode).
Although some of the above points are projection into the long term, I think that's good to have clear goals and a vision of where we're heading. After all, in the past years we've seen that the ALAN project is managing well its advancement, with it's own steady rhythm and pace, more or less constant along the course of the year, and has definitely been picking up a significant momentum in the last two years, in terms of the expansion of its ecosystem and the reunification of scattered projects under a joint umbrella project.
So, why not "dream big" and be optimistic that these goals can and will be achieved — if not in 2022, maybe the year after, it's fine.
Beta Was this translation helpful? Give feedback.
All reactions