This specification describes the contents of a template file, used for producing formatted output from a Collection of Notes.
Notenik will look for two sorts of special strings embedded within a template file: variables and commands. These are identified by special delimiters.
Notenik will recognize either of two sets of command and variable delimiters automatically. The choice of delimiters will be triggered by the first command-beginning delimiters encountered. The new delimiters are generally recommended, since they are more likely to be treated kindly by various HTML editors when creating your template files.
|Meaning||Original Delimiters||New Delimiters|
|Start of Command||<<||<?|
|End of Command||>>||?>|
|Start of Variable||<<||=$|
|End of Variable||>>||$=|
|Start of Variable Modifiers||&||&|
Variables will be replaced by values taken from the corresponding fields of the current Note, or from an internal table of global variables. Variables must be enclosed in the chosen delimiters. Each variable name must match a field label from the data source, or a global name specified in a SET command. The comparison ignores case (upper or lower), embedded spaces and embedded punctuation when looking for a matching field label. So a field label of “First Name” will match with a variable of “firstname”, for example.
A variable, unlike a command, can appear anywhere within the template file, and need not be isolated on a line by itself. More than one variable can appear on the same line. Variables can be used within template commands, as well as other places within the template file.
The following special variables are predefined and available for substitution, no matter what data source is being used.
A variable can be optionally followed (before the ending variable delimiters) by a modifier indicator and one or more modifiers. The default modifier character is the ampersand (&).
The following list summarizes the primary use of various letters and characters as variable modifiers.
|B||Base File Name|
|K||Hour of Day|
|M||Month or Minutes|
|O||Markdown to HTML|
|R||Keep characters on the right|
|R||Readable File Name|
|dd||Day of Month|
|EEE||Day of Week, Abbreviated|
|Dash||Remove Paragraph Tags|
|EEEE||Day of Week|
Following is a list of the variable modifiers with complete descriptions of how each works.
Placing a single apostrophe as part of the variable modifiers string will cause any HTML entities representing an apostrophe to be converted back to a normal ASCII/UTF apostrophe character: '. This can be useful for generating HTML to use as e-mail content, since e-mail parsers seem to sometimes drop the HTML entities commonly used for apostrophes.
Any punctuation character, other than ones specificaly called out in this list for other purposes, will be interpreted as a separator that will be placed before the current variable, if the variable is non-blank, and if the preceding variable was also non-blank and also marked by the same variable modifier. A space will be added after the separator, and before the current variable, if the punctuation is not a forwards or backwards slash (“/” or “\”). This is an easy way to list several variables on a single line, separating non-blank ones from others with commas (or other punctuation).
One or more consecutive digits within the modifiers will be interpreted as the length to which the variable should be truncated or padded. If the length modifier is shorter than the variable length, then by default characters will be truncated on the right (and preserved on the left) of the variable to bring it to the specified length. If it is desired to keep characters on the right, then also use the “R” modifier and place it before the length modifier digits. If the length modifier is longer than the initial variable length, then the variable will be padded with zeroes on the left to bring it to the specified length.
The letter “B” will cause the file extension, including the period, to be removed from a file name. This can be used, for example, to generate an output file name with the same name as the input data file (using the variable name “datafilename”), but with a different extension.
The letter “C” indicates that the variable consists of a series of words, and you wish to change or standardize the way in which the words are distinguished from one another.
When parsing the variable, the beginning of a new word will be indicated by either whitespace or punctuation between words, or by a transition from lowercase to uppercase (as in CamelCase usage). In other words, “two words”, “TWO_WORDS” or “twoWords” would all be parsed into two separate words.
What you want done with the word demarcation is defined by the characters following the “C” in the modifiers string. The letter “u” indicates a conversion to uppercase, the letter “l” indicates a conversion to lowercase, and the letter “a” indicates that the character should be left as-is. Anything other than these three characters (including a space) will be interpreted as a separator to be placed between the words.
Note that the u/l/a indicator can be specified three different times.
For example, if the template file contained the following:
And the name variable was equal to:
Then the resulting name in the output text file would be:
Converts a string to a conventional, universal file name, changing spaces to dashes, removing any odd characters, making all letters lower-case, and converting white space to hyphens.
Each tag found in the variable will be made into a link, linking to ‘=$relative$=yypathyy/xxtagxx.html’, where ‘xxtagxx’ is the tag, and ‘yypathyy’ is the string of characters following the ‘g’.
The letter “H” will cause selected special characters to be translated to their equivalent HTML entities.
When the letter ‘I’ immediately follows an ‘L’ or a ‘U’, then the case transformation (lower or upper) will only be applied to the initial letter of the variable.
Convert a URL to an HTML anchor tag with that URL as the href value.
Two lowercase 'k's will represent a 2-digit hour of the day on a 12-hour clock, within a date formatting string.
Two uppercase 'K's will represente a 2-digit hour on a 24-hour clock.
Converts the letters of the variable to lowercase. If immediately followed by ‘I’, then only the initial letter of the variable will be changed to lowercase.
Used in a date formatting string, with the following effects:
Remove HTML break (br) tags from the string.
The letter “O” will cause the field to be treated as Markdown, and converted to HTML.
Following this letter with a minus sign (‘-’) will cause any opening and closing paragraph tags (
</p> respectively) to be stripped from the resulting field (thus reducing the chance for possible conflicts with other tags).
Remove awkward punctuation characters.
This letter will cause the value to be enclosed in quotation marks, if the value contains quotation marks, or tabs, or newline characters.
The letter “R”, in combination with a length modifier, will cause the variable to be truncated to the given length, truncating characters on the left and keeping characters on the right.
The letter “R”, following the letter “F”, will cause the variable to be converted to a safe file name, but preserving as much human readability as possible.
The letter “S” will pull the first few sentences from the field, within the first 250 characters. Specifying a number immediately following the “S” will override the default of 250 with the specified number.
Converts the letters of the variable to uppercase (capital letters). If immediately followed by ‘I’, then only the initial letter of the variable will be changed to uppercase.
The first character following the ‘v’ will be used as a delimiter. Everything between the delimiters will be used as a from field. Everything following the second delimiter will be used as a to field. All output lines will be scanned for occurrences of the from field, and will be replaced with the to field.
If your input is coming from a Collection using wiki-style inter-note links (links to other Notes formed by placing the Title of the target note within double square brackets), then you will probably wish to convert these to functional links in your output.
You can accomplish this by using the letter “W” as a variable modifier to modify the Markdown code containing inter-note links. The “W” must then be followed by one of the following values.
1 - The digit ‘1’ will cause the target Note title to be converted to a conventional, universal file name, changing spaces to dashes, removing any odd characters, making all letters lower-case, and converting white space to hyphens. The ‘.html’ file extension will then be appended as a suffix. This option can be used when each note has its own page.
2 - The digit ‘2’ will cause the Note title to be similarly converted, but then have a ‘#’ prepended, with no suffix added. This option can be used when each note has its own heading within the same page.
Note that the ‘W1’ / ‘W2’ option should be specified before the letter ‘O’ requesting the conversion from Markdown to HTML.
The letter “X” will cause selected special characters to be translated to their equivalent XML entities. This is recommended, for example, when publishing an RSS (Really Simple Syndication) feed.
An underscore character (“_”) will cause all spaces in the variable to be replaced by underscores. This can be useful when creating a file name, for example. Leading and trailing spaces will be trimmed without replacement.
Represents an AM/PM indicator within a date formatting string.
Used within a formatting string, with the following effects:
Represents a two-digit day of month within a date formatting string.
Represents an abbreviated, 3-character, day of week within a date formatting string.
When used following the letter ‘o’, indicating conversion from Markdown to HTML, a dash (‘-’) indicates that leading and trailing paragraph tags should be stripped from the output.
Represents a full day of week within a date formatting string.
A string of characters indicating how the variable is to be formatted. The formatting string, if specified, should follow any other variable modifiers. Any character other than the modifiers listed above will cause the remainder of the variable modifiers to be treated as a formatting string. Currently, a formatting string is valid only for dates – either for the special variable today, or for any variable date in “mm/dd/yy” format.
A date formatting string follows the normal rules for Java date formatting. One or more occurrences of an upper-case “M” indicates a month, a lower-case “y” is used for a year, and a lower-case “d” is used for the day of the month. An upper-case “E” can be used for the day of the week. Generally, the number of occurrences of each letter you specify will be used to indicate the width of the field you want (“yyyy” for a 4-digit year, for example). Specifying more than two occurrences of “M” indicates you want the month represented by letters rather than numbers, with 4 or more occurrences indicating you want the month spelled out, and 3 occurrences indicating you want a three-letter abbreviation.
See below for full definition of allowable characters and their meanings.
|M||month in year||Text & Number||July & 07|
|d||day in month||Number||10|
|h||hour in am/pm||1~12||12|
|H||hour in day||0~23||0|
|m||minute in hour||Number||30|
|s||second in minute||Number||55|
|E||day in week||Text||Tuesday|
|D||day in year||Number||189|
|F||day of week in month||Number||2 (2nd Wed in July)|
|w||week in year||Number||27|
|W||week in month||Number||2|
|k||hour in day||Number||24|
|K||hour in am/pm||Number||0|
|z||time zone||Text||Pacific Standard Time|
|'||escape for text||Delimiter|
The count of pattern letters determine the format.
(Text): 4 or more pattern letters–use full form, < 4–use short or abbreviated form if one exists.
(Number): the minimum number of digits. Shorter numbers are zero-padded to this amount. Year is handled specially; that is, if the count of ‘y’ is 2, the Year will be truncated to 2 digits.
(Text & Number): 3 or over, use text, otherwise use number.
Any characters in the pattern that are not in the ranges of [‘a’..‘z’] and [‘A’..‘Z’] will be treated as quoted text. For instance, characters like ‘:’, ‘.’, ‘ ’, ‘#’ and ‘@’ will appear in the resulting time text even they are not embraced within single quotes.
All commands must be enclosed in the chosen delimiters. In addition, all commands must appear on lines by themselves. Command names can be in upper- or lower-case. Each command may have zero or more operands. Operands may be separated by any of the following delimiters: space, comma (‘,’), semi-colon (‘;’) or colon (‘:’). Operands that contain any of these delimiters must be enclosed in single or double-quotation marks.
The following commands are recognized. They are presented in the typical sequence in which they would be used.
<?delims new delimiters?>
<?set global = 0?>
<?include "filename.ext" ?>
<?definegroup group-number ?>
If used at all, this command should be the first command in the template file. This command overrides the standard delimiters used to recognize the beginnings and ends of commands and variables, for the remainder of the current template file. The command can have one to five operands. Each operand will become a new delimiter. They should be specified in the following order.
Note that, in addition to specification of the delims command, the first characters found on the first line of the template file can trigger the Notenik template processor to use an alternate set of delimiters.
This command can define a global variable and set its value. This command would normally have three operands: the name of the global variable, an operator, and a value.
Global variable name. This should not be the same as the name of any variable name specified by the input data file. The global variable name, when used as the object of a set command, should not be enclosed within the normal variable delimiters, since this would cause the variable name to be replaced by its current value.
Operator. Any of the following operators can be used.
= — This will cause the global variable to be set equal to the following value.
+= or simply + — This will cause the value to be added to the current value of the global variable.
++ — This can be used to add a value of 1 to the current value of the global variable, without having to specify the following value of 1. (In this case, the set command only takes two operands.)
-= or simply - — This will cause the value to be subtracted from the current value of the global variable.
-- Two minus signs in a row can be used to subtract a value of 1 from the current value of the global variable, without having to specify the following value of 1. (In this case, the set command only requires two operands.)
Value. This can be a literal or a variable (in which case it should be surrounded by the normal variable delimiters). The value can be a text string or an integer.
One intended use for the set command is to support a line counter. By initializing the value to 0, and then adding to it whenever an output line is generated, the IF command can be used to check for page overflow (in a table column, for example), and then start a new page or column, resetting the counter to 0 again.
Another common use for the set command is to preserve record variables in global variables so that they will be available within an ifendgroup block.
This command names and opens the output file, where the results of the template merge will be stored. The single operand is the name of the output file. This command would normally be the first line in your template file. Subsequent template records will be written to the output file.
Note, however, that the filename can contain a variable name. In this case, the output command would follow the nextrec command, and a new output file would be opened for each row input.
This command indicates the beginning of the code that will be processed/written out once per data row. Lines prior to the nextrec command will only be processed/written out once.
This is the first of five commands that define key fields and then conditionally write output when there is a break on any of those fields.
Up to ten group break fields can be defined. Each must be assigned a number from 1 to 10. Numbers should be assigned sequentially beginning with 1.
Input data should normally be sorted by the same fields used in any definegroup commands.
A definegroup command should normally follow a nextrec command. Each time that a definegroup command is encountered, Notenik stores the value of the variable, and checks for a change in the value for the specified group number.
Definegroup commands should precede ifendgroup and ifnewgroup commands, and should generally be specified in ascending order by group number.
The definegroup command has two operands.
Group Number. This must be a number from 1 to 10. Numbers should be assigned sequentially beginning with 1. Lower-numbered groups are considered more major than higher-numbered groups, in the sense that lower-numbered group breaks will automatically trigger higher-numbered group breaks.
Variable Name. This is the name of the key field variable. The variable should be surrounded by the normal variable delimiters, so that Notenik will see, not the name of the variable, but its current value.
This is the second of the five group commands.
Lines following this command and preceding the next group or endif command will be written to the output file at the end of a group of records sharing a common value for this key field.
Ifendgroup commands should follow definegroup commands and precede ifnewgroup commands, and should generally be specified in descending order by group number.
The ifendgroup command has one operand.
The trailing command can be used to eliminate a trailing delimiter, or replace it with another character.
For example, if previous lines have been written out with a series of names, each followed by a comma, then a trailing command could be used after an ifendgroup command to eliminate the last comma written out (or replace it with a closing parenthesis).
The trailing command requires one operand, and allows a second operand.
The first operand specifies a trailing character to be removed or replaced. A backwards search from the end of the output already produced will look for the the specified character. Whitespace and newline characters will be ignored. Any other character will terminate the search. If the specified character is found in a trailing position, then it will be removed. If a second operand is specified, then that character will serve as the first character's replacement. Note that the word “comma” may be spelled out as the first operand in order to search for a trailing comma. (Simply using the comma character will not work, since this will be interpreted as a delimiter between the operands of the command.)
A second operand, if specified, will serve as a replacement for the character specified by the first position.
This is the third of the five group commands.
Lines following this command and preceding the next group or endif command will be written to the output file at the end of a list of records containing this key field.
The end of a list will be triggered by a change in key values at the next higher level, or by a record containing blanks at the current group level.
Ifendlist commands should follow ifendgroup commands and precede ifnewlist commands, and should generally be specified in descending order by group number.
The ifendlist command has one operand. Note that the ifendlist and ifnewlist commands can generally be used to insert HTML tags to end a list and begin a list.
Note that references to record variables within an ifendlist block will retrieve the data from the record causing the break (i.e., the first record in the new group), not the last record in the group just ended. Use the set command to save data in global variables if you need to later access it when a list break has been detected.
This is the fourth of the five group commands.
Lines following this command and preceding the next group or endif command will be written to the output file at the beginning of a new list of records at this group level.
Ifnewlist commands should follow definegroup, ifendgroup and ifendlist commands, should precede ifnewgroup commands, and should generally be specified in ascending order by group number. The ifnewlist command has one operand.
This is the fifth of the five group commands.
Lines following this command and preceding the next group or endif command will be written to the output file at the beginning of a group of records sharing a common value for this key field.
Ifnewgroup commands should follow all other group commands, and should generally be specified in ascending order by group number.
The ifnewgroup command has one operand.
The if command can be used to test a variable to see if it is non-blank. If the variable is non-blank, then the following lines up to the closing endif command will be subject to normal output processing. If the variable is blank, then following lines will be skipped until the closing endif command is encountered. In this case, the first and only operand would be the variable to be tested.
The if command can also be used to test a variable to compare it to a constant (or other variable). In this case, the command would have three or more operands: the name of the variable, a logical operator, and one or more values.
In this second scenario, three operands are provided: the first value (variable or constant), a comparison operator, and the second value (variable or constant).
Any of the following comparisons may be performed, and each may be invoked with the appropriate symbols, abbreviation or words. Note that slashes are used in the following list to separate alternative representations for each operator.
Note that, if both values appear to be integers, then a numeric comparison will be performed for operands 1 - 6. In all other cases, strings will be compared.
The else command terminates the scope of its preceding if, ifchange, ifendgroup or ifnewgroup command, and applies the opposite logical condition to the following template lines.
The endif command terminates the scope of its corresponding if, ifchange, ifendgroup or ifnewgroup command.
This command allows you to include text from another file into the output stream being generated by the template.
An optional operand of “copy” will ensure that the include file is included without conversion; otherwise, if the input and output file extensions are different, and are capable of conversion, the input file will be converted to the output file's format (for example, Markdown or Textile can be converted to html).
Markdown conversion will be done using the flexmark processor, using the options for typographic conversions (as with SmartyPants), table generation and definition lists.
Textile conversion will be done using Notenik's own Textile processor which is, admittedly, incomplete, and yet may still be useful for some users.
If converting from Markdown, then an optional operand of “nometa” will cause metadata lines to be skipped when generating the HTML output; otherwise, they will be included.
The filename may include variables, allowing you to tailor the included content based on one or more fields from your input data source. This is especially useful when you would like to include output from another template in the output generated by this template (effectively combining outputs from two separate templates into a single output). If an include file is not found, then it will simply be skipped and processing will continue, with a log message to note the event.
For any conversion resulting in HTML, a pseudo-tag of <toc> can be used to generate a table of contents based on following heading tags. An optional attribute of “from” can be used to specify the beginning of a range of heading levels to be included; an optional attribute of “through” or “thru” can be used to specify the end of a range of heading levels to be included. See the following example.
<toc from="h2" thru="h4" />
This command indicates the end of the code that will be processed/written out once per data row. Lines after the loop command will be processed/written out once per execution.