17 Extending deplate

A deplate document consists of elements (i.e., single lines or group of lines) that are made up of particles (sub-line-level text bits).

17.1 Line/Elements

Elements are processed in several passes:

• accumulate a new element; it’s type is infered from the first line
• add other lines
• “finish” the element (unify with previous elements if applicable)
• process the element (at this point of time, all data/references etc. are known)
• output the formatted element (at this point of time, all elements were processed)

17.2 Text/Particles

Particles are processed in two passes:

• create an object and parse the text
• process the element and return a formatted string

17.2.1 Symbols

If you don’t want to define symbols using #ABBREV in your source file (maybe because of performance considerations), you can make them available by creating a file like ~/.deplate/after/fmt/#{FORMATTER}/mysymbols.rb, which contains something like the following HTML example:

# Set the context for where we want to store our symbol definitions, 
# here: HTML output format
class Deplate::Formatter::HTML
    # Create a hook function (the name must begin with 
    # "formatter_initialize_")
    def formatter_initialize_my_symbols
        # Define our symbols. We could either create a hash and merge it 
        # with the already defined @special_symbols or add each entry with 
        # a single command as in this example
        @special_symbols['€'] = '€'
        @special_symbols['Ä'] = 'Ä'
        # We need to rebuild the regular expression used for tokenizing
        build_plain_text_rx
    end
end

# Set the context: LaTeX output format
class Deplate::Formatter::LaTeX
    def formatter_initialize_my_symbols
        @special_symbols['€'] = '\EURtm{}'
        @special_symbols['Ä'] = '\"A{}'
        build_plain_text_rx
    end
end 

Be aware though that this file will not be loaded when using a HTML variant like the htmlsite formatter. If you want to make these symbols be available in all descendants of the HTML formatter, you will have to move this ruby code to ~/.deplate/config.rb.

17.2.2 Macros

For adding a new macro, you would have to put something like this into your config.rb3:

class Deplate::Macro::MyMacro < Deplate::Macro
    @@macros["mymacro"] = self
    def setup(text)
        @text = text * 3
    end
end

Or use the simple_macro function/method as in:

The macro is now accessible.

Foo {mymacro: bar}

This would then produce:

Foo barbarbar

17.3 Formatters

Sometimes, the best way to change deplate‘s output is to create a new formatter. Let’s take the html-snippet formatter as an example. This formatter derives from the HTML formatter but has a different name and doesn’t format paragraphs (the assumption is that this formatter is only used for small text snippets which are later on reused by an other application):

You could now save this code in, say, ~/.deplate/fmt/html-snippet.rb4 and invoke the newly defined formatter from the command line:

> echo '__Foo__ "bar".' | deplate -f html-snippet --included -
<em>Foo</em> &ldquo;bar&rdquo;.