directives

With directives you can control how a .xil file is assembled and how its corresponding HTML file is generated. See the directives category in the example browser for examples and below more detail.

overview

directive param description
define. key one-line-value define key/value pairs, one pair per line
define. key
multiple-line-value		 define key/value pair where the value is more than line
undef. key remove definition of key
ifdef. key text translate text if key is defined
ifndef. key text translate text if key is not defined
include. path include file
includex. path include file but do not Xilize — only <, >, and & will be translated to character entities (even in HTML tags)
propfile. path read properties file as key/value pairs to define
xilize. create epilog/prolog (@@ and other top-level elements) — classic mode only
[abbr]url create abbreviation for a URL
toc. min max type table of contents: min heading level (e.g. "2"), max level (e.g. "3"), type (* or #)
body. exists only to allow you to put modifiers on the <body> tag

Each of these directives is described below.

key/value definition

Each time Xilize translates an .xil file it creates an environment of key/value pairs that you can access, modify, and add to. Use them

  • to avoid typing the same thing more than once
  • to control
    • how your pages are assembled
    • how HTML is generated

define.

There are two ways to add a definitions to the environment.

A mulitple-line value is added with

define. myMulitLineKeyName
the value of the key goes
on any number of lines
and is terminated by a blank line

Alternatively several keys can be defined in one statement if they all have single line values:

define. president1 George Washington
president2 John Adams
president3 Thomas Jefferson

In this case the first word on the like is the key and the rest of the line is the value.

Notes:

  • Values may contain any text including Xilize markup.
  • Except in the case of the special keys style and script adding a definition for a previously defined key replaces the old definition.

undef.

To remove a definition use

undef. keyName

key substitution

Use a key's value in your text like this:

See the ${eb} for more information.

See the example browser for more information.

Where ${eb} was defined in this directive:

define. upNav ../intro.html
docTitle Xilize2 User Guide
eb "example browser":examples/examples.html

special keys

Xilize is aware of a few dozen special keys which you can use to control HTML generation as well as access their values in your markup with ${key}. See the quick reference for an overview and the page assembly chapter of this guide for details.

conditional translation

Two directives allow you to conditionally translate blocks depending on whether or not a key has been defined.

ifdef.

If the key useGandhiQuote has been defined, the block will be translated, otherwise it will be ignored.

ifdef. useGandhiQuote  bq. Permanent good can never be the outcome
of untruth and violence. _Mohandas K. Gandhi_

In this example, assuming useGandhiQuote has been defined (to anything at all), the bq. block is translated:

Permanent good can never be the outcome of untruth and violence. Mohandas K. Gandhi

ifndef.

If the key useGandhiQuote has not been defined, the block will be translated, otherwise it will be ignored.

ifndef. useGandhiQuote  bq. Permanent good can never be the outcome
of untruth and violence. _Mohandas K. Gandhi_

use cases

Conditional directives can be nested:

 ifdef. addQuotes  ifdef. useGandhiQuote bq. Permanent good can
never be the outcome of untruth and violence.
_Mohandas K. Gandhi_

One of the mose powerful uses of conditional translation is in combination with the include. directive. See below.

include files

One of the essential features of Xilize, the include file directives provide a powerful mechanism for eliminating duplice text and easily structuring a group of HTML pages with a similar look-and-feel. Page headers and footers are so common Xilize has some special mechanisms in both classic and natural modes to handle them — see the page assembly chapter of this guide for more information.

All three of the include directives take one parameter: the path to the file to be included. In all cases if the path is not absolute, it is take as being relative to the current file being processed. That means, if an include file A given as a relative path is being included in from another include file B, Xilize will take the location of A as being relative to the location of B irrespective of the location of the original .xil file.

Each include directive interprets the included file in its own way as described below.

include.

In a file named myPage.xil the directive:

include. quotes.xilinc

will cause the file quotes.xilinc to be read and included in the translation as if its text had been in the myPage.xil. quotes.xilinc may contain any number of blocks.

Relative paths (recommended)

include. ../../quotes.xilinc

will be resolved against the location of myPage.xil, or you can use an absolute path like

include. /home/andy/myProject/quotations/quotes.xilinc

Notes:

  • Using the filename extension .xilinc for Xilize include.'s allows you to get the benefit of syntax highlighting while avoiding the automatice xilizing which occurs with .xil files with the most common uses of Xilize.
  • See the relative file path assistant in XAA for a sure-fire way to set relative file paths accurately.

includex.

includex. is primarily intended for the inclusion of HTML and programming code examples. When a file is included by includex. it translated only to make it XHTML presentable. That means

  • <, &, and > are translated to their respective character entities
  • no key/value substitution is done

This is similar to the translation of prex. blocks.

propfile.

propfile. includes a Java properties file, interpreting the properties defined in the file like definitions created by the define. directive. It's a handy way to grab information generated by other programs. The expectation is that you will use some of the values of these keys in your .xil file with ${ key }.

URL abbreviations

Textile while not having a general purpose define. directive like Xilize does have a URL abbreviation syntax which is also supported here.

[cw]http://www.centeredwork.com

allows you to do this

Click "here":cw to go to Centered Work.

which translates like this

Click here to go to Centered Work.

You can put a group of URL abbreviations in a block, one per line, and have any number of such blocks sprinkled through your .xil file (or more likely in one or more include files):

[cw]http://www.centeredwork.com
[xilize]http://www.centeredwork.com/xilize2/xlinks.html
[ug]guide/intro.html

Note: URL abbreviations are

  • relative URLs are relative to the current file being processed
  • only used in the context of a link — as in the markup for a link "link_text":url_abbreviation or image !url_abbreviation!

table of contents

toc. generates a table of contents (TOC) in the location in which you place it in a .xil file. The TOC is generated from the <hn> elements in the file; you control which heading elements are involved.

The general syntax is

toc. min max type

where min and max specify heading levels and type is one of * or # (unordered or ordered list).

Note: the toc. directive may occur any number of times in the same file. For example, at the top of a file you have

toc. 2 2 *

to create a high-level TOC with only the level 2 headings. Then just after each of the <h2> you might do something like this

toc. 3 6 *

to provide a jump table local to that subsection's headings.

Note:

  • Xilize assigns id attributes to all heading elements which do not have an id attribute set
  • Xilize will use existing id attributes
  • The class attribute of the top-level (outer-most) <ul> or <ol> is set to toc so you can style your TOC as you please.

special markup for hn. blocks

If you want only a part of a heading to appear in a TOC — or something that is completely different than the text of the heading, the special markup &{toc: ... } and &{tocEntry: ... } is available:

markup TOC text
h2. An Introduction to Special Relativity An Introduction to Special Relativity
h2. An Introduction to &{toc: Special Relativity} Special Relativity
h2. An Introduction to Special Relativity &{tocEntry: Einstein's Idea} Einstein's Idea

body directive

The body. directive exists only to assign modifiers to the <body> start tag. One use of this is to add JavaScript hooks:

body{{onload="myFunction"}}.

Alternatively, you can assign name and id attributes:

body(myClassname#myId).

Or any combination of modifiers:

body(myClassname#myId){{onload="myFunction"}}))((=.

Note: This directive does not generate the <body> tag. That is done automatically (see page assembly).