8 - Formatting

8.1 - [hlit], [vlit] and [slit]

8.1.1 - [hlit]

 [hlit (format=1,)content]  is very useful when you want to present HTML code, or document code, literally.

You must use this tag in one of the style blocks; you can't use it in a Page Content block.

What it does is translate everything between its braces into HTML suitable for display in a normal HTML environment. This lets you place the code you want to share in one place, and without any concern about tags or encodings, display it.

If you include the optional format=1, parameter, all spaces are replaced with    , which prevents HTML compression of spaces.

When this runs, it places the result into a local variable named  loc_hlit . You can convert that to a global variable by creating global storage of the local's content, like this:

Anything that needs to be prepared for the whole document, you should do on the first page into the local, then move into a global. That will make it available to all pages in the document.

If you set up global variables, you can control the styling of the various tags. Note that the pretty-printing depends on the idea that you create balanced pairs of braces, squigglies, angle brackets, and double quotes. These are the variables, which are in pairs providing pre- and-post element formatting control:

•  ppre_lb  and  ppos_lb  for left square brackets
•  ppre_rb  and  ppos_rb  for right square brackets
•  ppre_ls  and  ppos_ls  for left sqiggly brackets
•  ppre_rs  and  ppos_rs  for right squiggly brackets
•  ppre_la  and  ppos_lav  for left angle brackets
•  ppre_ra  and  ppos_ra  for right angle brackets
•  ppre_quo  and  ppos_quo  for opening double quotes
•  ppre_cqu  and  ppos_cqu  for closing double quotes
•  ppre_ampv  and  ppos_amp  for ampersands
•  ppre_lf  and  ppos_lf  for ampersands

You can look at this project's styles, here, to see how I set the above variables up for this manual to provide pretty-printing of the styles and built-ins.

In addition, you can alter the strings for the actual characters by changing the contents of the following variables:

•  txl_lb  for left square bracket
•  txl_rb  for right square bracket
•  txl_ls  for left squiggly bracket
•  txl_rs  for right squiggly bracket
•  txl_lt  for left angle bracket
•  txl_gt  for right angle bracket
•  txl_am  for ampersands
•  txl_qu  for double quotes
•  txl_lf  for newlines (*nix LF, 0x0A)

8.1.2 - [vlit]

 [vlit (format=1,)variableName]  is like  [hlit (format=1,)content] , but generates from a variable's content instead of literal content. When this runs, it places the result into a local variable named  loc_vlit .

8.1.3 - [slit]

 [slit (format=1,)(wrap=1,)styleName]  Is used in a similar fashion, only it captures style content for you. If format=1, all spaces are translated to non-breaking spaces. If wrap=1, then the style definition is wrapped around the style content. When this runs, it places the result into a local variable named  loc_slit .

Here is the  {entity}  style without wrap=1; as you can see, it presents the content of the style only:

Here is the  {entity}  style with wrap=1; here, the definition is included as well:

Here is the  {keyhints}  style without format=1. Notice that the information is all flush left and spaces are collapsed:

Here is the  {keyhints}  style with format=1. Here you can see that the formatting of the original style is preserved:

If you're wondering about the blue background behind the styles, that's being done by wrapping the result of  [slit]  with  {codediv} :

Examples of using  [vlit (format=1,)variableName]  are presented next.

8.2 - Special Variables

8.2.1 - Global Page Variables

wtfm creates three global variables that provide you with current page information. They are:

•  current_page  — the page and extension for the current page
•  prevpage  — the page and extension of the previous page (empty if no such page)
•  nextpage  — the page and extension of the next page (empty if no such page)

You can use these for various purposes; one common use in my case is to conditionally create content that only appears on one page, or doesn't appear on one.

Here's how to generate content on every page but tocpage.html:

Here's how to generate content only on tocpage.html:

8.2.2 - Global Style Variables

wtfm creates three additional global variables that you can access that represent the unprocessed content of the global styles, any parent styles for the current project, and the current project styles. This allows you to easily include them in your documentation with just a few lines, no matter how extensive they are. These are the variables:

•  xlatedprojectstyles 
•  xlatedglobalstyles 
•  xlatedparentstyles 

Here's how to include the global styles in a displayable format in a local variable:

1: Place the translation mechanism in the Page Locals section:

2: Invoke the variable in the Page Content:

Here's how to include the project styles in a displayable format, also in a variable local to the current page:

1: Place the translation mechanism in the Page Locals section:

2: Invoke the variable in the Page Content:

Here's how to include the parent styles in a displayable format in a global variable:

1: Place the translation mechanism in the Page Locals section:

2: Invoke the variable in the Page Content of that page, or any page later in the main sequence: