Hi All I've a attached a proposal for installing and removing AsciiDoc filters. Comments please.
I haven't addressed the important question of how to publish and distribute filters. Maybe a noticeboard where it's easy for authors to register their filters -- then they would be free to host them on Google Code, Github or whereever. This is not something I have the time to get involved in. My motivation is also driven by self interest: this will free me from having to act as filter custodian and from having to maintain and ship new filters with the AsciiDoc distribution. WARNING: I may be getting ahead of myself here -- I haven't implemented any code yet, hopefully I'm not painting myself into a corner. Cheers, Stuart -- You received this message because you are subscribed to the Google Groups "asciidoc" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/asciidoc?hl=en.Title: AsciiDoc Filter Plugins
AsciiDoc Filter Plugins
AsciiDoc filters provide an external mechanism for transforming source blocks of text in AsciiDoc source files to arbitrary markup in the output files.
There is currently no mechanism that makes it easy to distribute, install and remove filters. This proposal describes a set of conventions and additional asciidoc(1) command options to bridge this gap.
Filters are an extension mechanism (plugin) and should be separate. The advantages of plugins are well documented.
The mechanism I’m proposing is, above all, simple: filter resources are distributed in a Zip file; installation is just a matter of unzipping to an AsciiDoc filters directory. It would be up to the filter designer to perform runtime (dependency) checks and warnings.
Filter commands
A new --filter option would be added to asciidoc(1) to install, remove and list filters:
asciidoc --filter install ZIP_FILE [FILTERS_DIR] asciidoc --filter remove FILTER_NAME asciidoc --filter list
Where:
- FILTER_NAME
-
Each filter has a unique name matching the regular _expression_ [a-zA-Z]\w*.
- ZIP_FILE
-
The filter Zip file name must start with the filter name e.g. my_filter-1.0.zip packages filter my_filter.
- FILTERS_DIR
-
Filters are installed into a same-named subdirectory of the FILTERS_DIR directory (FILTERS_DIR defaults to the local $HOME/.asciidoc/filters directory).
The commands perform as follows:
- install
-
Create a subdirectory in FILTERS_DIR with the same name as the filter then extract the ZIP_FILE into it.
- remove
-
Delete the FILTER_NAME filter directory and all its contents.
- list
-
List the names of installed filters.
Examples:
$ asciidoc --filter install myfilter.zip $ asciidoc --filter remove myfilter $ asciidoc --filter list code graphviz latex music source |
Filter Zip file contents
A minimal filter would consist of an AsciiDoc configuration file and a short README text file, for example:
myfilter.conf README |
There is no formal restriction on what files should or can be included. Best practices will emerge informally with practise and experience. For example:
-
You may decide to include filter documentation or you may prefer to host documentation externally.
-
The excutable filter command might be included or it might be an external depenency.
Last updated 2011-02-05 10:49:17 NZDT
