§ 1 - Introduction

§ 1.1 - What is This?

aa_macro is an open-source macro expansion language aimed at providing deep functionality to chat systems, and/or authoring documentation in text form, and/or for markup languages, particularly HTML. It is a Python 2.7 import library with zero non-standard Python 2.7 dependencies. You can use it directly in your own Python 2.7 code by simply importing it, or you can use it indirectly, in the context of a full documentation system, for example as used in my own wtfm documentation system.

aa_macro uses two basic notational forms. Square brackets are used to invoke built-in operators; and squiggly braces are used to invoke user-defined styles:

 [builtinOperator] 

 {userStyle} 

§ 1.2 - What Problem does it Solve?

Some documentation projects are technically difficult. There are many facets to this kind of work. For instance tables of contents, indexes, glossaries, cites, foot- and end-notes, images, figures, sidebars, ads, and so on. aa_macro specifically tries to make all that easier to manage, and in such a way as to allow maximum flexibility at the same time it supports writing less to accomplish more. And by "documentation", I mean entire websites, manuals, how-tos / tutorials, stories, resumes... basically anything at all you might want to write.

§ 2 - The Details

§ 2.1 - How Text is Processed

Class   macro()   internal operation is generally described as processing content from an input stream to an output stream (an internal stream, not an IO stream) in an inside-to-outside, left-to-right order. If you're familiar with RPN, aa_macro parsing is similar.

This has implications for certain types of content. It may result in some non-obvious (but well-defined) behavior when your content is complex, so it's critical to understand the order of events when you're writing macros.

Here is a quick example of how content processing events are ordered:

In step 1,  [i foo]  is processed, because it is first in left-to-right order within the inside-most level.

In step 2,  [u bar]  is processed, because it is also within the inside-most level, and it comes next in left-to-right order.

In step 3,  [p <i>foo</i> <u>bar</u>]  processes the completed results of the inner level.

There are four types of exceptions to this inside-to-outside, left-to-right processing order.

The first when you define  [style]  and  [gstyle]  user macros.

The second is when you define a  [repeat]  macro.

The third is the use of the specialized  [hlit]  and  [pythparse]  code-documenting pretty-print tags.

The fourth is the use of the  [raw]  and  [graw]  variable storage operators.

In all four cases, processing the content of these built-ins is deferred.

For  [style]  and  [gstyle] , this allows their results to vary based on events in the processing stream concurrent with the actual invocation of the style, rather than the conditions that obtain at the time of style definition.

For  [repeat] , evaluation occurs within the context of each repeat, rather than just at definition time. (If you need that behavior, use  [dup]  or  [eval]  instead.)

For  [hlit]  and  [pythparse] , the content is not processed normally, but instead is passed through pretty-printing processes where custom characters and styles are applied for enhanced display in HTML and similar environments.

For  [raw]  and  [graw] , the content is not processed at all, it is simply stored in the variable for later retrieval.

You can also use quad-backtick content fencing to cause the various braces not to be interpreted in any context:

````{some literal [content]}````

All other content is processed inside-to-outside and left-to-right.

If you want a style to process immediately for later use in the context that is extant when it is defined, then the best way to go about that is to use the style immediately, storing the result in a variable for later placement. This preserves the style result. An example of such a style use is as follows:

The result,  $moneybags$ , is placed into the local variable "forlater" and can be used at any time after that by simply pulling the variable:

 [v forlater] 

Instances in which this would be useful include those where you change the style before the content would be used, or if the style uses other elements which themselves change before the content is used.

§ 2.1.1 - Newlines, or Not

Within aa_macro source, newlines are normally significant, by which I mean that if you have them in the source, they will show up in the output. There may be times, however, when you don't want a line of aa_macro source code to produce a newline. In that case, simply end the line with two spaces. aa_macro will then not generate end of line character to the output stream.

§ 2.1.2 - Built-in Command Syntax Flow

Built-in Command Syntax Flow Diagram