• Rename branch beta7-prep-contributing → dev-contributing.
• Rebase dev-contributing on master.
• Update CONTRIBUTING.md to embody the new branches strategy (see discussion below).
• Update 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:

• CONTRIBUTING.md
• manual/CONTRIBUTING.md

See also:

• CONTRIBUTING.md (on master branch)
• Issue #59 — discussion on ALAN Manual branches strategy for Beta vs Alpha.
• Issue #71 — considerations on branching, merging/squashing, and committing strategies .

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?

@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?

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:

• Customize HTML stylesheets:
  • Customize Verbatim blocks (colors and styles):
    • Alan code examples
    • BNF rules (currently orange, like original).
    • Game transcripts
      • Decide color scheme (currently blue).
    • Shell output (use new Windows CMD modern colors).
      • Make callouts discs' BG yellow.
  • Fix mockup sample blocks in § 2.4 Notation via roles:
    • Alan code notation sample
    • BNF rules notation sample
    • Game transcripts notation sample
  • Paragraphs with "commentary" role: add left margin.
    (These appear below verbatim compiler output, as commentaries, eg in App C. Run-Time Messages)
• (more issues expected soon...)

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.

As suggested by Jürgen on Alan Yahoo!, update the ARun and compiler swtiches

• A.2. Compiler Switches
  • Add missing switches. NO! The text clearly says these are just examples, not the full list. The missing switches are only advanced sub-options.
  • Add verbatim copy help text? NO! it would be redundant, not important.
• A.4. Interpreter Switches:
  • Amend -v opt (from version to verbose).
  • Add missing switches:
    • -l.
    • -c.
    • -n.
    • -i.
    • -r.
  • Add verbatim copy help text? NO! it would be redundant, not important.

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:

• Asciidoctor PDF backend.
• pandoc — via DocBook to ODT conversion

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!

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.

@thoni56, in Appendix G: Localization there are three sections which have a title but then a "TBD" note instead of section contents:

• G.3. Player words
• G.4. Word variations
• G.5. Word order

Comment Out TBDs?

• comment out TBDs

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.

Create Issues to Tracks TODOs

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).

• create issue for G.3 TBD
• create issue for G.4 TBD
• create issue for G.5 TBD

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.3. Player words.

Marked as TBD in original Manual.

Live preview from dev-man:

• §G.3. Player words (dev-man)

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.

• Styles & Formatting
  • Alan Code
    • Code Examples Blocks (see Issue #2)
      • keywords casing: capitalized
      • predefined classes casing: lowercase
      • code truncation (...)
    • Inline code (see Issue #1)
  • BNF Definitions (see Issue #2)
  • Game Transcipts
  • Player input (inline)
    • ALL and AND player input (where AND is not to be confused with the Alan keyword)
  • The Index
    • keywords casing: all-caps (see Issue #5)
• Language
  • Use UK English in spelling conventions, abbreviations, etc.

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 Locations.

... 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).

This issues tracks the status of required/missing assets for the Alan Manual.

Images and Illustrations

• Add missing images:
  • Alan logo (cover/preabmle) — the logo was reconstructed as a vector image to allow lossyless scaling.
  • Figure 1 (Ch.2, p.20 of PDF) — "The principles for and relations between a game description, a compiler, a game file and the interpreter"
  • Figure 2 (Ch.2, p.33 of PDF) — "Relationships between the pre-defined classes.". Rebuilt in SVG using Dia Diagram Editor.

Transcripts

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.

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

• the manual indicates that you can Add , you probably cannot and possibly also should not
• there is no explanation was Add actually does, it should at least say something like "adding like as if you had written that in the class declaration directly, and adds in the same way as inheriting does"
• possibly give an example that explains that the clauses in the Add construct is just as if you had written them on the class
• describe that you can test for the Container property using "IsA"

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 to ebnf 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.

• Create custom language definitions fo XSLTHL:
  • EBNF.
• Manual AsciiDoc source: Change BNF to EBNF in source blocks.

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.

@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).

Classes and Keywords

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:

• Yellow BG for inheritable classes (entity, thing, location, object, actor)
• Grey BG for non-inheritable classes (literal, string, integer)
• italics for classes whose name is not a keyword (literal, integer)

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).

Styling Issues

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?

Examples Needed

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 Verbs 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.

While working on the keywords list in Appendix D.2, I've noticed a couple of things:

• The built-in classes actor and location are present, but not thing, entity and object. Is it because the former are also pseudo-attributes and the latter not?
• Some keywords like 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).

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.

• Polish the ported AsciiDoc source.
• Adapt document to Styling Conventions of this project.

NOTE — This document is currently unassigned and if any volunteer wants to take it on hes/she's most welcome to do so.

@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:

1. 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).

2. I've opted to use references that alway point to the section number, instead of its title. For example:

   • "see also Run-time Contexts on page 164"

   becomes:

   • "see also Section 5.3"

   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:

• https://asciidoctor.org/docs/user-manual/#customizing-the-cross-reference-text

... 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:

• Alan Author's Guide — See #51 for more info.
• Alan Manual — See #50 for more info.
• Alan 3 Beginner's Guide

NOTE — The Alan IDE Reference Guide is only available in PDF right now.

IMPORTANT! — See also proposal #107 to switch to Rouge instead!

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.

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.

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!

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.

Add Section on Actor Scripts in 6. Hints and Tips

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.

Improve STEPs

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).

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:

• asciidoctor/asciidoctor-extensions-lab#99

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.

• Create subdirectory for it
• Add sources
• Add generated PDF (Maybe? Do we do this? @tajmone

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.

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):

• Example of addition to literal
• Example of addition to string
• Example of addition to integer

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:

1. The Live HTML Preview will be syntax colored. (no longer applies now that we have a real website!)
2. We can benefit from static highlighting for better HTML chunking (sse #78).

@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).

Player Words and Allowed Chars

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:

• "alphanumeric characters" is rather vague as it could imply different characters ranges in different contexts (like in RegExs, for example), and often this definition includes the underscore, which would make redundant mentioning it separately. Futhermore, Alan accepts as valid words chars all letters supported in the encoding of the adventure, which would include also letters with accents, diacritics, etc., which usually don't fall under the "alphanumeric" category (even in RegEx engines, the term doesn't always include non-Ascii letters).
  • I'd rather use "letters and numbers" here
  • then mention somwhere that all letters supported in the encoding (ISO-8859-1 or others) are valid.
• The "dash" is rather confusing, as usually it's understood as either the en- or em-dash, which are not valid input in Alan as far as I know. Probably "hyphen" would be clearer. I can't actually recall using a dash or hyphen in player input. Any examples?
• Single quotes are not mentioned, but instances might include them in their name (eg: "rock'n'roll" or "Bob's cat").
• Double quotes and Strings-input is not mentioned either, and it might be worth at least mention it in an admonition note, if not in the paragraph itself. This would be a good place to either entertain a full explanation of how string input is seen by the parser, or to provide a cross-reference link to where the Manual discusses it.
  • Also, if I'm not mistaken, the range of valid characters inside a quoted string input is wider that the one of plain word inputs. Is it so?
• Although this specific paragraph focuses on the words of player input, the general context is that of player input, so it might be worth entering into more details (if not in this paragraph, in a dedicated one) about the use of punctuation and which punctuation chars are valid to the parser.
  • "?" Question marks can't be defined as part of Syntax definitions.
  • How does the parser handle the presence of unsupported chars? For example, if the player types "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.

Currently there are no build scripts for the Alan IDE Guide, just the ADoc source file and the prebuilt PDF.

• Add PDF conversion script via Asciidoctor-fopub:
  • Use FOP/XSL template of Alan Manual?
• Add HTML conversion script:
  • Use Asciidoctor default html5 template.

All documents should have automated building scripts in order to allow easier maintainance when changing the templates or updating the software of the toolchains.

@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.

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:

• Provide customized SVG iamges with different background color (affects all callouts in the book, in all blocks and within the text too).
• Disable callout icons and use text instead (i.e. (1)) via the callout.graphics setting (not very nice solution).
• Use Unicode characters instead of icons (possible, but need to look into how to do it).
• Use a lighter color scheme for shell (simplest 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.

• Fix BNF rule — done in branch 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 a Glossary to the ALAN Manual:

• Check if Glossaries are supported in HTML backend (they are).
• Create Glossary section.
  • Added in temporary branch beta7-prep_glossary, between last Appendix and Index (in file: manual_17.asciidoc)
  • Update Manual README.md to list new manual_17.asciidoc source file.
• Add entries:
  • stropping
• Add entries placeholders — commented out entries with dummy definitions, as placeholders:
  • attribute
  • BNF
  • class
  • clause
  • construct
  • escaping
  • expression
  • identifier
  • inheritance
  • instance
  • property
• Submit Pull Request. When the Glossary is ready to be squashed into 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.

Preview Links

The current state of the Glossary can be viewed in the beta7-prep_glossary branch:

• HTML Manual — Live HTML Preview
• PDF Manual
• manual_17.asciidoc — Glossary source file.

About the Glossary

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.

Glossaries in Asciidoctor

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!

Useful Links

• Asciidoctor Manual » §58. Glossary
• The Word Factory » How to make a good glossary
• wikiHow » How to Write a Glossary
• Wikipedia » Glossary

Links to Online Glossaries

Some useful online glossaries on programming terminology:

• CodingDojo » Glossary of terms
• ComputerHope.com » Programming terms
• hackr.io » Top Programming Terms and Definitions for Beginners
• Programming for Beginners » Expand Your Programming Vocabulary
• Wikitionary » Glossary of computer programming

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 or Only definitions and execute them (stop if Only 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 or Only qualifier it is executed. If the qualifier was Only 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

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?

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.

Code Examples

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.

Inline Keywords

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 LOCATIONs.

Alan EBNF Blocks

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.

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!)

• Alan in A.2. Compiler Switches:
  • Add -vesion switch
  • others? (need to check when Beta7 is finally out)
• ARun in A.4. Interpreter Switches:
  • Add -vesion switch
  • -h for -help is supported (although non mentioned in help)
  • others? (need to check when Beta7 is finally out)

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.

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?

Preview Links

• App. G.5. Word order (master)
• App. G.5. Word order (dev-man)

Possibly in Chapter 2, but maybe also where the concepts are introduced/used.

Task list and progress status of customization of syntax highlighting in PDF documents.

• Create custom language definitions fo XSLTHL:
  • Alan ("alan-hl.xml").
  • BNF (moved to #38).
• Customize XSL stylesheets for sourcecode blocks, so that each language has its own color theme and all syntax elements are covered and styled:
  • Alan code examples
    • Add conditional checks in XSL/XSLHL styles to customize look and feel of Alan source code.
    • Define styling for all syntax elements of the Alan language.
    • Choose a color scheme for Alan examples (chosen GitHub's old scheme)
  • BNF rules
    • Add conditional checks in XSL/XSLHL styles to customize look and feel of BNF rules. (moved to #38).
    • Define styling for all syntax elements of BNF (terminal, non terminal).
    • Choose a color scheme for BNF rules.

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).

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).

Highlight Integration

There is an example extension to integrate André Simon's Highlight in Asciidoctor:

• https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/highlight-treeprocessor.rb

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.

Looking Into Other Highlighters

Asciidoctor natively supports various syntax highlighter, but I was thinking of using either Rogue or Highlight.js.

Rouge

• http://rouge.jneen.net/
• https://github.com/jneen/rouge

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.

Highlight.js

• https://highlightjs.org/
• https://github.com/highlightjs/highlight.js

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.

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:

• styles-preview.pdf
• tests-syntax-highlighting.pdf
• tests-typography.pdf

Also, some PDF related issues have to be dealt with. Here is a task list of the WIP status:

• Customize XSL styles:
  • LISTS:
    • Ordered List Bullets:
      • Fix bullet types definition to use supported chars.
      • Use square bullet for all level (new font used).
    • Q&A Lists: For some reason, items in this list inherit the full section numbering. (NOT IMPORTANT!)
  • FOOTNOTES:
    • Footnotes in Tables: use numbers instead of letters (this seems to occur only inside tables, but in the Manual these are the only footnotes right now). (CAN'T FIX THIS!)
    • Smaller footnote marks, not bold.
  • ADMONITIONS:
    • Nicer icons? (CAN'T FIX THIS!)
    • Icons colors according to type of admonition (red, yellow, green, blue, etc.)? (moved to #39)
    • Add Light BG colors and borders? (could use different colors for each admonition type) (moved to #39)
  • CUSTOM BLOCKS (code, verbatim and examples):
    • Colors and styles):
      • Alan code examples
      • BNF rules (currently orange, like original).
        • Make it lighter, more pastel like.
      • Game transcripts
        • Bluish color scheme.
      • Shell output:
        • Win 10 default CMD scheme (new version).
        • Windows CMD legacy scheme (DARK_WHITE on DARK_BLUE).
    • Split Blocks: see if we can control orphan lines and/or prevent breaking up the block at page end.
  • Fix MOCKUP SAMPLE BLOCKS in § 2.4 Notation via roles:
    • Alan code notation sample
    • BNF rules notation sample
    • Game transcripts notation sample
  • EXAMPLE BLOCKS:
    • Rounded corners.
    • Very light BG color?
  • COMMENTARY — Paragraphs with "commentary" role: add left margin.
    (These appear below verbatim compiler output, as commentaries, eg in App C. Run-Time Messages)
  • FONT SIZES:
    • Smaller Captions (Tables, Figures, etc.).
    • Smaller font in Example blocks Titles.
    • Inline Code: looks bigger than base font, should reduce size slightly.
  • HEADER & FOOTER:
    • Better alignment of page number and title.
    • No header on blank pages.
    • No header border on headerless pages.
    • Lighter colors? (grey)
  • PREAMBLE:
    • FIXED: removed bounding box.
• Fix problem with special Unicode chars not showing in PDF (eg, arrows symbols in Tables)
• FONTS:
  • Find appropriate fonts and include them in project
    • Main text: Noto Sans — License: Apache 2.0.
    • Headings: Fira Sans Condensed — License: SIL Open Font.
    • Verbatim/Code Roboto Mono — License: Apache 2.0.
  • Set fonts in XSL stylesheets

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.

Admonition blocks could be graphically improved.

• Nicer Icons — This one seems tricky. I've managed to make the template load custom SVG icons from the document folder, but I can't find a way to load custom icons from the custom template folder. Must research this more.
• Colorize Admonitions by Types:
  • Icons colors according to type of admonition (red, yellow, green, blue, etc.).
  • Add Light BG colors?
  • Colorize border according to type.
  • Slighlty colored text according to type.
• Smaller font? (need to test this)

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]

This issue tracks and discusses choosing fonts for the PDF template:

• Enable custom fonts in XSL FO template settings.
• Choose a font for:
  • Main text: Noto Sans — License: Apache 2.0.
  • Headings: Fira Sans Condensed — License: SIL Open Font.
  • Verbatim/Code Roboto Mono — License: Apache 2.0.
• Include chosen fonts in repository:
  • TTF/OTF
  • Webfonts (not needed right now!)

When choosing a font for the PDF template, we need to check that the following criteria are met:

• Project inclusion — The font's license should permit including the font file in this project.
• Webfont — The font should also be available as webfonts, or its license allow converting it to webfonts and storing them in this project. This is so that we can use the same fonts for HTML-based documents (web pages, ePub, Mobi, etc.).
• Style and weights — The font must also available in bold, italic, bold+italic variants.
• ISO-8859-1 glyphs — All ISO-8859-1 characters must be present in the font's glyphs.
• Unicode chars — Commonly used Unicode characters/symbols should be represented in the font.
• Ligatures — Should the (non-monospace) font used in the main body of text should support ligatures?
  • Does Asciidoctor rely (require) on ligatures for some replacements? (eg, =>) — need to check this!
  • Asciidoctor-fopub uses FOP v2.1 which doesn't support ligatures in PDF!
  • Check if the HTML backend supports ligatures.

Original Fonts in Manual

These are the fonts currently used in the Manual:

• Pristina — A commercial font by International Typeface Corporation.
• Garamond — Many free fonts are available, based on the original typeface created by Claude Garamont (c. 1510–1561).
• Courier New — Although the font that comes installed with Windows OS is a commercial font by Microsoft, similar typefaces are freely vailable under many different names.

Use of italics in the above list indicates that the font should be available in the preinstalled fonts of most OSs.

Fonts Websites

• Font Squirrel — a good website for fonts, with many fonts also available as webfonts, and there is also the Webfont Generator tool to convert font files to webfonts. Font Squirrel also provides useful license information for its fonts, and prevents any operations that might violate the font's license terms.
• Google Fonts — Huge fonts collection, with many options and tools to customize fonts.

This issue tracks (and discusses) the status of metadata and other book info for the Alan Manual document header:

• Book Info:
  • :doctitle: — The ALAN Adventure Language Reference Manual
  • :description:???
  • :keywords:???
• Author(s) Info:
  • :author:???
  • :email:???
• Others?

Live Preview links

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

• HTML Manual
• PDF Manual

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.

AsciiDoctor Documentation References

• § 14. Header
  • § 14.5. Metadata
  • § 14.6 Header Summary
• § 51. Colophon

@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.

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.

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.

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.

• Find all problematic characters and lists them:
  • Table 4. Order of Execution of Verbs:
    • Downward Arrow
    • Vertical Ellipsis
  • Table 3. Order of Execution of ENTERED in Nested Locations:
    • Downward Arrow
    • Vertical Ellipsis

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.