Collections

Say you are writing a documentation and lots of acronyms fill the place. There should be a chapter that provides a complete list, with links to the definitions.

Here is an idea how to accomplish this: write a macro that is used whenever a new acronym is introduced. The macro formats the original text a certain way, in the background it collects it together with a source hint. When it comes to the list chapter, the stored hints can be used to build the link list.

To achieve this, I use a macro like this to collect things (remove the newlines when copying):

    +COLLECT:\EMBED{lang=perl
              my $b=q(__body__);
              push(@__type__, $b);
              join('', '\I<\OREF{n="__chapter__"}<__hint__> \SEQ{type=__type__ name="__type__', ++$__type__, "\"}: $b>")
             \END_EMBED

This is a generalized implementation for the collection task. It uses Perl (requires -active in the converter call) to perform the dynamic operations. First, the body is taken and stored in an array. This array is not declared lexically (by my) which makes it a package variable. Using package variables allows to share variables between all embeddd and included Perl snippets, so each subsequent call of the macro can access the array again and complete it more.

The final Perl line in the macro definition formats the text that appears where the macro was used. Here I append an intro text (parameter "hint") which is a link to the collection list page (parameter "chapter"), and finally display the original body. Adapt the macro if you don't like the prefix or want to wrap the body text another way, but please let the sequence intact: the macro adds a uniquely named sequence of a special type (parameter "type") to the text. This way, I get a link target for later reference.

Due to the generalization, I now can define collections of various types. Here are a few declarations:

    +ACRONYM:\COLLECT{type=acronym hint=Acronym chapter=Acronyms}<__body__>
  
    +TODO:\COLLECT{type=todo hint=Todo chapter="To do"}<__body__>
  
    +QUESTION:\COLLECT{type=questions hint=Question chapter=Questions}<__body__>

With these definitions now it's easy to add an item to a collection, e.g. by \ACRONYM<ACR> or \TODO<Look there!>. As defined, each of these calls will add an anchor and a text at the macros position, and it stores the body text in a type specific array in the Perl space behind the scenes.

And finally, we want to write a chapter that contains a linked list to all the items collected. As this task is similar for the several types, again I wrote a macro to perform it:

    +SHOW_COLLECTION:\EMBED{lang=perl}
                      my $c;
                      join("\n",
                           '',
                           map
                            {
                             join('',
                                  "\n# $_ (\OREF{n="__type__",
                                  ++$c,
                                  "\"}<read with contents>)\n\n"
                                 )
                            } @__type__
                          );
                      \END_EMBED

This macro again receives the type to work for and transforms the entries in the related collection array into a numbered list, with each entry containing the item text and a link to the place where it was collected. So, for example, an acronym in the list will have a link to the place where an \ACRONYM macro was used to add it to the collection.

Usage of the show macro is simple:

    =Acronyms
  
    \SHOW_COLLECTION{type=acronyms}
  
    =Questions
  
    \SHOW_COLLECTION{type=questions}
  
    =To do
  
    \SHOW_COLLECTION{type=todo}

Of course a lot of other things could be done in this model - providing sorted lists only containing the first occurence of each item springs to mind. Everything possible with Perl can be done with the collection to present it a perfect way.