1 - Introduction

1.1 - What is This?

aa_macro is an open-source macro language aimed at providing flexibility in writing documentation in text form, 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 such as my own wtfm.

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

 [builtinStyle] 

 {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. This has implications for certain types of content and may result in some non-obvious behavior when your content is complex. Here is a quick example of how content processing events are ordered:


input: [p [i foo] [u bar]]
step1: [p <i>foo</i> [u bar]]
step2: [p <i>foo</i> <u>bar</u>]
step3: <p><i>foo</i> <u>bar</u></p>

There are four types of exceptions to this rule. The first is definition of a  [style]  and  [gstyle] , the second is  [repeat] , the third is the specialized  [hlit]  and  [pythparse]  code-documenting pretty-print tags, and the fourth is 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.

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:


[style dollars $[b]$]
[local forlater {dollars moneybags}]

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.

Keyboard Navigation
, Previous Page . Next Page t TOC i Index

Valid HTML 4.01 Loose
 

This manual was generated with wtfm
wtfm uses aa_macro and SqLite
aa_macro uses python 2.7