StdLib Man: Dynamic Inclusion of Library Source Excerpts

[tajmone]

UPDATE — For this topic, refer to the new Dynamic Examples article on the ALAN Docs Wiki.

---

In various places of the StdLib Manual there excerpts from the library source (sometimes the entire file is shown). Since the manual was last edited these sources have now changed.

Instead of manually copying and pasting each source snippet from the library to the Manual sources, I suggest that we instead use Asciidoctor's include:: directive to extract the required code dynamically, which will ensure that every time we rebuild the Manual these code snippets will mirror the current state of the library.

Selectively including certain parts of a source file can be done in two ways in Asciidoctor:

1. By providing line ranges.
2. Via tagged regions.

Including by Line Ranges

The first solution doesn't require changing the sources in any way, it's enough to provide the desired line range to import from the target source:

include::lib_verbs.i[lines="1..10,15..20"]

but its obvious downside is that whenever the target source changes the line ranges might need to be adjusted, because the desired code snippet might have shifted up or down in the source.

Including by Tagged Regions

The second solution is much better because it allows to tag specific regions of interest in the target sources using their native comments, which can than be imported via their tag name.

This system is already being used to handle dynamically the code examples in the StdLib Manual, in order to include the examples snippets from real sources, which are then compiled and run with a commands script, and then snippets of the actual game-play are included in the Manual via the same system.

Here's a real example from _variations1.alan:

--------------------------------------------------------------------------------
-- §6.1.3. DOOR
--------------------------------------------------------------------------------
-- tag::front_door[]
THE front_door ISA DOOR AT garden
  NAME front door
  DESCRIPTION ""
END THE front_door.
-- end::front_door[]

where the comment lines -- tag::front_door[] and -- end::front_door[] delimit the front_door tagged region, which is then imported into the manual (in StdLibMan_06.adoc) via:

[source,alan]
--------------------------------------------------------------------------------
include::{utf8dir}/_variations1.alan[tag=front_door]
--------------------------------------------------------------------------------

In the final Manual, the reader will just see a normal ALAN code block, but for us maintainers it means that whenever we change the example sources, or their output changes due library changes, the Manual is self-updated without need of any cut-&-paste operations. It's a slightly more laborious approach, but it's worth it because it only needs to be done once (set it and forget it).

The obvious downside of this approach is that it requires adding the region-tags comments in the StdLib sources. Whereas these comments are not a problem in the examples files (which either are not shared with end users, or if they are they get stripped of these comments in the release archive), adding these comments to the library sources is another issue altogether.

@AnssiR66, if you don't mind me adding a few of those tags comment lines to the StdLib sources, it would be a great improvement to ensure that the Manual (and any other document in this project) will always show up-to-date excerpts from the library sources.

In case you don't want these tag-region comments to be added to the sources, the solution is to filter them out in the final end-user release. This adds an extra layer of complexity, because the library sources need to be preprocessed for the end users (using sed), but it has already been adopted in the Alan-Docs repository, for the The Alan Beginner's Guide (which extensively imports snippets from the example adventure, which is then made available to end users after stripping the tag-comments line).

What do you think of this?

---

References

• Asciidoctor Manual:
  • 28. Include Directive
    • §28.6.1. By tagged regions
    • §28.6.3. By line ranges

[AnssiR66]

I think these tags can be very well added to the sources. Anyway, the aim of the library is for the game author to access the actual library sources as little as possible and define everything in their own game source file. - Do you mean these tag lines will also show in the manual?

[tajmone]

Do you mean these tag lines will also show in the manual?

No! Asciidoctor will remove any tags comments in the output document. The way tags are implemented is really cool, there are a lot of advanced features in tags regions:

• You can split a tagged region into many chunks across the document(s), and they'll show as a single chunk.
• You can use globbing-style patterns and match tags categories (e.g. class-* will match tags class-actors, class-devices, etc.).
• You can match all, or exclude match patterns.
• And other cool features...

Asciidoctor has really done a great job with the include:: directive, and (if I remember correctly) tags is a new feature added to AsciiDoc by Asciidoctor (i.e. not present in the original AsciiDoc Python).

[AnssiR66]

Sure, sounds good! Just go ahead...

[tajmone]

See #126 on how to include:: ALAN sources and transcripts directly (i.e. ISO-8859-1 encoded) into ADoc sources, without having to convert them to UTF-8 first.