7.3 Customizing accent, style and other simple commands

The formatting of the HTML produced by style and indicatric commands (@tt, @code, @email, @titlefont), the accentuation related commands taking argument (@', @udotaccent, @dotless) and miscalleneous commands (@email, @verb, @w, @uref, @math, @asis) is controlled by two hash in the default case, %style_map for normal context, %style_map_pre for preformatted context and %style_map_texi in string context.

The key of the hashes are the command names. There are two possibilities for the values corresponding with two interfaces. The values may be strings or hash references, and you can chose the interface depending on the one you prefer. The interface with hash reference is a bit more flexible but might also be regarded as more complex. If you don't like either of these interfaces you can define your own.

Some remarks are in order:

• The nonlettered accent commands which following character is considered to be the argument (like in @`a) should be keys of the hash %accent_map hash, even if no value is associated.
• @math is handled differently if LaTeX2HTML is used.

7.3.1 An interface for commands formatting with a hash reference

The key of the hashes are the command names. The value determine how the command argument is formatted. This value is a reference on a hash. In this hash each key corresponds with a type of information for the formatting, and the value is the corresponding information. For example, in

$style_map{'command'} = { 'args' => ['code'], 'attribute' => 'code'};

the arguments for @command are interpreted as specified by the values associated with the ‘args’ key while the attribute associated with that command is ‘code’.

The following keys in the hashes associated with each command have the following meaning:

‘args’

The value associated is a reference on an array. Each element of the array defines how the arguments (separated by ‘,’ in the texinfo code) for the @-command should be formatted. The possibilities are

normal

for normal text,

code

for text with ‘---’, ‘--’, ‘''’ and ‘``’ kept as is,

keep

if the texinfo should be kept as is, without interpretation of the @-commands.

For example, we have

$style_map{'email'}->{'args'} = ['code', 'normal'];

because ‘---’, ‘--’, ‘''’ and ‘``’ should be kept as is in the first argument of @email.

The default is ‘['normal']’.

‘attribute’

If the associated value is a word, it is considered to be an HTML element name, and the argument is enclosed between the element opening and the element closing. For example, if the value is elem, the resulting HTML is <elem>arg</elem>.

If the text is a word followed by some text, the word and is interpreted as above, and the text is considered to be the attributes text of the element. Thus elem class="elem" leads to <elem class="elem">arg</elem>.

This works only if there is only one argument.

‘begin’

The associated value is added in front of the text.

‘begin’

The associated value is added after the text.

‘quotes’

If the corresponding value is true, the result is enclosed in quotes $OPEN_QUOTE_SYMBOL and $CLOSE_QUOTE_SYMBOL, with defaults ‘`’ and ‘'’.

‘function’

The corresponding value should be a function reference. The corresponding function is called with the following arguments:

$command

The @-command name

$args

A reference on an array containing the arguments of the @-command.

$command_stack

A reference on an array containing the name of the @-commands containing the @-command being formatted, latest on top.

$state

A reference on a hash containing a lot of informations about the context of the @-command.

$line_nr

An opaque structure containing the information about the line number of the @-command. It can be used to call main::echo_error or main::echo_warning with first argument a message, and second argument $line_nr.

7.3.2 An interface for commands formatting with a string

The keys of the hashes are the command names. The value determine how the command argument is formatted. If the value begins with ‘"’, the result is enclosed in quotes $OPEN_QUOTE_SYMBOL and $CLOSE_QUOTE_SYMBOL, with defaults ‘`’ and ‘'’.

The command argument is allready formatted as HTML. The remaining of the value text (or the value text if there were no ‘"’) is interpreted as follow:

• If the text is empty the argument of the command is left as is.
• If the text is a ‘&’ followed by a name, like ‘&function’, the name is considered to be a function name, and this function is called to format the argument of the command. The first argument of the function is the command name, the second is the command argument. For example, if the value associated with the (fictituous) command @foo is &my_func and we have:

  sub my_func { my @args = split /,\s*/ $_[1]; return "$_[0]: $args[0]" if ($args[1] = 1); return "$args[0]"; }

  The result of

  @foo{truc, 1} @foo{truc, bidule}

  will be

  foo: truc truc

• If the text is a word, it is considered to be an HTML element name, and the argument is enclosed between the element opening and the element closing. For example, if the value is elem, the resulting HTML is <elem>arg</elem>. Similarly "quoted leads to `<quoted>arg</quoted>'.
• If the text is a word followed by some text, the word and is interpreted as above, and the text is considered to be the attributes text of the element. Thus elem class="elem" leads to <elem class="elem">arg</elem>.

7.3.3 Defining the style and indicatric commands interface

If you don't like this scheme, it is possible to change how those commands are processed by redefining the following function reference:

Function Reference: $resulting_text style $style $command $text $args $no_close $no_open $line_nr $state $command_stack

$command is the @-command, $style is the value associated with the $command in the %style_map, %style_map_pre or %style_map_texi hashes. The $text is the text appearing within the @-command braces. args is a reference on an array contening the command arguments formatted according to the same conventions than with the reference hash style (provided the value associated with the @-command is a hash reference with a $arg key as described in Reference hash args). If $text is split in paragraphs each paragraph is passed through the function, and $no_close is true if it is not the last paragraph, while $no_open is true if it is not the first paragraph. $line_nr is an opaque structure containing the information about the line number of the @-command. It can be used to call main::echo_error or main::echo_warning with first argument a message, and second argument $line_nr. $state is a reference on a hash containing a lot of informations about the context of the @-command. $command_stack is a reference on an array containing the name of the @-commands containing the @-command being formatted.

Doku-Base