Alan Interactive Fiction Development team.
Alan is a tool for creating works of Interactive Fiction, aka text adventures. It's a prose-like programming language that is easy to use.
Alan IF Documentation Project
Home Page: https://git.io/alan-docs
License: Other
Alan Interactive Fiction Development team.
Alan is a tool for creating works of Interactive Fiction, aka text adventures. It's a prose-like programming language that is easy to use.
@thoni56, I've finished porting and cleaning up 5. Running An Adventure, but it might require some text revision.
I've taken the liberty to polish up some sentences wherever I was certain that it wouldn't affect their meaning, but in some places there seems to be either a problem with terminology choice, or the sentences are a bit entangled are not very clear.
I've annoted all comments and proposals in lines that start with a "// @
" (eg: "// @TODO:
", "// @FIMXE:
", "// @NOTE:
", etc.), so sifting through the comments can easily be done via Search functionality.
Some revisions might be worth mentioning them here, while others are either self-explanatory notes or just some reminders for enhancements to the text that could be dealt with at any time in the future (jotting them down in th source code ensures that any contributor will see them).
In Sec. 5.2. Player Input it's stated:
A restriction placed on the player input by the interpreter is that the words the player is allowed to use can only contain alphanumeric characters, underscores and dash.
This point might be expanded upon, as it's a rather important one. Some problems emerge with the above sentence:
rock'n'roll
" or "Bob's cat
").?
" Question marks can't be defined as part of Syntax
definitions.where am I?
" and there is a defined syntax for "where am I
" (the StdLib contains it), will that extra ?
invalidate the whole input, or will it just be ignored and the input work?In some of the above considerations I'm trying to imagine the sort of questions which might go through the reader's mind, and can actually recall having asked them myself while starting with Alan. So, I thought that these questions belong to this section, for it's probably the chapter that a reader would consult when studying similar issues.
As for the valid characters ranges, I've actually had to peek at Alan source code to work out the exact ranges.
While working on the keywords list in Appendix D.2, I've noticed a couple of things:
actor
and location
are present, but not thing
, entity
and object
. Is it because the former are also pseudo-attributes and the latter not?Container
, Opaque
, on
, off
, etc. could be seen more like the built-in classes (ie, built-in pseudo attributes, as they at times called in the Manual). How should we case these? lowercase, like built-in classes?I've converted the original verbatim-styled block to a CVS-Table — IMO it looks nicer, and it's also easier to maintain, and the number of columns could be controlled via custom attributes, and be set differently in different formats (eg, for an ePub in an ebook reader 4 columns instad of 5 might be better).
The new "CONVENTIONS.md
" document contains the Formatting and Styling Conventions guidelines adopted in Alan-Docs.
This Issue tracks the status of the guidelines, as there are still many points not convered by the document (although already discussed in Issues). It also provides a thread for discussion on the topic of styling convention across Alan documentation.
...
)ALL
and AND
player input (where AND is not to be confused with the Alan keyword)All Issues on the topic are labelled as "styling conventions
".
@thoni56, I propose that Alan keywords in paragraphs get styles as inline code, whereas in the manual they are currently styled in bold.
Example:
Using the Syntax construct, you can also define more complex player input.
becomes:
Using the
Syntax
construct, you can also define more complex player input.
In computer related documentation, this is becoming a standard way of formatting keywords, code snippets and verbatim text related to the terminal; it looks better and it's more intuitive to the reader.
The problem is how to handle cases in which keywords are printed with their plural form, like in:
For this purpose, we use Locations.
which could be rendered as:
For this purpose, we use
Location
s.
... where the "s" of plurality directly follows the inline-code. (in AsciiDoc must be formated as ``Location``s
, with double backtick).
This is also seen frequently in documentation, although it might not look quite as nice. But in my opinion it visually reinforces the actual keywords spelling, and it also highlights how these are strictly related to natural language in their usage.
I'm not quite sure about their usage in headings though, as these tend to look bad in the final document — especially since many sections will contain keywords in their title, which would end up looking messy. So I'd rather exclude headings, and only apply inline-code styling to paragraphs, notes, and similar document elements.
So, if it's ok with you, I'd like to proceed and change all occurences of keywords in paragraphs (or other elements, except headings) from bold to inline code. I'd like to get these search-&-replaces tasks out of the way before starting to proofread the whole document, because once these are done with I'm going to split the document into multiple files (one for each chapter).
I've come across @darshandsoni's asciidoctor-skins, a collection of alternative stylesheets for the native Asciidoctor backend.
The styles are nice, and MIT licensed. Unfortunately there aren't any Sass sources, but we could easily port a stylesheet to SCSS if we find one that we'd like to use.
This is approach is preferable to having to tweak the asciidoctor-stylesheet-factory, which relies on an old version of Foundation and on Compass (which has reached EOF).
At this point, anything that could speed up work is welcome.
Add a Glossary to the ALAN Manual:
beta7-prep_glossary
, between last Appendix and Index (in file: manual_17.asciidoc
)README.md
to list new manual_17.asciidoc
source file.beta7-prep
branch, create a pull request (requirinh approval by @thoni56) and discuss further changes therein. Squashing into a single commit advised.NOTE — I propose squashing the Glossary into
beta7-prep
branch even with a single definition, for Alan beta7 is approching and there are lot's of clean up chores ahead of us, and it's better to get rid of dev branches as soon as they are feasable to go, to keep the workflow cleaner.
The current state of the Glossary can be viewed in the beta7-prep_glossary
branch:
manual_17.asciidoc
— Glossary source file.The need for a glossary at the end of the Alan Manual It has come up a number of times on the ALAN-IF Yahoo group.
We'll need a bunch of entries (and well polished definition) to make the effort worth its time — let's say, at least 10 entries. But the work on the Glossary can start right now, since all documentation edits are currently taking place in the beta7_prep
branch only, for the upcoming release.
The idea is to offer the reader a way to look-up any technical terms that he/she might have encountered in the course of the Manual.
From Asciidoctor Manual » §58. Glossary:
You can include a glossary of definitions by including the
[glossary]
marker before the section header and before the first definition.[glossary] == Glossary [glossary] mud:: wet, cold dirt rain:: water falling from the sky
Asciidoctor Glossary is supported also in the HTML backend.
As for the PDF backend (via DocBook → asciidoctor-fopub), it's really prickly about formatting, so extra care should be taken to ensure that the Glossary is rendered as expected in PDF — even if it might look fine in HTML, it could be completely broken in PDF!
Some useful online glossaries on programming terminology:
Ciao @thoni56,
In these days I've been doing some tests with syntax highlighting in the HTML5 backend (a bit slowed down by flue and fever).
There is an example extension to integrate André Simon's Highlight in Asciidoctor:
I've tested it and it works fine, but the sample extension doesn't yet handle callouts and custom substitutions, which is rather limiting for a documentation project.
Right now we don't use callouts in the Manual, but they would indeed be useful. But the Manual uses custom substitutions in syntax examples, and the Beginners' Guide relies heavily on them to assign custom colors to specific lines. So, I think we should look for a solution that supports all Asciidoctor features.
I don't know Ruby and have no experience with Asciidoctor's API, so I wouldn't know where to start editing the sample extension to make it support callouts.
Probably, at this point, the best solution is to create a new Alan syntax for another syntax highlighter.
Asciidoctor natively supports various syntax highlighter, but I was thinking of using either Rogue or Highlight.js.
Rouge has the advantage of producing standalone HTML5 docs, which don't require JavaScript at all. Some HTML based formats don't handle well JavaScript (e.g. CHM Help files) or they might target devices which don't support it at all (eBook readers, for ePub and Mobi/Kindle, etc.).
Besides, Rouge is to Ruby like Pygments is to Python, and we could say that it's the highlighter of choice with Asciidoctor.
Furthermore, it's the highlighter used by GitHub, so creating an Alan definition could ultimately lead to its syntax being highlighted on GitHub too (well, in theory at least, because for a file extensions to be registered on GitHub it must have a significant presence in the portal, but you can always declare it manually in Git attributes targeting GitHub linguist, and if Rouge supports the syntax it should get highlighted).
The downside of using Rouge is that I've never used it before, I don't know Ruby and it's a bit more complex than other highlighters. But this shouldn't be an obstacle, it might just require a bit more effort and time. I've already looked at examples and its documentation, and it seems doable.
I've already created Highlight syntaxes, and it's fairly simple to use. It's a bit strict when it comes to syntax elements naming conventions, and if you need to create a syntax defiinition that breaks those schemes it won't be included in the official distribution.
Highlight.js is lighteight and fast, and you can either link to its CDN or create a custom release with only the languages you need. Probably Alan isn't a general enough language to be included in the default distribution (or the CDN), but the website's download page allows you to create custom distributions in the browser.
Anyhow, I'll start experimenting with Rouge and Highlight.js, and will try to create an Alan syntax for Rouge (or both, maybe).
I'll post updates on this issue when I have some news or working examples.
Today I started looking into the reconstruction of the Index, but I've realized that there seem to be some problems in the original document.
In the PDF Manual's Index, the entries are not cliccable links (although the page numbers they refer to seem correct). I've looked into the ODT file, and I can't find any Index entry fields.
What was the original word processor used to create the ODT document? I'm using LibreOffice Writer to open the original doc, so it might be that some features are not supported.
I guess that I'll have to try and reconstruct the Index manually, by checking the Index entries and the page they point to, and working out myself where to place ADoc style Index anchors in the document.
Any suggestions on this?
Callouts in shell example blocks don't show up well due to reverse-video numbered circles having a black background color almost identical to that of the block background.
While in the HTML stylesheets it was easily solved by assigning to callouts numbers a yellow BG color, in the XSL stylesheets it doesn't look as easy.
The PDF template uses SVG image files to render the reverse-video circled numbers; although it's possible to customize the XSL settings to point to customized SVG images, this setting would affect all callouts — i.e. I haven't found a way to use different callout images depending on the block role.
Possible solutions to this problem:
(1)
) via the callout.graphics
setting (not very nice solution).NOTE — Currently, the only callouts used in the Alan Manual are actually in shell examples (App. F.1. Format of Messages). So, I could actually tweak the SVG icons colors, so they contrast a bit more with the shell scheme, but there are some cons to this approach:
- The SVG icons colors would also be used in the main text, where the callouts are expanded upon; so the chosen color would have to look good with the white background too.
- In the future we can foresee more usage of callouts in the Manual, in Alan code too; so, unless I can come up with a color that looks nice also in Alan code examples, I'll have to find another solution.
In the Manual, SCRIPTs need to be better explained.
For a start, the sections dealing with SCRIPT
/STEP
and Actor Statements (USE
/STOP
) are quite far apart to make it comfortable for the read to study the subject.
NOTE — In commit c2bd0b8 I've added some cross-refernce links on some keyowrds in those sections, to make it at least easy to quickly jump back-&-forth between the two sections.
Probably, a section should be dedicated to actor scripts in Ch. 6 Hints and Tips with more explanations and examples.
The topic is rather important one, and currently the Manual doesn't really get deep into it.
NOTE — I also suggest that the Hints and Tips chapter be renamed Tips and Tricks, which is more commonly used in these contexts.
The section on STEPs is not very clear. Mainly, both the BNF rules and the description of the valid expressions is too vague:
step = 'STEP' {statement}
| 'STEP' 'AFTER' expression {statement}
| 'STEP' 'WAIT' 'UNTIL' expression {statement}
The text says:
A step can be defined to be executed immediately, at the next move, to wait a number of moves before it’s executed or even to wait for a special situation (condition) to arise.
But it doesn't quite clearly associate these possibilities which the rule variants. Spelling it out in a list might be better:
A step can be defined to be executed:
- immediately (
STEP {statement}
),- at the next move (
STEP 'AFTER 1
),- to wait a number of moves before it’s executed (e.g.
STEP 'AFTER 3
)- or even to wait for a special situation (condition) to arise.
The last point is the less clear, for when I tried complex expressions like checking that an attribute was equal to a certain value I'd get compiler errors stating that the expression in this context must be boolean. All expression should ultimately result in a false/true statement, so lacking examples I'm not sure how the last point might be fully used.
As for the code example:
Step After ticksLeft Of train
"The train driver enters the train, and after a brief
moment the train starts to move."
I find it ambiguos, for I'd intuitively think that ticksLeft
would be of integer type. Maybe using more explicit attribute names and adding comments to the examples would help the newbie reader.
But I think that overall this section could do with a couple of more examples and explanatory text (even in view of creating a dedicated section for scripted actors in Hints and Tips).
Currently there are no build scripts for the Alan IDE Guide, just the ADoc source file and the prebuilt PDF.
All documents should have automated building scripts in order to allow easier maintainance when changing the templates or updating the software of the toolchains.
As suggested by Jürgen on Alan Yahoo!, update the ARun and compiler swtiches
-v
opt (from version to verbose).-l
.-c
.-n
.-i
.-r
.This issue tracks (and discusses) the status of metadata and other book info for the Alan Manual document header:
:doctitle:
— The ALAN Adventure Language Reference Manual:description:
???:keywords:
???:author:
???:email:
???These links point to the dev-man
branch, and will work even after force-pushing to the PR:
NOTE — some of the header entries will also be useful elsewhere, eg, in the [Colophon] or eBook metadata in formats like ePub, Mobi, etc.; therefore it would be a good idea to employ user defined attributes to store some book-related strings and info that could then be referenced in various places.
Metadata is useful in terms of SEO when creating HTML online pages, and with eBooks it improves indexing them in ebook stores, as well as in an eBook Reader device's indexing.
UPDATED: Asciidoctor-fopub is now being used in the project!
We need to work out a reliable way to convert the documentation to PDF.
So far, I've experimented with the following methods, but stumbled into problems which make the unsuitable for the task at hand:
If anyone has some advise on which would be the best way to convert the Alan documents to PDF while preserving the styles of the original ODT/PDF documents, any suggestions and help are much appreciated!
Asciidoctor Highlight.js
We should take a look at @jirutka's Asciidoctor Highlight.js extension for it allows to use HLJS at convert time and free the final document from the need of loading HLJS package — thus making the docs truely portable to any HTML based format, including CHM, ePub, Mobi/Kindle, etc.
This project provides an Asciidoctor.js extension for highlighting source listing blocks using highlight.js right during document conversion (instead of in browser on client-side as the built-in highlight.js support).
It supports all Asciidoctor features such as callouts, passthroughs inside a code and all other substitutions, except highlighting of specified lines (attribute
highlight
).
This is an Asciidoctor.js extension, so it would require an alternative toolchain to the Ruby version, which might preclude using other Ruby-only extensions (not really sure of the implications). We might still rely on this for specific formats like CHM, etc.
Local tests and more digging are required, and this thread will be used to aggregate notes, links and discussions on evaluating the pros and cons of this alternative approach.
Task list and progress status of customization of syntax highlighting in PDF documents.
alan-hl.xml
").NOTE — asciidoctor-fopub uses Apache™ FOP to convert from DocBook to PDF, and XSLTHL for syntax highlighting source code (for more info, see the XSLTHL Wiki).
@thoni56, in Appendix G: Localization there are three sections which have a title but then a "TBD" note instead of section contents:
Shouldn't we comment them (title and all) out so that they don't show up in the actual document but only in the AsciiDoc source? or would you rather keep them visible for some reason.
Also, I'll be creating an Issue for each one of them, just to keep the project's TODOs organized, regardless of who and when they get actaully written (they are pending tasks after all, so they deserve an Issue so that they can show up in the projects' dashboard).
Then, assigning these TODO Issues to one of us would be also be a good idea (again, to keep track of who will be doing what).
I could have a go at G.3. Player words, which I think I can handle, but the other two's scope is beyond my competence, so I'd assign them to you (again, no deadline attached).
Do you agree on this approach? I.e. is it OK if I just assign to you those tasks which I think need to be done and which are beyond my competence? Instead of nagging you with messages, when something is not urgent assigning it to you should be enough, then it will show up when you query open issues using asignment filters. For the urgent staff I can always nag you with the @thoni56
bell ringer 😉.
None of these are blocking issues in regards to publishing the new Manual version as an official replacement of the original ODT/PDF — these TBDs have been there for a while anyhow, but commenting them out in the source might make the final doc look better.
As you might have noticed, in these days I've cleaned up the various loose Issues and started to use the Project dashboard to organize the various subproject of this repository, so that the various tasks are easy to track.
I've also enabled some of the automatic features of the dashboard that keep track of Issues references in commits to automatically update the dashboard.
These features are quite cool and make it easier to work collaboratively, especially on the long term.
Appendix G: Localization, section G.5. Word order (links to master
).
Marked as TBD in original Manual:
Text about how the rigid word order (verb first, possibly prefixed with a noun) that Alan imposes. Or does it? With the noun first is it possible to implement “das buch nehmen” with the syntax
take = (o) nehmen
?
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:
design.doc
ACTORS_IN_CONTAINERS.md
Alan Transitivity.mm
rules.rtf
which, by the way, are a quite useful reference when learning.
alan-design/
FolderI 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.
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.
This issue tracks and discusses porting the Alan Begineer's Guide Asciidoc. The source file still needs cleaning up and adapting to the project's styling convention and resources.
NOTE — This document is currently unassigned and if any volunteer wants to take it on hes/she's most welcome to do so.
@thoni56, I have a few questions about the literal class and its subclasses.
The manual could be expanded a bit on this topic, especially by providing exmaples. So, I'll expose here my doubts and questions about them, and if you can help me cllarify the topic I could then try to edit the Manual accordingly (in a separate branch).
One of the things that initially puzzled me most on literals is that while they all belong to the predefined classes not all of them have corresponding keywords:
As a matter a fact, I propose to change the image of the above diagram to use color and style to provide further information:
For, if I've understood correctly, while you can ADD TO
the string class, you can't do that on literal and integer.
The diagram is shown in Ch.2's The Predefined Classes, and adding the proposed color/style changes, and a description of their meaning in the image's caption, could help new users memorize better the base classes.
This is a first draft I was working on (but here I used red borders instead of italics for non-keyword classes):
But I think that using italics instead of red borders is better (especially for a printable version, where the dark red would be lost in print).
What do you think about the classes diagram tweaks? Should we use in the Manual?
(the image above is just a draft, I'll create a good SVG image).
In various places I have problems when it comes to styling literals, since they are not Alan keywords in the strict sense I haven't styled them as inline code
, but as bold. The problem is that when the text mentions all the predefined classes it becomes a mixture of inline-code and bold styles:
In Ch.2's The Predefined Classes I haven't yet decide how to style this paragraph, and just left all classes in bold in this context:
They are entity, thing, location, actor, object, literal, string and integer and have the relationship, inheritance tree, shown in the figure above.
... because if I were to follow strictly the conventions, it would like a bit hugly:
They are
entity
,thing
,location
,actor
,object
, literal,string
and integer and have the relationship, inheritance tree, shown in the figure above.
I think that styling convention should make like easier to the reader, but in some contexts we should also consider text elegance. As a general rule, when a keyword occurs multiple times in a paragraph, I only style it as inline code in its first occurence, or in those places where it's important to underline that we're dealing with the keyword, not just the general concept. Wherever the context is obvious, or when the keyword and its noun counterpart in the natural language overlap, I prefer not to use styles.
But in the above list of native classes, distinguishing between classes that have and don't have a keyword counterpart might actually help the reader, who might otherwise try to use ADD TO
with literal
and integer
— here, styling them in bold will make them contrast with the other classes, although I admit it looks hugly.
Any suggestions on this?
The problem in the manual is that section 3.6. Instances/Literals is vague on the topic:
The classes literal, string and integer cannot be instantiated explicitly. Instead, you might say that they are implicitly instantiated when the player inputs a literal. For example:
[...]
It is possible to add
Verb
s to literal and its sub-classes. This way it is possible to create verbs that take strings and integers as parameters.
The last sentece really confuses me. Some examples here (or elsewhere, and just add a cross reference here) would help, otherwise the reader/learner is left with huge question mark floating in his head.
I've seen examples of verb additions to the string class (in the StdLib), but the above sentence clearly states that they can be added "to literal and its sub-classes".
Could you help me understand better this point?
I think that it's worth adding to the manual a couple of examples right after that sentence. So far, I can't recall finding in the manual practical examples on literal classes, but I might be wrong on this.
I propose that we agree on some code styling conventions for both the manual and other Alan related documents, so that they look consistent in style.
I think that code examples would be more readable if Alan keywords and built-in classes were in all caps, as it helps distinguish between custom created classes, instances and attributes, versus that which is hard-coded into the language. Currently, first-letter caps styling is being used in the manual.
Example:
Every door Isa object
Has otherside door.
End Every door.
Every lockable_door Isa door.
Has otherside lockable_door.
End Every lockable_door.
The someDoor Isa door
Has otherside someLockableDoor.
End The someDoor.
The someLockableDoor Isa lockable_door
Has otherside someDoor.
End The someLockableDoor.
... would become:
EVERY door ISA OBJECT
HAS otherside door.
END EVERY door.
EVERY lockable_door ISA door.
HAS otherside lockable_door.
END EVERY lockable_door.
THE someDoor ISA door
HAS otherside someLockableDoor.
END THE someDoor.
THE someLockableDoor ISA lockable_door
HAS otherside someDoor.
END THE someLockableDoor.
Although syntax highlighting is going to mitigate the issue by enforcing special colors to keywords and built-in classes, I nevertheless think that it looks more intuitive for the reader.
Possibly, ISA
could be capitalized as IsA
, for readability sake, but the other keywords should be all-caps:
EVERY door IsA OBJECT
HAS otherside door.
END EVERY door.
EVERY lockable_door IsA door.
HAS otherside lockable_door.
END EVERY lockable_door.
THE someDoor IsA door
HAS otherside someLockableDoor.
END THE someDoor.
THE someLockableDoor IsA lockable_door
HAS otherside someDoor.
END THE someLockableDoor.
For consistency sake, I'd also style as all caps keywords within paragraphs and other document elements, including headings-titles.
As mentioned in Issue #1, I propose to apply inline-code styling to keywords in paragraphs, but not in headings; but I think they should be at least all-caps in headings, as this will make them stand out in the TOC.
So, reusing the examples from Issue #1:
Using the Syntax construct, you can also define more complex player input.
For this purpose, we use Locations.
would become:
Using the
SYNTAX
construct, you can also define more complex player input.For this purpose, we use
LOCATION
s.
I'd apply the same principle to EBNF blocks (which is already the case, more or less):
forms = indefinite | definite | negative
definite = 'DEFINITE' article_or_form
indefinite = [ 'INDEFINITE' ] article_or_form
negative = 'NEGATIVE' article_or_form
article_or_form = 'ARTICLE' {statement}
| 'FORM' {statement}
Although the above styling is not applied to every EBNF block, it seems like this was the preferred styling for EBNF, allowing to easily distinguish between actual keywords and more abstract elements of the syntax.
Here, I'd simply enforce the same styling on all EBNF blocks in the manual.
Robert deFord has written an excellent guide to setup and use the AlanIDE. On my recommendation it was the first documentation to startout as an AsciiDoc.
Robert has kindly stated "it is not copyrighted", but we might need to figure out how to formulate that so that it resonates with the other Alan docs.
Update the highlight-treeprocessor.rb
extension to add support for callouts in Highlight extension, so that Highlight can be used instead of Highlight.js for syntax highlighting HTML-based backends.
This is prefarable to using Hihglight.js for it allows static syntax highlighting, easier usage of custom syntaxes, and because Highlight offers more options to customize results.
For more info, see #99:
Although optional, we could add an EBNF syntax highlighting definition, just to add some color to BNF rules (nothing dramatic, just slight shades variations of the base color).
NOTE — The rules in the Alan Manual actually use EBNF notation (not BNF), so I should change the
source
language toebnf
to correctly support the syntax definition, especially since other HTML highligthers ship with both BNF and EBNF definitions, and having the wrong lang definition might cause problems.
source
blocks.beta7-prep
, commit fb899b9. Issue will auto-close when merged into master.As discussed on Alan IF Yahoo list, the BNF rule for Addition in §3.8. Additions should be edited and the [inheritance]
part removed:
addition = 'ADD' 'TO' 'EVERY' id
[inheritance]
{property}
'END' 'ADD' ['TO'] [id] '.'
Although the above BNF rule matches the real BNF used in the ALAN source code, it only creates confusion in the reader since no inheritance can actually be specified with ADD
.
Add to all HTML conversion scripts the following Asciidoctor settings attributes:
-a reproducible
— don't add last-updated date in HTML footer, to prevent spurious changes in Git when building unchanged docs.-a sectanchors
— adds an anchor in front of the section title when the mouse cursor hovers over it.Some Unicode characters used in the Manual are not being represented well in the PDF version. This issue should track all the characters and where they appear in the Manual, until a solution has been found to represent them correctly in both the HTML and PDF output.
The adopted solution is going to use custom attributes for characters substitutions, which are defined conditionally via ifdef::
directives targetting the different backends with different substitutions.
Currently the only reason why we are not using Highlight for the Alan Manual is because it uses callouts in a few places, which are not yet supported in the Highlight extension for Asciidoctor.
See Issue #36 for more details on the problem.
IMPORTANT! — See also proposal #107 to switch to Rouge instead!
IMPORTANT!—If we switch to Highlight, we need to check for the presence of code blocks with an indented 1st line, and apply the fixes of #70.EDITED — This problem was fixed at the template level, in commit aa8fb65.
EDITED — The above information is actually incorrect! The Manual currently only uses callouts in App. F.1. Format of Messages, for a shell/CMD literal block, which is not being syntax highlighted!
So we could simply switch to Highlight at any moment, without breaking the document. This would allow us to have syntax highlighted code in the HTML Live Preview link, which is currently used by ALAN website to direct end users to the online manual.
Of course, after the switch to the Asciidoctor format we were hoping to use callouts freely in the Manual, for they are great references for commenting the code examples in a clean way. But in the meantime, while awaiting to a switch to the Rogue highlighter, we could just switch temporarily to Highlight, so that:
The Live HTML Preview will be syntax colored. (no longer applies now that we have a real website!)- We can benefit from static highlighting for better HTML chunking (sse #78).
@jirutka's asciidoctor-html5s backend (Ruby) looks promising for creating better HTML5 docs (especially for executable eBooks):
This project provides alternative HTML5 converter (backend) for Asciidoctor that focuses on correct semantics, accessibility and compatibility with common typographic CSS styles.
Local tests and more digging are required, and this thread will be used to aggregate notes, further links and discussions on evaluating the pros and cons, and if there are potential pitfall in interactions with other extensions.
The creation of custom DocBook XSL Stylesheets to provide the required/desired styling to the PDF Alan Manual is a milestone for the public release of the new ADoc version of the manual.
Sample documents with extended features tests are available in the _dev/styles-tests/
folder:
Also, some PDF related issues have to be dealt with. Here is a task list of the WIP status:
role
s:
"commentary"
role: add left margin.Please, add any comments about missing styles that need to be handled, current styles that need fixing, and ideas to improve the Manual layout. They will be added to the tasks list.
This issues tracks the status of required/missing assets for the Alan Manual.
Although not strictly necessary, game and debugging transcripts could be maintained by adding a source adventure and a commands script (aka, solution file) in order to automatically generated transcript files — which could then be included into the document via include
directives.
This approach might have some added benefits in terms of maintainance, especially for debugging and -h
output, as it would allow always showing the output of the latest compiler/interpreter versions.
But the generated transcript will need some styling (bold, italic) before it can be included into the Manual, in order to comply with the styling conventions.
Maybe, the styling problem could actually be worked around by customizing the source adventure to include AsciiDoc formatting markup in name locations (eg, *Kitchen*
); but styling the player input in italics would still need to be done via RegExs substitutions on the final transcript (at the most, the prompt could be set to "> _
", to initiate italics, but I can't think of any way to add the closing _
at the end of the input line via the adventure itself).
Another solution might be to create an ad hoc syntax definition for Highlight, which would then automatically style transcripts via syntax highlighting (like I've done in Sublime Alan, with the Alan Transcript syntax). This solution wouldn't require usage of any AsciiDoc markup formatting in the transcripts.
beta7-prep-contributing
→ dev-contributing
.dev-contributing
on master
.CONTRIBUTING.md
to embody the new branches strategy (see discussion below).manual/CONTRIBUTING.md
to describe the new branches naming conventions and development and release strategies for official Manual release and Alpha dev/previews (see discussion below).Currently working on the following documents on branch dev-contributing
:
See also:
CONTRIBUTING.md
(on master
branch)Ciao @thoni56,
I wanted to ask you about the way new contents should be proposed for the Manual (and any other doc in general). If it's OK with you, I was thinking that new content should be proposed in separate branches (created ad hoc for each new content submission), so there is a chance for you (or whoever will be appointed to supervise the documentation project) to discuss, revise, edit and approve (or reject) new contents.
Unlike fixing of typos and other minor changes, new contents are a bit of a delicate matter, and I think their addition should be supervised. This branch-based approach, on the other hand, allows freedom to anyone to at least propose contents vi pull requests. As for those with full access to the repository (like me), it boils down to separating what is editing work and contents changes.
For example, I feel I could write some contents on the internationalization/localization of Alan, since I'm fresh from the library translation, but I'd prefer to work on a separate branch where there is space to discuss and revise all the proposed contents before merging them.
What do you think about this?
Possibly in Chapter 2, but maybe also where the concepts are introduced/used.
This issue tracks and discusses choosing fonts for the PDF template:
When choosing a font for the PDF template, we need to check that the following criteria are met:
=>
) — need to check this!These are the fonts currently used in the Manual:
Use of italics in the above list indicates that the font should be available in the preinstalled fonts of most OSs.
@thoni56, as you can see I've started rebuilding all the cross references lost during conversion.
I need to point out a few things here:
Often in the original manual those references also mentioned the page number, but I have dropped that in the AsciiDoc version since in many formats the page number would become meaningless (like web pages) or relatively difficult to reference (like ePubs).
I've opted to use references that alway point to the section number, instead of its title. For example:
becomes:
Except in some edge cases where I realized that showing the section title instead of its number was more appropriate.
Unfortunately, it seems that in AsciiDoc the cross-reference link text is either autogenerated or custom-set — but it doesn't seem possible to mix the two, or at least I haven't found a way to do it in the documentation (ie, some macros to produce the section or page number of the linked reference in custom text).
I believe that this is the best system in terms of maintainance, for it requires only to reference the chapter/section title, and AsciiDoc will substitute it with the section number at build time. When chapters are referenced, the chapter title is shown along with its number, though; but sections are shown only as numbers.
It's possibile to have a degree of control on how this is handled via project settings:
... and this could be set differently for PDF conversion and HTML docs, for example (ie, how verbose a cross-reference should be printed out).
But I think that it would be a good idea to adopt the AsciiDoc standard way of handling cross references (as I've done with Chapters 1 and 2), as these tend to work well in multiple output formats, and are easy to maintain through collaborative editing.
Of course, the advent of eBooks has changed many book paging conventions, and avoiding references to page numbers is one of them — now publishers usually want a book to look good both in paper and digital format, and this obviously requires a compromise between the two.
Please, when you have time, have a look at the rebuilt cross-refs in Ch1 and Ch2, and let me know what you think about them.
Switch all HTML documents in the project from using highlight.js to Highlight:
NOTE — The Alan IDE Reference Guide is only available in PDF right now.
IMPORTANT! — See also proposal #107 to switch to Rouge instead!
Appendix G: Localization, section G.3. Player words.
Marked as TBD in original Manual.
Live preview from dev-man
:
dev-man
)Currently the are no impediments for not using Highlight for the Alan Author's Guide, for it doesn't it uses callouts anywhere (these being what prevents using Highlight with Asciidoctor — See #36 on this).
So, since this book is still in the making, the question really boils down to whether we are planning to use callouts or not in it! Callouts are indeed a cool feature, especially in these type of documents which contain lots of code examples, for they introduce a nice notes-like system for source code.
Eventually, the Highlight extension will support callouts, but right now it doesn't. Should we just keep using Highlight.js, and enjoy callouts? Or should we rather switch to Highlight and postpone using callouts in the book until they are supported?
It's a matter of choosing which one should get the priority: the highlighter toolchain or the callouts feature?
Since this is Thomas's book, the choise belongs to him really...
IMPORTANT! — See also proposal #107 to switch to Rouge instead!
There is a very preliminary Author's Guide in the source (in Writing.odt) uploaded to website under Development Snapshots, perhaps somethings in it might be valuable. We should look through that and save what's valuable before removing it from the source tree and uploads.
The contents of the Appendices documenting Alan compiler and ARun switches need to be checked over so that they match the latest switches of Beta7 when it's out.
(all preview links below point to dev-man
branch!)
-vesion
switch-vesion
switch-h
for -help
is supported (although non mentioned in help)NOTE — The ported ODT Manual was updated to Alan beta5, although some manual editing has occured after beta6 was released. See #32 for more info on those updates.
@thoni56 I was thinking of moving the xsl-fopub/
folder to a repository of its own and the include it back as a Git submodule.
The reason for this is that other Alan related projects like Anssi's StdLib (and, eventually, also my Alan Italian project) will need the AsciiDoc fopub template to build their documentation in PDF.
Since the StdLib repo dynamically compiles source adventures and generates transcripts to import into the documentation sources, they need to keep the documentation together with the library sources. So, moving the StdLib documentation to this repository is not a viable option for practical reasons (besides, keeping everything together is better for maintainance purposes).
Moving the Alan AsciiDoc PDF template to a standalone repository would allow any Alan related project to benefit from it without having to manually import it, which would also prevent having multiple copies of the template. The obvious benefits would be that any updates to the template repository could be automatically integrated by moving the Git submodule pointer.
Would that be OK with you?
If yes, I'd create the new repository under the Alan-IF organization.
Appendix G: Localization, section G.4. Word variations.
Marked as TBD in original Manual:
Text about using multiple names for the same objects & synonyms, and how the interpreter chooses which word to use when [sic]
Tweak the default CSS stylesheets to provide the required/desired styling to the HTML Alan Manual is a milestone for the public release of the new ADoc version of the manual. Here is a task list of the WIP status:
role
s:
"commentary"
role: add left margin.Custom CSS overrides are handled in Highlight.js' CSS (using Sass) since it's already included in the document by default. Easy solution, fine results.
Please, add any comments about missing styles that need to be handled, current styles that need fixing, and ideas to improve the Manual layout. They will be added to the tasks list.
In a mail conversation in [alan-if] Tristano asked about how Add works and how you can use that wrt. inheritance. Here are some highlights
One thing I don't know anything about, and is curious about, is graphical styling. In a sense, all AsciiDOC documents look the same. What are the possibilities of graphically styling the document? I'm thinking about typeface, page headers and other graphical elements, e.g. like what the DOC version of the manual now has.
Not that we need to exactly replicate the DOC, but curious, not only for this project, about the possibilities.
Ciao @thoni56,
in the Alan Manual, §3.11. VERBs » Controlling Execution with Qualifiers, it says:
So in short (with base class definitions of the outermost location being the outermost and the instance bound to the last syntax parameter the innermost):
- From the outside in, find any
Before
orOnly
definitions and execute them (stop ifOnly
found).- From the inside out, execute any definitions not already executed and not declared with the
After
qualifier.- Execute the remaining verb definitions (those with an
After
qualifier) from the outside in.
This part of the Manual has always confused me and seems wrong. If you look at the text that precedes the above statement, just a couple of paragraphs before:
First, starting at the "innermost" according to the table above, the verb in the last parameter (if any) is investigated and, if any of its (inherited) verb bodies have the
Before
orOnly
qualifier it is executed. If the qualifier wasOnly
then execution is also aborted at this stage and no more verb definitions are examined, otherwise the other parameters are examined in the same way.
... it seems to contradict the previous "in short" list, and that in the above list "outside in" and "indise out" should be swapped in all three list items.
Could please check that section and confirm if the above (and the text preceeding it) are correct.
Thanks
@thoni56 , while editing the Alan Manual I've noticed that sometimes it follows British conventions, other times American conventions. This is probably the result of different people editing the document.
I'm often not sure which convention to follow (e.g., using a comma after i.e. and e.g., or not), and whenever I need to lookup some grammar or spelling issue (which is rather frequent) I often come across different answers for UK and USA English. This also affects the setting of spell-checking tools, which are quite useful in keeping track of spelling typos and could also ensure that spelling follows either the UK or USA English conventions.
Establishing which English the Manual follows would be a good idea, and we could add it to the guidelines.
What to do you suggest, UK or USA?
Admonition blocks could be graphically improved.
As previously discussed in #15, the Manual lacks examples on literal classes, specifically regarding additions.
I suggest adding the following examples, maybe under Section 3.8. Additions, and then add a note with cross-references in Section 3.6 Instances » Literals to them (as additions are a more advanced topic in that place):
literal
string
integer
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.