7.4 Formatting of special simple commands

The formatting of special simple commands is controlled by functions. To customize the output, the corresponding function references should be redefined. All these functions return a formatted text.

The formatting of anchors is controlled by $anchor, but the function associated with the function reference does more, it is usefull to produce a reference target or link.

Function Reference: $anchor anchor $identifier $href $text $attributes

If $identifier is not empty, this value should be used to create a target for links (typically associated with a name or id attribute in HTML). The $href argument specifies a hpertextual reference which should be used to link to a target. In case both $identifier and $href are given the text produced should be both a target for $identifier and a link to $href. $text is the text to be displayed. $attributes are additional attributes. It should be reasonable to assume that the attributes are for a <a> HTML element.

To customize the images produced by @image, the first possibility is to modify the @IMAGE_EXTENSIONS, which holds a list of filename extensions for image files. It is also possible to redefine the function used to determine the filename of the image:

Function Reference: $filename image_files $basename $extension

$basename is the first @image argument, $extension is the corresponding @image argument. This function reference should return an array of image filenames without path that the main program should look for.

Last, it is possible to control the formatting of @image by redefining:

Function Reference: $image image $file_path $basename $preformatted $file_name $alt_text $width $height $raw_alt $extension $working_dir $file_path

$file_path is the image file name with the path, $basename the file name without extension. $preformatted is true if the image appears in preformatted text. $file_name is the file name without path but with extension. $alt_text is the alternate text, it may be undefined. $width and $height are the corresponding arguments of @image, $raw_alt is the unmodified alt argument of @image and $extension holds the corresponding @image argument. $working_dir is the path to working dir relative to the output directory. $file_path is the file name relative to the $working_dir.

The formatting of @sp is controlled by:

Function Reference: $sp sp $number $preformatted

$number is the numeric argument of @sp. $preformatted is true if the @sp appears in preformatted text.

The formatting of @acronym and @abbr is controlled by:

Function Reference: $acronym acronym_like $acronym_texi $acronym_text $with_explanation \@explanation_lines $explanation_text $explanation_simply_formatted

$acronym_texi is the acronym argument with texinfo @-commands, $acronym_text is formatted.

The other arguments are related with the explanation, the second arg of the acronym. $with_explanation is true if the second argument of the acronym command is present. If an explanation exists, coming from previous @acronym or as an arg of this command, the other args are defined: \@explanation_lines is a reference on an array containing the simply fomatted explanation lines, $explanation_text is the explanation text formatted, $explanation_simply_formatted is the explanation with a light formatting, unabling in HTML (or XML) the explanation to be in an attribute.

Doku-Base