8 - Formatting

This section collects various useful formatting notions you may want to employ.

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:

[hlit <b>My Bold Text</b>]
[global myglobal [v loc_hlit]]
WARNING:  [hlit] ,  [vlit]  and  [slit]  must be used in the global styles, project styles, or page locals area. They cannot be used successfully within the page content area. Also, they cannot be used inside another built-in or style. Use these commands as I describe above: generate to the local, then move that to the desired final local or global for use elsewhere before using the conversion again.

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:

{bu <span style="color:#5599FF;">&amp;[b];</span>}

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

[gstyle entity {bu <span style="color:#5599FF;">&amp;[b];</span>}]

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

[gstyle keyhints
<div style="
clear: both;
width: 75%;
border-style: solid;
background: #ffffff;
text-align: center;
padding: .5em;
margin: auto;
"
>
[i Keyboard Navigation]
<hr width="75%">
{key ,} Previous Page
{key .} Next Page
{key t} TOC
{key i} Index
</div>
]

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

[gstyle keyhints 
<div style="
        clear: both;
       width: 75%;
border-style: solid;
  background: #ffffff;
  text-align: center;
     padding: .5em;
      margin: auto;
"
>
[i Keyboard Navigation]
<hr width="75%">
{key ,} Previous Page
{key .} Next Page
{key t} TOC
{key i} Index
</div>
]

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

[gstyle codediv 
<div style="
    background: #000088;
         color: #00ff00;
 margin-bottom: {cpad};
       padding: {cpad} {cpad} {cpad} {cpad};
"
>[b]</div>
]

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

8.2 - Special Variables

wtfm creates three 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:

[vlit vglobal_styles]
[local xlatedglobalstyles [v loc_vlit]]

2: Invoke the variable in the Page Content:

[v xlatedglobalstyles]

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:

[vlit vproject_styles]
[local xlatedprojectstyles [v loc_vlit]]

2: Invoke the variable in the Page Content:

[v xlatedprojectstyles]

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:

[vlit vparent_styles]
[global xlatedparentstyles [v loc_vlit]]

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

[v xlatedparentstyles]
Keyboard Navigation
, Previous Page . Next Page t TOC i Index

Valid HTML 4.01 Loose
 

This manual was generated with wtfm