§ 2.3 - A Brief Introduction to Built-ins and Styles

See also:  [ghost] ,  [glos] ,  [gstyle] ,  [listg] ,  [locs] ,  [spage]  and  [style] 

§ 2.3.1 - Overview

Styles are the heart of what class   macro()   is about. The built-ins you'll be reading about throughout this manual are the low-level bricks and mortar that get things done, but styles are how you get things done cleanly and easily and sanely using the built-ins. They also let you go beyond the built-ins into wholly custom text generation.

§ 2.3.2 - Built-ins

You specify a built-in using square brackets. Here's how to do HTML italics. What happens is that the built-in named "i" receives "my text" as content. It then wraps HTML italics tags around that content, and returns it that way:

§ 2.3.3 - Styles

Here are the primary components of a style:

Here's how that works in practice:

You can create any custom style you like, including ones that do what the built-in operators do. For instance, you can create an italics style to do the exactly same thing as the italics built-in very easily:

That's a simple example intended to demonstrate how; the why is generally more interesting. Perhaps you like to use bold with italic to emphasize; that's just as easy:

aa_macro's built-ins are designed with an eye towards HTML rendering. But perhaps you have a need to generate text to be processed by something other than a web browser (such as markdown, which has to be processed further) where italics are indicated by underscore. In that case, you'd do this:

You can write sets of styles and place them in files to be included in your projects. So you can write styles that generate, for instance, HTML and markdown from the same source documents. In fact, I do that very thing using the aagen command in the aa_macro repo to generate the quick reference documentation:

On the first line, the  -i qr_html.txt  includes styles that generate to HTML.

On the second line, the  -i qr_markdown.txt  includes styles that generate to markdown.

Both command invocations take  quickref.txt  as the primary source input, and each generates to a different file,  quickref.html  and  quickref.md  respectively.

See also:  [ghost] ,  [glos] ,  [gstyle] ,  [helps] ,  [helps2] ,  [listg] ,  [locs] ,  [s] ,  [spage]  and  [style] 

§ 2.3.3.1 - Style Syntax Flow

Style Syntax Flow Diagram