New Spanish Documentation

[tajmone]

@Rich15 and @thoni56, I've now added in alan_es/docs/ a draft of the user guide for the Spanish Foundation, currently written in English.

The document supports Dynamic Examples via external ALAN adventures and solution files which are re-compiled and generated at build time, handled via the latest Rake functionality — the very functionality which has kept me away from the Foundation project in the past week, since it took me some time to code it (sorry for the prolonged silence, but as you're about to learn, the resulting new features were well worth the waiting).

Rake takes care of handling all documentation prerequisites, so whenever changes are detected not only in the AsciiDoc sources, but also in the Spanish library sources, the external ALAN examples or their solution files, the documentation is rebuilt automatically to ensure that any changes to the source code are reflected in the documentation.

In practical terms, this means that we don't have to worry about code examples and transcripts shown in the documentation becoming outdated, since code snippets are extracted at build from real ALAN sources, and sample transcripts are re-generated whenever there have been changes to the code. This is a particularly useful feature, for large documents in general, but especially for documenting a work-in-progress library subject to continuos changes which affect the text of the transcripts.

For us is a set it and forget it blessing, for we don't have to worry about untranslated or buggy library messages, since these will be auto-fixed in the documentation once they are fixed in the library. We only have to focus on creating ad hoc ALAN adventures and solution files to cover the various topics described in the docs, and generate transcripts that serve the purpose.

@Rich15, Currently, we're not tracking any of the generated HTML docs, only their AsciiDoc sources, so in order to view the documentation you'll also need to install Asciidoctor, in case you didn't already.

Were to Go From Here...

We could use this Discussion thread to track development of the new Spanish Foundation guide. To be clear, I don't have any clear plan in mind yet, especially since I'm writing the document in English, which doesn't make too much sense.

Right now, I'm focusing on providing a document that illustrates how to use the new Spanish grammar module and its attributes; so it's more of a compendium to English documentation really, covering the Spanish specific features and not the whole library.

Probably, once the Spanish library is heading toward completion, it would make more sense to translate (or rewrite) its documentation in Spanish — but that would require a native speaker with considerable spare time to dedicate to this task. Hopefully, this document I'm writing in English could make the translation job a bit easier, since it covers those aspects which are not found in the English documentation.

Enjoy! and share your thoughts on the topic ...