This document contains some guidelines for editors and contributors on how to apply consistent AsciiDoc formatting and styling in the Alan documentation.
These guidelines are not yet complete, and they are open for discussion and change proposals via repository Discussions and Issues.
Table of Contents
- Introduction
- Use UK English
- AsciiDoc Formatting Guidelines
- Source Code
- The Index
- Related Issues
- External References
The following guidelines are not absolute rules engraved in stone, and contributors might encounter cases where a different approach might be more appropriate in the given context. Understanding the purpose of these conventions and guidelines will enable contributors to decide when exceptions are due.
Formatting and styling conventions are intended to provide a better and more pleasant reading experience to final users of the documentation. By adopting consistent styling in a document (and, possibly, across multiple Alan related documents), the reader intuitively learns to associate each style with a specific context, providing a smoother reading experience.
The nature of the Alan documentation poses some special challenges when it comes to styling conventions, for in the natural flow of the documentation it's not always easy to decide how to represent a term that is both an Alan keyword and an English noun — the Alan philosophy revolves around the idea that the Alan syntax should mimic natural English, rather than a classic programming languages paradigm.
Therefore, in the course of a sentence it might be difficult to choose how to represent certain words. For example, while discussing actors, we're dealing with a natural English concept and an Alan predefined class, so 'actor' could refer either to the English noun or the Alan keyword.
Sometimes the distinction is not so important, as the context has already clarified the topic at hand, and the Alan keywords and their English counterparts are one and the same in the discourse. But sometimes it's important to let the reader distinguish when a word is referring to a specific keyword, and not a generic concept.
These guidelines were designed for the official Alan documentation, and if you're contributing your own documents to the project (tutorials, articles, etc.) you are under no obligations to follow them — we surely aren't going to tell anyone how they should style their own writings.
The Alan documentation should follow UK English rules. If you use spell checking tool, set them accordingly. This affects also conventions for abbreviations, etc.
We strongly recommend reading the AsciiDoc Recommended Practices guidelines.
From AsciiDoc Recommended Practices:
Don't wrap text at a fixed column width. Instead, put each sentence on its own line, a technique called sentence per line. This technique is similar to how you write and organize source code.
Among the (many) benefits of this approach in terms of collaborative editing and text maintenance, it also prevents lots of headaches when it comes to diffing source documents (and in all Git related diffing operations and logs).
These guidelines pertain how code and language keywords should be formatted in the document.
Code examples blocks in the document should be formatted according to the following guidelines.
In the final documents all Alan code blocks are syntax highlighted, therefore colours will provide the reader with helpful cues to distinguish reserved keywords, between built-in classes and user defined classes, and all the various language constructs.
All code should follow prose case rules, i.e. use capital letters only when at the beginning of an independent line, or when it makes sense to do so (e.g. a proper name that in English would be capitalized), although the last rule is left to the author's discretion.
The goal is to provide a fluid text that looks natural, without emphasizing the programming language aspect.
- keywords should be capitalized only when beginning or closing a block, or when on an independent line or sub-construct (e.g.
If/End if,The/End the,Every/End every, etc.), with the exception of:- compound keywords containing multiple words should be capitalized as if there was a space between them (e.g.
IsA,ElsIf) to improve their readability.
- compound keywords containing multiple words should be capitalized as if there was a space between them (e.g.
- predefined classes should be lowercase (e.g.
thing,actor). - indentation: 1 Tab = 2 spaces.
For practical reasons, often part of the examples code is truncated to keep the focus on the topic being presented.
- horizontal truncation should be indicated by adding three inline full stops ("
..."). - vertical truncation should be indicated by a line containing only three full stops ("
...") following the natural indentation of the code they replace.
Example:
Every door IsA object ...
Has otherside door.
End Every door.
The east_door IsA door.
Has otherside west_door.
...
NOTE — We'll need to check how these
...will be handled by the syntax highlighter. Probably, they'll be highlighted as Alan keywords (the Highlight syntax treats the terminating dot as a keyword), but we could tweak the syntax to treat three consecutive full-stops as a separate token group, in order to have them styled using different colouring.
Here are some conventions regarding the style and structure of Index entries.
- Alan keywords should always be in all-caps (e.g.
IF,THEN,EVERY).
Follow and contribute to the discussion on formatting and styling issues:
Some useful links...