From: <mn...@us...> - 2007-12-18 19:05:33
|
Author: mnodine Date: 2007-12-18 20:05:17 +0100 (Tue, 18 Dec 2007) New Revision: 5483 Modified: trunk/prest/doc/src/prest_extend.rst Log: * Added documentation on the ``init`` routine for plug-in directives and roles. * Added a section on Adding New Roles. Modified: trunk/prest/doc/src/prest_extend.rst =================================================================== --- trunk/prest/doc/src/prest_extend.rst 2007-12-18 19:03:14 UTC (rev 5482) +++ trunk/prest/doc/src/prest_extend.rst 2007-12-18 19:05:17 UTC (rev 5483) @@ -16,7 +16,7 @@ This document explains how to write new modules to extend prest. There are two principal mechanisms by which prest can be extended: adding new -plug-in directives and adding new writers. For either of these tasks, +plug-in directives/roles and adding new writers. For either of these tasks, the programmer should be familiar with the DOM_ data structure and the `DOM.pm`_ subroutines. @@ -35,9 +35,14 @@ A plug-in directive can be added by creating a Perl module with the same name as the directive (with a ".pm" extension, of course). The -Perl module must have a BEGIN block which registers the routine to -call to process the directive using -`Text::Restructured::Directive::handle_directive`_. +Perl module should have an ``init`` routine which registers the +routine to call to process the directive using +`Text::Restructured::Directive::handle_directive`_ (though this call +can also be in a BEGIN block). The ``init`` routine is called with +the arguments ``($parser, $source, $lineno)``, where +``$parser`` is the ``Text::Restructured`` object, ``$source`` is the +name of the file containing the directive,, and ``$lineno`` is the +line number within ``$source``. As an example from the ``if`` plug-in directive, @@ -103,6 +108,18 @@ The help text should parse correctly as reStructuredText, since it is passed through prest to create the web documentation. +Adding New Roles +--------------------- + +A plug-in role can be added by creating a Perl module with the same +name as the role (with a ".pm" extension, of course). The Perl module +should have an ``init`` routine which registers the role using the +parser's `Text::Restructured::DefineRole`_ method. The ``init`` +routine is called with the arguments ``($parser, $source, $lineno)``, +where ``$parser`` is the ``Text::Restructured`` object, ``$source`` is +the name of the file containing the directive,, and ``$lineno`` is the +line number within ``$source``. + Adding New Writers ------------------ |