7.5 Processing special characters in text

Some characters are processed especially in text: ‘---’, ‘--’, ‘``’ and ‘''’. This is done only if in normal text and not in some commands (@code, @env…). A function reference is called to process the text and should take care of those constructs. It may also be used to transform the text, for example set it in upper case if it is in @sc. This function should also take care of protecting special characters

Function Reference: $processed_text normal_text $text $in_raw_text $in_preformatted $in_code $command_stack

The function processes $text and returns $processed_text. The other arguments give some information about the context of the text. $in_raw_text is true if the text appears in special place where there is no formatting, typically in comments. $in_preformatted is true if in a preformatted environemnt, and $in_code is true if in a special command like @code, @env where ‘---’, ‘--’, ‘``’ and ‘''’ should not be touched. $command_stack is an array containing the name of the formatting @-command that enclose the text.

In the default case the ‘---’, ‘--’, ‘``’ and ‘''’ constructs are expanded if needed and the text is upper-cased if in @sc. Special characters (‘&’, ‘"’, ‘<’ and ‘>’ in HTML) are protected if needed.

Some characters are special, for example we have ‘&’, ‘"’, ‘<’ and ‘>’ in HTML. In some cases some pieces of text don't go through the above function, but still needs to be protected to appear in text. This is done by the function associated with the function reference

Function Reference: $protected_text protect_text $text

The function processes the unprotected text $text and returns the resulting protected text $protected_text.

Empty lines are processed by the following function reference, which could be usefull if empty lines are to be removed for example

Function Reference: $resulting_text empty_line $empty_line $state

This function processes an $empty_line and returns the resulting text $resulting_text. $state is a structure that holds informations about the state of the parsing. Empty lines are left as is by default except right after a definition @-command.

Doku-Base