Skip to content

Commit

Permalink
B.Guide Scripts
Browse files Browse the repository at this point in the history 
Start polishing the "Beginner's Guide" build scripts, dropping all the
non-essential batch scripts and replacing them with Bash scripts.

The only batch script preserved is `PDF_BUILD.bat`, due to the known
issues with trying to use asciidoctor-fopub from Windows Bash (#66).

Also polish the B.Guide's README files, removing all redundant info on
the Lib v0.6 and linking instead to the ALAN Wiki and the Alan Goodies
repositories to obtain more info.
  • Loading branch information
@tajmone
tajmone committed May 24, 2021
1 parent 841bd25 commit 8d8bbfc
Show file tree
Hide file tree
Showing 11 changed files with 85 additions and 301 deletions.
7 changes: 0 additions & 7 deletions alanguide/BUILD_ALL.bat
View file

This file was deleted.

34 changes: 0 additions & 34 deletions alanguide/HTML_BUILD.bat
View file

This file was deleted.

24 changes: 13 additions & 11 deletions alanguide/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,9 +45,9 @@ Obviously, the reader is encouraged to study and use the newest [ALAN Standard L


# Folder Contents

- [`alanguide.css`][guide css] — _Beginner's Guide_ extra stylesheet.


The reader will also need to download the source files of the __ALAN Library__ required to follow the tutorial steps, as well as the complete sources of the _TV TIME!_ adventure created during the tutorial.

- [`/alanguide-code/`][alanguide-code] — Alan sources of (and for) tutorial.
Expand All @@ -68,9 +68,13 @@ The reader will also need to download the source files of the __ALAN Library__ r

## Conversion Scripts

- [`BUILD_ALL.bat`][BUILD_ALL.bat] — convenience batch to invoke all conversion scripts at once.
- [`HTML_BUILD.bat`][HTML_BUILD.bat] — batch script to create `alanguide.html` document.
- [`PDF_BUILD.bat`][PDF_BUILD.bat] (_experimental_) — batch script to create `alanguide.pdf` document (currently ignored in repository).
| script | output | supported OSs |
|----------------------------------|------------------|---------------|
| [`html_build.sh`][html_build.sh] | `alanguide.html` | all |
| [`pdf_build.sh`][pdf_build.sh] | `alanguide.pdf` | Linux, macOS |
| [`PDF_BUILD.bat`][PDF_BUILD.bat] | `alanguide.pdf` | Windows |

Unfortunately, the `pdf_build.sh` script doesn't currently work under Bash for Windows due to paths resolution problems ([Issue #66]), so we need to keep also a batch version (`PDF_BUILD.bat`).


> **NOTE** — (2020/12/27) Now the AsciiDoc sources exploit the new (and undocumented) `encoding` option for the `include::` directive, so the toolchain no longer needs to first convert external ALAN sources and transcripts to UTF-8 before their inclusion in the source documents (see [Issue #84]).
Expand Down Expand Up @@ -156,9 +160,7 @@ The original `plasma.jpg` image was converted to `plasma.png`, a PNG with transp
[alanguide www]: https://alanif.se/files/alanguide/alanguide.html "View the 'Alan 3 Beginner's Guide' at Alan website (outdated version)"

[styling conventions]: ../CONVENTIONS.md "Read the 'Formatting and Styling Conventions' guidelines adopted in Alan-Docs"
[BUILD_ALL.bat]: ./BUILD_ALL.bat "Batch script to invoke all the Alan Guide conversion scripts."
[HTML_BUILD.bat]: ./HTML_BUILD.bat "Batch script to convert the Alan Guide to a single-file standalone HTML5 document."
[PDF_BUILD.bat]: ./PDF_BUILD.bat "Batch script to convert the Alan Guide to PDF document."


[ALAN Standard Library 2]: https://github.com/AnssiR66/AlanStdLib "Visit the official repository of the ALAN Standard Library 2"

Expand Down Expand Up @@ -192,13 +194,12 @@ The original `plasma.jpg` image was converted to `plasma.png`, a PNG with transp
<!-- Project Files -->

[guide]: ./alanguide.asciidoc
[guide html]: ./alanguide.html
[guide css]: ./alanguide.css
[guide pdf]: ./alanguide.pdf

[BUILD_ALL.bat]: ./BUILD_ALL.bat "Batch script to invoke all the Alan Guide conversion scripts."
[HTML_BUILD.bat]: ./HTML_BUILD.bat "Batch script to convert the Alan Guide to a single-file standalone HTML5 document."

[html_build.sh]: ./html_build.sh "Bash script to convert the Alan Guide to a single-file standalone HTML5 document."
[PDF_BUILD.bat]: ./PDF_BUILD.bat "Batch script to convert the Alan Guide to PDF document."
[pdf_build.sh]: ./pdf_build.sh "Batch script to convert the Alan Guide to PDF document."
[TODO]: ./TODO.md "View the TODO document"

[docinfo]: ./docinfo.html "View docinfo source"
Expand Down Expand Up @@ -226,6 +227,7 @@ The original `plasma.jpg` image was converted to `plasma.png`, a PNG with transp

<!-- Repo Issues -->

[Issue #66]: https://github.com/alan-if/alan-docs/issues/66 "Issue #66 — Shell Scripts Produce Corrupt PDFs under Bash for Windows"
[Issue #84]: https://github.com/alan-if/alan-docs/issues/84 "Issue #84 — Use New encoding Option with include:: Directives"

<!-- EOF -->
36 changes: 0 additions & 36 deletions alanguide/alanguide-code/COMPILE.bat
View file

This file was deleted.

196 changes: 29 additions & 167 deletions alanguide/alanguide-code/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,6 @@ The source files for the _TV TIME!_ adventure and its dependencies.
- [Library Contents](#library-contents)
- [The `lib` Folder](#the-lib-folder)
- [The `mylib` Folder](#the-mylib-folder)
- [Some Background on the Libraries](#some-background-on-the-libraries)
- [Library Details and Tweaks](#library-details-and-tweaks)
- [Fixes](#fixes)
- [Reverts from 0.6.1](#reverts-from-061)

<!-- /MarkdownTOC -->

Expand All @@ -25,32 +21,43 @@ The source files for the _TV TIME!_ adventure and its dependencies.

# Folder Contents

- [`/lib/`][lib] — Library v0.6.2 original sources.
- [`/mylib/`][mylib] — Library v0.6.2 modified as indicated tutorial.
- [`COMPILE.bat`][COMPILE] — script to compile the adventure.
- [`/lib/`][lib/] — Library v0.6.2 original sources.
- [`/mylib/`][mylib/] — Library v0.6.2 modified as indicated tutorial.
- [`build.sh`][build.sh] — script to compile and test the adventure.
- [`plasma.png`][plasma] — required adventure asset.
- [`tvtime.alan`][tvtime.alan] — the final _TV TIME!_ adventure.

The `lib/` folder contains a copy of the original ALAN Library v0.6.2; the reader will need it to carry out the tutorial steps, which require editing the original library sources and adapt them to the needs of the _TV TIME!_ adventure.
The [`lib/`][lib/] folder contains a copy of the original ALAN Library v0.6.2; the reader will need it to carry out the tutorial steps, which require editing the original library sources and adapt them to the needs of the _TV TIME!_ adventure.

The `mylib/` folder contains a modified copy of ALAN Library v0.6.2, with all the changes indicated by the tutorial already applied. This folder is needed in order to compile the `tvtime.alan` adventure.
The [`mylib/`][mylib/] folder contains a modified copy of ALAN Library v0.6.2, with all the changes indicated by the tutorial already applied.
This folder is needed in order to compile the `tvtime.alan` adventure.

While studuying the tutorial, the reader will need to create his/her own copy of the `lib/` folder, and apply to it the changes indicated in the various steps of the tutorial. Because the tutorial takes a gradual approach, where the _TV TIME!_ adventure grows progressively, you won't be able to use the files from the `mylib/` folder straight away, for each intermediate version of the tutorial code needs a specific set of tweaks to the library code. The reader will have to manually implement these as he goes along the tutorial.
While studying the tutorial, the reader will need to create his/her own copy of the `lib/` folder, and apply to it the changes indicated in the various steps of the tutorial.
Because the tutorial takes a gradual approach, where the _TV TIME!_ adventure grows progressively, you won't be able to use the files from the `mylib/` folder straight away, for each intermediate version of the tutorial code needs a specific set of tweaks to the library code.
The reader will have to manually implement these as he goes along the tutorial.


# Alan Library v0.6.2

The original _Beginner's Guide_ uses ALAN Library v0.6.1 throughout the tutorial examples, which was an old version of the ALAN Library ported from ALAN 2, and now superseeded by the newer [ALAN Standard Library 2] by [Anssi Räisänen].
The original _Beginner's Guide_ uses ALAN Library v0.6.1 throughout the tutorial examples, which was an old version of the ALAN Library ported from ALAN 2, and now superseded by the newer [ALAN Standard Library 2] by [Anssi Räisänen].

In order to preserve usability of the code examples, I've included here a full copy of the ALAN Library v0.6.2, which was its latest version before the shift to Library v1, and made a few tweaks to make it closer to the original v0.6.1 used in the tutorial but keep the ALAN compatibility chages of v0.6.2 (more details below).
In order to preserve usability of the code examples, I've included here a full copy of the ALAN Library v0.6.2, which was its latest version before the shift to Library v1, and made a few tweaks to make it closer to the original v0.6.1 used in the tutorial but keep the ALAN compatibility changes of v0.6.2.

For detailed info about the ALAN Library v0.6.2 used here, its history and my changes to it, visit the [Alan Goodies] repository, which now hosts the official archive copy of the library:

- https://github.com/alan-if/alan-goodies/tree/master/libs/ALAN-Library_0.6/

For more information on the history of the various ALAN libraries, see the ALAN Wiki:

- https://github.com/alan-if/alan/wiki/Alan-Libraries

The ALAN Library was originally included in the [ALAN repository], inside the [`lib/`][last lib] subfolder, but when Anssi's StdLib became an independent project they were removed from the repository.

## Library Contents

### The `lib` Folder

This [`lib/`][lib] folder contains a copy of the old Alan Library v0.6.2, taken from the Alan repository. Some unnecessary files were left out on purpose (automation scripts, test files, TODO, etc.).
This [`lib/`][lib/] folder contains a copy of the old Alan Library v0.6.2, recovered from the Alan repository.
Some unnecessary files were left out on purpose (automation scripts, test files, TODO, etc.).


- [`lib/std.i`](./lib/std.i) — main Library module, imports all other modules:
Expand All @@ -60,11 +67,10 @@ This [`lib/`][lib] folder contains a copy of the old Alan Library v0.6.2, taken
- [`lib/notes.txt`](./lib/notes.txt) — Some guidelines for using `std.i`.
- [`lib/ReadMe`](./lib/ReadMe) — Original Library README file.

More info on their origin and tweaks can be found further on.

### The `mylib` Folder

The [`mylib/`][mylib] folder is a copy of [`lib/`][lib] but with all the changes from the tutorial.
The [`mylib/`][mylib/] folder is a copy of [`lib/`][lib/] but with all the changes from the tutorial.

The following library files were changed:

Expand All @@ -82,167 +88,23 @@ And the following files were added:
- [`mylib/cut.i`](./mylib/cut.i)
- [`mylib/plug.i`](./mylib/plug.i)


## Some Background on the Libraries

Having joined the ALAN community when Anssi's StdLib 2.1 was already the new established library (i.e. Tristano speaking here), I haven't had any actual experience with previous versions of the ALAN Library.

From what I've gathered, the evolution of the ALAN standard libraries is roughly as follows.

- The original __ALAN Library__, up to v0.4.0 (2001–2002), was designed for ALAN 2.
- __ALAN Library v0.4.1__ was ported to work with ALAN 3, and was updated up to v0.6.2 (2002–2007).
- __[ALAN Library 1]__ (2010–2011) was a new library design (redesign?) by [Anssi Räisänen], where the library code was organized into four main sumodules.
- The __[ALAN Standard Library 2]__ (2016–) was designed by [Anssi Räisänen], this being a new library altogether, targeting specifically ALAN 3 new features and introducing extensive features in formally organized library structure. This is the current ALAN Library in use today, v2.1 being the latest release.

The original ALAN Library, up to v0.6.2 was the result of the collaborative joint effort of Göran Forslund, Stephen Griffiths and Thomas Nilsson (now Thomas Nilefalk). The [ALAN Library 1] was designed by [Anssi Räisänen]. The new [ALAN Standard Library 2] (aka StdLib) is the work of [Anssi Räisänen].

All three libraries are distributed under the Artistic License 2.0.


## Library Details and Tweaks

The library files of v0.6.2 used here were taken from commit [`c44766fa`][c44766fa] (2017/04/17) of the ALAN repository — the next commit ([`18c72f83`][18c72f83]) removed the whole library, so I'm assuming that these were the latest files available for ALAN Library v0.x.

I've also used for comparison the files from Library v0.6.1, taken from commit [`e002f20c`][e002f20c], to preserve a few elements that were changed in v0.6.2 and to keep the library closer to the code used for the original tutorial.

The [ChangeLog](./lib/ChangeLog) for v0.6.2 mentions the following changes:

```
0.6.2 : November 2007 (SG)
invent.i : changed 'the Worn' from a 'thing' to an 'entity' (to make compatible with recent versions of Alan3)
meta.i : remove q verb and made q synonym of 'quit' (no longer need a warning
about quit being not undoable because it is undoable in recent Alan3 versions)
```


Ultimately, this is Library v0.6.2 with the following fixes and tweaks applied (you may consider it either as "v0.6.1 improved", or as an hybrid between v0.6.1 and v0.6.2).

### Fixes

The indentantion of all library sources was fixed, and all tabs converted to spaces (2 spaces per tab). Lines were joined or split in a few places, to make the code more readable.

- `lib/invent.i`

I've changed `THE worn ISA thing IN hero` into `THE worn ISA entity`, as it should have been in the first place. In fact, the header comments state:

```alan
-- invent.i
-- 0.6.2 : changed 'the Worn' from a 'thing' to an 'entity'
```

so it looks like the `ISA thing IN hero` might have been actually an error. In any case, that line it was preventing compilation, so it had to be changed.

### Reverts from 0.6.1

I've also preserved some default attributes and CHECKS from v0.6.1 that were removed in v0.6.2. My assumption was that the _TV TIME!_ example might rely on them.

- `lib/open.i`

Restored the `And obj1 Is openable` CHECK:

```alan
Add To Every object
Verb close_with
When obj1
Check obj2 In hero
Else "You don't have" Say The obj2. "."
And obj1 Is openable
Else "You can't close" Say The obj1. "."
Does -- To be overridden by "Does Only" Where appropriate...
"You can't close" Say The obj1. "with" Say The obj2. "."
End Verb.
End Add To.
```

which in v0.6.2 was removed:

```alan
Add To Every object
Verb close_with
When obj1
Check obj2 In hero
Else "You don't have" Say The obj2. "."
Does -- To be overridden by "Does Only" Where appropriate...
"You can't close" Say The obj1. "with" Say The obj2. "."
End Verb.
End Add To.
```

- `lib/people.i`

Restored some default for the `person` class definition:

- `Is Not named.`
- Customized `Description` based on `named` attribute.

I've kept the code from v0.6.1:

```alan
Every person Isa actor
Is Not named. -- If it has a proper name
Description
If This Is Not named Then
"There is" Say An This. "here."
Else
Say This. "is here."
End If.
End Every person.
```

which in v0.6.2 had become:

```alan
Every person Isa actor
End Every person.
```

These are really small tweaks intended to keep the library files as close as possible to those used in the original tutorial, but at the same time preserve the benefits of v0.6.2 — which basically boil down to the `worn` becoming an `entity` and the improved `quit` verb that leveraged newly added support for UNDO functionality in ALAN.

Also, it's not clear why the above CHECKs and defaults were removed (no other changes are present in v0.6.2 beside those mentione here), but my hypothesis is that there were many "tweaked" versions of these libraries circulating at the same time, and that the updates to v0.6.2 were made over a slightly different version of 0.6.1.


<!-----------------------------------------------------------------------------
REFERENCE LINKS
------------------------------------------------------------------------------>

[ALAN Library 1]: https://www.alanif.se/download-alan-v3/download-library/library-v1-00 "Go to the download page of ALAN Library v1.0 on ALAN website"

[ALAN Standard Library 2]: https://github.com/AnssiR66/AlanStdLib "Visit the official repository of the ALAN Standard Library 2"
[Alan Goodies]: https://github.com/alan-if/alan-goodies "Visit the ALan Goodies repository on GitHub"

[ALAN repository]: https://bitbucket.org/alanif/alan "Visit the official ALAN repository on Bitbucket"
<!-- Tutorial code assets -->


<!-- Tutorial code assets ---------------------------------------------------->

[lib]: ./lib/ "Navigate to folder"
[mylib]: ./mylib/ "Navigate to folder"
[tvtime.alan]: ./tvtime.alan "View source file"
[COMPILE]: ./COMPILE.bat "View source file"
[lib/]: ./lib/ "Navigate to folder"
[mylib/]: ./mylib/ "Navigate to folder"
[build.sh]: ./build.sh "View source file"
[plasma]: ./plasma.png "View image"
[tvtime.alan]: ./tvtime.alan "View source file"


<!-- people ------------------------------------------------------------------>
<!-- people -->

[Anssi Räisänen]: https://github.com/AnssiR66 "View Anssi Räisänen's GitHub profile"

<!-- Alan upstream repository ------------------------------------------------>

<!-- Lib v0.6.1 -->

[e002f20c]: https://bitbucket.org/alanif/alan/commits/e002f20c275e8429315580b8501d137750bd22de "View commit e002f20c of Alan repository on Bitbucket"

<!-- Lib v0.6.2 -->

[c44766fa]: https://bitbucket.org/alanif/alan/commits/c44766faea7539806a01fa6e8bee2c84fa0b2c36 "View commit c44766fa of Alan repository on Bitbucket"

<!-- Lib removed from Alan repo -->

[18c72f83]: https://bitbucket.org/alanif/alan/commits/18c72f8378ca59651a92b580265fd814a0965ab6 "View commit 18c72f83 of Alan repository on Bitbucket"

[last lib]: https://github.com/tajmone/alan/tree/c44766faea7539806a01fa6e8bee2c84fa0b2c36/lib
[last std]: https://github.com/tajmone/alan/blob/c44766faea7539806a01fa6e8bee2c84fa0b2c36/lib/std.i


<!-- EOF -->
Loading

0 comments on commit 8d8bbfc

Please sign in to comment.