search

alan-if / alan-docs

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

ALAN Manual 1st Release ETA #74

Closed tajmone closed 3 years ago

tajmone commented 3 years ago

@thoni56, do we have an ETA for the first public release of the new ALAN Manual?

I realize that many Issues for pending tasks were originally added to the New Alan Manual Release Project just because we though we had so much time ahead of us, whereas now suddenly the Beta7 is already out, and we could probably move many non-essential Issues to the Alan Manual (dev) Project instead (which is for long-terms updates of the Manual).

I've already started to sift through the various pending Issues associated with the New Alan Manual Release Project and other Manual-related labels, moving to the long term that which is not strictly necessary.

Still, there are some Issues which might be important for a first release, although not essentials (e.g. designing a proper cover for the PDF edition, and other aesthetic matters).

Maybe we could use this Issue thread to plan the ETA date and discuss what to resolve before the release and what to postpone to future updates.

Mid-November: StdLib v2.2.0 ETA

As mentioned elsewhere, @AnssiR66 and I were planning to release the new StdLib v2.2.0 somewhere around mid-November (a tight deadline, but we should meet it with some sacrifice), so we might consider releasing the new ALAN Manual together with the StdLib update — we could then announce them together, offering a big incentive for authors to give them a go during the Christmas holidays, when they'll have some free time to dedicate to writing a new IF work. We could also announce the new reprint of the ALAN Beginner's Guide, with the full examples sources; although it was already available here, some might have missed it.

Personally, I think this is going to be great news in the IF community, especially since the last year has been quite stale in terms of IF Systems updates (especially with Inform7 having missed it's v1.0 deadline altogether, and no further news updates were released).

ALAN Manual Live Preview links

These links point to the dev-man branch, and will work even after force-pushing to the PR:

thoni56 commented 3 years ago

Well, I'm not a great fan of deadlines, especially in my hobby projects ;-) In the state we are now I think we could merge to master at any time after the Urgent Tasks are done. That would be the new version. It wouldn't be the 1st release, since https://alanif.se is already pointing to the PDF here, but it would be a better and updated version ;-)

Then we could do other improvement work on master, continously providing better and better versions.

Beta 8 feature descriptions should be introduced only on dev-man branch which then needs to be continuously rebased.

(Or is this contradicting something we have already agreed upon when it comes to where we want to do what type of work?)

tajmone commented 3 years ago

Well, I'm not a great fan of deadlines, especially in my hobby projects ;-)

I was just hoping to match the "new" Manual release with the StdLib update (which introduces significant improvements, and many bug fixes, beside the revamped and corrected StdLib Manual), I just though it would be a strong incentive for old (and new) ALAN users to dive again into ALAN during the season holidays.

In the state we are now I think we could merge to master at any time after the Urgent Tasks are done.

Well, then let's focus on making it ready on dev-branch and maybe keep fixing small optional improvements until the StdLib update is ready, and just release them together — the ALAN Manual is definitely going to be ready long before the StdLib, which still requires huge work on its Manual.

That would be the new version. It wouldn't be the 1st release, since https://alanif.se is already pointing to the PDF here, but it would be a better and updated version ;-)

Most of all, I'd emphasize the collaborative aspect of this new version, thanks to AsciiDoc being a text source that can be easily edited collaboratively on GitHub (something that wasn't easy to do with docx/Word like documents).

Then we could do other improvement work on master, continously providing better and better versions.

Beta 8 feature descriptions should be introduced only on dev-man branch which then needs to be continuously rebased.

(Or is this contradicting something we have already agreed upon when it comes to where we want to do what type of work?)

No, this is correct, and it matches the updated CONTRIBUTING.md docs (both the general guidelines for all documents, as well as those specific to the Manual).

AnssiR66 commented 3 years ago

On the other hand, if the new version of the ALAN manual is ready to be published long before the StdLib updated manual, wouldn't it be fine to just go ahead and release the ALAN manual before it? Then, when the StdLib manual also gets ready, there could be a reminder that the new version of the ALAN manual is (and has been, for some time) available as well. And/or, when publishing the new version of the ALAN manual, there could be a "pre-mention" of the StdLib + manual also being updated soon, and people could then start looking forward to that, as well? But, this is just my opinion :-). My point being, I don't wish that the StdLib updating work in any way interferes with/ jars what happens in the ALAN system otherwise, and with how Thomas wishes to bring things forward. I get your idea about the "marketing gimmick" of simultaneous publishing, Tristano, but the marketing can be still carried out even if the ALAN manual is published first...

thoni56 commented 3 years ago

Yes, exactly what I was thinking. We should not let one delay the other. And we can make the "simultaneous" release of the two can be made into more of a publicity stunt ;-)

And it might even happen that there's a beta8 at that time!

That leaves us with only one essential task, the naming question in #76 and if it's associated discussion if it's possible to do some kind of CI build of the document (but that could also wait actually).

(On CI-build: Travis, CircleCI and friends all allows you to use a docker image of your choosing. So it would be completely feasible to build one with the alan-doc required tooling and then use that in the associated CI job to generate a smoking fresh PDF/HTML version of both the master and the dev-man branches. Realised I haven't looked into what the current Travis jobs do...)

tajmone commented 3 years ago

OK then, I'll try to fix all the remaining details today so we'll be ready to merge into master — sorry for the late reply, but I've been in and out of bed with high fever since yesterday, so I didn't have a chance to read the latest comments updates here.

Yesterday I had a chance to look at the ALAN website, and how it links to the documents, and I've realized that it links directly to the docs on master — via raw links to the PDF, and via Live HTML Preview to the HTML version. So, whenever we merge into master the links on the website will be pointing directly to the latest version, without requiring any changes on our side.

The reason I mentioned using CI to deploy the docs directly on ALAN website was mainly due to some limitations on the Live HTML Preview service — i.e. it requires all image assets to be hard-coded inside the document via Data-URI, and it doesn't work properly with highlight.js (in fact, I see that ALAN code is not being syntax highlighted on the Live Preview, whereas syntax highlighting works fine if you open the HTML doc locally).

Hopefully, we'll be soon enabling the GitHub Pages website for this repository, so we'll be able to also serve the HTML documents online without needing the Live HTML service. The main obstacle to achieving that is the need to tweak the Asciidoctor templates in order to provide a navigation bar to allow end users to return to the main menu from the various documents, and then to provide an index page presenting the project. It's doable, but it requires some preparatory work and some dedicated scripts to update the GHPage website (I'd set it to serve from the docs/ folder of master branch, so we don't have to deal with a dedicate orphan branch, and can publish within the repository itself, using the same toolchain).

thoni56 commented 3 years ago

You shouldn't be "working" if you are ill! (Yeah, I know...)

the links on the website will be pointing directly to the latest version, without requiring any changes on our side

Cool, right! Bringing value without any work!

due to some limitations on the Live HTML Preview service ... and it doesn't work properly with highlight.js

That's too bad on the pretty styling you created. But as long as we work towards providing a "perfect" HTML rendering I think we can live with that for now.

I'll think how I could enable uploading an HTML-version to the Alan site from the Alan CI on https://ci.alanif.se. I almost nailed building the documentation on Cygwin, which is what ci.alanif.se is running primarily, but fo-pub did something that created Windows paths which some other step did not like. But I'll re-visit that tonight.

tajmone commented 3 years ago

OK, released!

You shouldn't be "working" if you are ill! (Yeah, I know...)

Hate staying in bed, but trying to rest too when I need (hence the long pauses).

That's too bad on the pretty styling you created.

I was thinking that you could include the build Manual (at lest the HTML version, which is lighter) with the ALAN package — although I'm not sure how this could be done without redundancy, since some packages are split into components. Well, the Manual is for authors, not players, so it could ship with the compiler SDK.

thoni56 commented 3 years ago

Nice! Hurray! Time to celebrate!