search

alan-if / alan-docs

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

Adding Alan Design Docs #33

Closed tajmone closed 3 years ago

tajmone commented 5 years ago

Ciao @Thoni56,

Whenever bug issues pop up in the Yahoo! group, I notice that it often follows a discussion on Alan internals. As far as these internals are concerned, currently the only documents available are those in the doc/design/ folder of the repository:

which, by the way, are a quite useful reference when learning.

Adding Them to alan-design/ Folder

I was thinking that it might be a good idea to include them in this project, and convert them to AsciiDoc — except Alan Transitivity.mm which is a mind-map, but we could use it to grab some screenshot to illustrate the documentation, as these would provide a nice visual aid to topics.

I'm aware that some of these docs are still drafty, but porting them to ADoc would allow future editing to be inline with the new documentation system.

We could introduce them as a set of independent articles, inside a dedicated folder (e.g. alan-design/), and in the future they could eventually become chapters of a book in its own right. The alan-design/ folder could collect various articles on the inner workings of Alan, and other tech stuff.

Since they are rather short documents, their conversion won't take me more than an hour.

Amachine Specs

I was also hoping that the Amachine specs might be documented at some point. Now and then I study Alan's source code, hoping to manage to get a bird's-eye view of the general design picture, so I can eventually start to experiment with it and (hopefully) also contribute to the code in the future.

But I haven't yet managed to figure out where to start from, there are so many source files that it's difficult to get a grip on what belongs where.

For example, I'm still strugling to understand how the Amaching operates, i.e. if it's a sort of VM (like Glulx and TADS VM) with its own set of opcodes and memory management, or if it's just a binary program that processes the input adventure. Other design aspects I'd like to learn more about regard the separation between Alan compiler and the interpreter, and what is hardcoded in adventure files and what in the terp (for example, by studying the source I discovered that the QUIT code, questions and text are hardcoded in the terp).

Having a dedicated folder in the project could help toward that direction, and even if these are draft documents they could be very useful nonetheless, especially to anyone wishing to approach Alan source code from scratch.

tajmone commented 5 years ago

Done: Added

The above mentioned docs are now available in the Beta7 branch, inside the xtra-docs/ folder (See Issue #48, commit 74fea67fe59).

We now only need to decide:

IMO, it would be good to keep them here, to centralize development of any Alan-related docs and to free the Alan source repository from documentation work.

Ultimately, I chose xtra-docs/ as the folder name, instead of the initial proposal of alan-design/, for it seemed a better catch-all choice for a temporary folder that can host all sorts of incomplete documents. But of course, we can still change the name.

thoni56 commented 5 years ago

I think alan-design is a good name. Only drawback I see is that it might be taken as an indication of final/true documentation. So provided that we clearly state the flux they are in, I'd suggest going for alan-design.

tajmone commented 5 years ago

Done!

Only drawback I see is that it might be taken as an indication of final/true documentation. So provided that we clearly state the flux they are in, I'd suggest going for alan-design.

I wouldn't worry about that, for all documents ready for consumption are clearly listed at the beginning of the main README.

Besides, once the Manual is officially ready for publication, we'll start to focus on deploying it on the Internet via GitHub Pages (from docs/ folder, or otherwise). So, ultimately, it should be clear that documents will be published online as they are ready, and that the repository hosts both WIP documents as well as ready-to-use ones.

But any improvements in the README to better clarify this division between ready and WIP documents are of course welcome.

tajmone commented 5 years ago

Merge Into Master?

Currently the Alan-Design docs are only available on the Beta7 dev branch (didn't want to create a new branch just for them), but if you're happy with them I could cherry-pick their commits (or just check out their folder from the dev branch into master) so they become available in master (not sure how long it will be before Beta7 gets merged into master).