From: Angel Yanguas-G. <ang...@gm...> - 2012-04-30 04:45:50
|
Hi, I have been playing with docutils and I have created a new role :chem:, to process subscripts and superscripts for chemical formula (i.e. :chem: or :ch:`Al2O3` == Al<sub>2</sub>O<sub>3</sub>). It worked, and now I have it running in my local copy. However, I still have a couple of questions: 1) So far I have included it in my local copy of roles.py. Is there any other way of loading custom roles / add-ons to distutils that does not involve modifying roles.py? (like a local directory where custom roles could be added/imported into distutils?). 2) Is nodes.Text the standard way of returning a text node? 3) Can roles be made to work recursively? In other words, am I missing a simple way of calling a role within a role (i.e. so that I can expand Al2O3 into "Al :subs:`2`\ O:subs:`3`\ " and that magically everything is taken care of)?. 4) Is a role the best way of doing this? Should I be using a directive instead, or is it an overkill? Many thanks, ay |
From: Guenter M. <mi...@us...> - 2012-05-04 07:57:01
|
On 2012-04-30, Angel Yanguas-Gil wrote: > Hi, > I have been playing with docutils and I have created a new role >:chem:, to process subscripts and superscripts for chemical formula > (i.e. :chem: or :ch:`Al2O3` == Al<sub>2</sub>O<sub>3</sub>). Looks interesting. > It worked, and now I have it running in my local copy. However, I > still have a couple of questions: > 1) So far I have included it in my local copy of roles.py. Is there > any other way of loading custom roles / add-ons to distutils that does > not involve modifying roles.py? (like a local directory where custom > roles could be added/imported into distutils?). There is currently no plug-in mechanism in Docutils and no clear plan how to implement one in a clean and secure manner. The usual practice is to use a custom front-end, load Docutils and customize it before calling the publisher functions. See the sandbox for examples of this approach (e.g. the now obsolete sandbox/code-block-directive/rst2html-highlight.py). Adding directives this way is documented: there is a "register directive" API. For roles, I see ``register_canonical_role(name, role_fn)`` in roles.py. The downside is that this approach does not scale well: * you need one modified front-end for every output format, * you cannot easily combine extensions (say html4_strict for valid XHTML 1.1 and rstdiff for diffs of rst files). > 2) Is nodes.Text the standard way of returning a text node? I think so. Look at the source how other roles do this. As return value of the role, I'd use an `inline` node as container (and give it a class argument to allow styling) and nest the `Text` and `subscript` nodes. > 3) Can roles be made to work recursively? In other words, am I missing > a simple way of calling a role within a role (i.e. so that I can > expand Al2O3 into "Al :subs:`2`\ O:subs:`3`\ " and that magically > everything is taken care of)?. I'd search the source to find out how to call the "subs role function" with the number as argument and nest the returned node in the inline node. > 4) Is a role the best way of doing this? Should I be using a directive > instead, or is it an overkill? A role is well suited for inline formulas. If you want block-level (display) formulas as well, add a directive. Günter |
From: Angel Yanguas-G. <ang...@gm...> - 2012-05-09 17:06:13
|
Thanks for your input. Nesting the nodes in an inline node is a good idea, so far I was returning them as a list, but an inline node is a more elegant solution. I will definitely check out the sandbox for front-end customization. Angel On Fri, May 4, 2012 at 2:56 AM, Guenter Milde <mi...@us...> wrote: > On 2012-04-30, Angel Yanguas-Gil wrote: >> Hi, > >> I have been playing with docutils and I have created a new role >>:chem:, to process subscripts and superscripts for chemical formula >> (i.e. :chem: or :ch:`Al2O3` == Al<sub>2</sub>O<sub>3</sub>). > > Looks interesting. > >> It worked, and now I have it running in my local copy. However, I >> still have a couple of questions: > >> 1) So far I have included it in my local copy of roles.py. Is there >> any other way of loading custom roles / add-ons to distutils that does >> not involve modifying roles.py? (like a local directory where custom >> roles could be added/imported into distutils?). > > There is currently no plug-in mechanism in Docutils and no clear plan how to > implement one in a clean and secure manner. > > The usual practice is to use a custom front-end, load Docutils and > customize it before calling the publisher functions. See the sandbox for > examples of this approach (e.g. the now obsolete > sandbox/code-block-directive/rst2html-highlight.py). > > Adding directives this way is documented: there is a "register directive" API. > For roles, I see ``register_canonical_role(name, role_fn)`` in roles.py. > > The downside is that this approach does not scale well: > > * you need one modified front-end for every output format, > > * you cannot easily combine extensions (say html4_strict for valid > XHTML 1.1 and rstdiff for diffs of rst files). > > >> 2) Is nodes.Text the standard way of returning a text node? > > I think so. Look at the source how other roles do this. > > As return value of the role, I'd use an `inline` node as container (and > give it a class argument to allow styling) and nest the `Text` and > `subscript` nodes. > >> 3) Can roles be made to work recursively? In other words, am I missing >> a simple way of calling a role within a role (i.e. so that I can >> expand Al2O3 into "Al :subs:`2`\ O:subs:`3`\ " and that magically >> everything is taken care of)?. > > I'd search the source to find out how to call the "subs role function" > with the number as argument and nest the returned node in the inline node. > >> 4) Is a role the best way of doing this? Should I be using a directive >> instead, or is it an overkill? > > A role is well suited for inline formulas. > If you want block-level (display) formulas as well, add a directive. > > Günter > > > ------------------------------------------------------------------------------ > Live Security Virtual Conference > Exclusive live event will cover all the ways today's security and > threat landscape has changed and how IT managers can respond. Discussions > will include endpoint security, mobile security and the latest in malware > threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/ > _______________________________________________ > Docutils-users mailing list > Doc...@li... > https://lists.sourceforge.net/lists/listinfo/docutils-users > > Please use "Reply All" to reply to the list. |