From: Mark N. <Mar...@fr...> - 2005-09-27 19:04:57
|
The documentation for the role directive keeps open the possibility that "specific roles may support other options". I would like to propose that writer-specific options be allowed on role directives to support one-time formatting problems for which it may not be economical to extend the style sheet. Here's an example, using an html writer:: .. role:: red :html: font :color: red .. role:: orange :html: font :color: orange .. role:: yellow :html: font :color: yellow .. role:: green :html: font :color: green .. role:: blue :html: font :color: blue .. role:: navy :html: font :color: navy .. role:: purple :html: font :color: purple .. role:: strike :html: strike :red:`r`\ :orange:`a`\ :yellow:`i`\ :green:`n`\ :blue:`b`\ :navy:`o`\ :purple:`w` :strike:`This text is struck through.` which produces an output like:: <p><font classes="red" color="red">r</font><font classes="orange" color="orange">a</font><font classes="yellow" color="yellow">i</font><font classes="green" color="green">n</font><font classes="blue" color="blue">b</font><font classes="navy" color="navy">o</font><font classes="purple" color="purple">w</font></p> <p><strike classes="strike">This text is struck through.</strike></p> Here, the "argument" to the ``html`` option is the tag for the output (defaults to ``span`` if not present) and any option list specifies the attributes for the tag. The designer of the roles could likewise provide a ``:latex:`` option to tell the latex writer how to render the role. Note that these all use the 'inline' tag internally. LaTeX is probably a bit easier than html, since it doesn't need close tags, so you can probably just have an argument to specify what LaTeX macro(s) to execute between ``{`` and ``}``.) For example, :: .. role:: green :html: font :color: green :latex: \color{green} :green:`Green text.` might get rendered by the latex writer as :: {\color{green} Green text.} For this approach to work, the writer will need to know what role was originally assigned to an inline element (not just the eventual class, since roles may be defined in terms of each other) and to be able to get at its writer-specific option in the role's definition. I realize this suggestion is likely to get torpedoed since it obviously crosses the line from abstract layout to specific rendering, but there are times when there really *is* no abstract concept associated with the desired rendering, such as color-coding text to match a figure or illustrating four classes of numbers in a table by giving different colors to them. What do you think? Regards, --Mark |
From: David G. <go...@py...> - 2005-09-28 13:33:51
Attachments:
signature.asc
|
[Mark Nodine] > The documentation for the role directive keeps open the possibility > that "specific roles may support other options". That should read "specific *base* roles..." (emphasis added); corrected in the docs. > I would like to propose that writer-specific options be allowed on > role directives to support one-time formatting problems for which it > may not be economical to extend the style sheet. Here's an example, > using an html writer:: > > .. role:: red > :html: font > :color: red How would this be represented in the internal document tree (i.e., using docutils.dtd)? It's very well to show the final output, but the tricky part is the internal representation. > Here, the "argument" to the ``html`` option is the tag for the > output (defaults to ``span`` if not present) and any option list > specifies the attributes for the tag. The designer of the roles > could likewise provide a ``:latex:`` option to tell the latex writer > how to render the role. What about XML output, or other? What if the specified writer is *not* being used? What is the output then (and how is this determined)? > Note that these all use the 'inline' tag internally. Please provide examples of the internal representation. > .. role:: green > :html: font > :color: green > :latex: \color{green} > > :green:`Green text.` How would *this* be represented internally? > For this approach to work, the writer will need to know what role > was originally assigned to an inline element (not just the eventual > class, since roles may be defined in terms of each other) and to be > able to get at its writer-specific option in the role's definition. I don't follow; please elaborate. Remember, the writer and parser must be kept separate, and they shouldn't need to know about each other. > I realize this suggestion is likely to get torpedoed since it > obviously crosses the line from abstract layout to specific > rendering, Yes, it does :-) > but there are times when there really *is* no abstract concept > associated with the desired rendering, such as color-coding text to > match a figure or illustrating four classes of numbers in a table by > giving different colors to them. These are valid use cases, and I've come across similar situations myself. Another possible solution may be a variation on the "raw" role, say "custom-raw". Instead of specifying the raw HTML as interpreted text, the "custom-raw" role would provide the context. Something like this: .. role:: green(custom-raw) :format: html :prefix: <font color="green"> :suffix: </font> :format: latex :prefix: {\color{green} :suffix: } :green:`example` The above would produce the following internal representation: <paragraph> <raw classes="green" format="html" xml:space="preserve"> <font color="green"> <raw classes="green" format="latex" xml:space="preserve"> {\color{green} example <raw classes="green" format="html" xml:space="preserve"> </font> <raw classes="green" format="latex" xml:space="preserve"> } Having said this, I think it's exceedingly ugly, and I'm not sure if it has any place in Docutils/reST. Rather than either of these solutions, it may be better to provide a way to specify stylesheet fragments in the document. Something like http://docutils.sf.net/docs/dev/todo.html#misc-raw perhaps: .. raw:: html :destination: style .green {color: green} .red {color: red} .natural {color: orange} .whole {color: brown} -- David Goodger <http://python.net/~goodger> |
From: David G. <go...@py...> - 2005-09-29 00:17:35
Attachments:
signature.asc
|
[Mark forgot to copy the list; I'm quoting with permission] [Mark Nodine] >>> The documentation for the role directive keeps open the >>> possibility that "specific roles may support other options". [David Goodger] >> That should read "specific *base* roles..." (emphasis added); >> corrected in the docs. >> >>> I would like to propose that writer-specific options be allowed on >>> role directives to support one-time formatting problems for which >>> it may not be economical to extend the style sheet. Here's an >>> example, using an html writer:: >>> >>> .. role:: red >>> :html: font >>> :color: red >> >> How would this be represented in the internal document tree (i.e., >> using docutils.dtd)? It's very well to show the final output, but >> the tricky part is the internal representation. [Mark Nodine] > AFAICS, the role directive leaves no direct footprints in the > doctree; it affects only the ``classes`` attribute for the > ``inline`` tag. Sorry, I meant the *usage* of the new role. True, the role directive itself doesn't change the doctree. So, given the definition above, how would the following usage be represented in the doctree? colored :red:`text` >> What about XML output, or other? What if the specified writer is >> *not* being used? What is the output then (and how is this >> determined)? > > Any writer that does not have a specific option specified for > it in the role definition should use its default rendering for > the ``inline`` tag. > >>> Note that these all use the 'inline' tag internally. >> >> Please provide examples of the internal representation. >> >>> .. role:: green >>> :html: font >>> :color: green >>> :latex: \color{green} >>> >>> :green:`Green text.` >> >> How would *this* be represented internally? > > Since the parser knows the role definition when it processes > the interpreted text, it could attach the options' information > as attributes to the ``inline`` object. Show concrete examples please. I don't want to add a bunch of attributes to existing elements, especially not format-specific attributes. It really ought to be implemented in terms of the existing document model. There is already a mechanism for format-specific content. >> Another possible solution may be a variation on the "raw" role, say >> "custom-raw". Instead of specifying the raw HTML as interpreted >> text, the "custom-raw" role would provide the context. Something >> like this: >> >> .. role:: green(custom-raw) >> :format: html >> :prefix: <font color="green"> >> :suffix: </font> >> :format: latex >> :prefix: {\color{green} >> :suffix: } >> >> :green:`example` > > I don't like the fact that the order of options is important > (e.g., what if you specify :prefix: before specifying :format:?), It could be treated as a markup error. But that's just an example for discussion. The syntax isn't the important thing though; the internal doctree representation is. Other syntax could be: .. role:: green(custom-raw) * :format: html :prefix: <font color="green"> :suffix: </font> * :format: latex :prefix: {\color{green} :suffix: } Or .. role:: green(custom-raw) html :prefix: <font color="green"> :suffix: </font> latex :prefix: {\color{green} :suffix: } IOW, the syntax could be anything we like. > but I think you're on to something here. What about something > like:: > > .. role:: green > :html-prefix: <font color="green"> > :html-suffix: </font> > :latex-prefix: {\color{green} > :latex-suffix: } The problem here is scalability. We'd have to add support for new directive options for each format. That would become really old really quickly. > :green:`example` > > having internal representation > > <paragraph> > <inline classes="green" html-prefix="<font color=\"green\"" > html-suffix="</font>" latex-prefix="{\color{green}" latex-suffix="}"> > example Same scalability problem here. We'd have to add support for format-specific attributes to the DTD for each writer, plus support for those attributes to the writers. -- David Goodger <http://python.net/~goodger> |
From: Mark N. <Mar...@fr...> - 2005-09-29 15:36:05
|
David Goodger wrote: > [Mark Nodine] > > AFAICS, the role directive leaves no direct footprints in the > > doctree; it affects only the ``classes`` attribute for the > > ``inline`` tag. > > Sorry, I meant the *usage* of the new role. True, the role directive > itself doesn't change the doctree. > > So, given the definition above, how would the following usage be > represented in the doctree? > > colored :red:`text` The problem really is trying to get communication between the role's definition and the use of the role, which is impeded by the fact that the role directive has no representation in the doctree. Just as a substitution_definition has a representation in the doctree, perhaps we should add a role_definition type of object whose name is in its names attribute and attach a role attribute to inline for defined roles. We could use the directive's content to encode the writer-specific information such as you suggested: > Other syntax could be: > > .. role:: green(custom-raw) > > * :format: html > :prefix: <font color="green"> > :suffix: </font> > * :format: latex > :prefix: {\color{green} > :suffix: } > > Or > > .. role:: green(custom-raw) > > html > :prefix: <font color="green"> > :suffix: </font> > latex > :prefix: {\color{green} > :suffix: } > > The problem here is scalability. We'd have to add support for new > directive options for each format. That would become really old > really quickly. > > > :green:`example` > > > > having internal representation > > > > <paragraph> > > <inline classes="green" html-prefix="<font color=\"green\"" > > html-suffix="</font>" latex-prefix="{\color{green}" latex-suffix="}"> > > example > > Same scalability problem here. We'd have to add support for > format-specific attributes to the DTD for each writer, plus support > for those attributes to the writers. Agreed, and it would be preferable not to have to clutter each use of the custom role with all the information specific to every writer. Referring to a role_definition avoids both these problems. --Mark |
From: David G. <go...@py...> - 2005-09-29 22:14:33
Attachments:
signature.asc
|
> David Goodger wrote: >> So, given the definition above, how would the following usage be >> represented in the doctree? >> >> colored :red:`text` [Mark Nodine] > The problem really is trying to get communication between the > role's definition and the use of the role, which is impeded > by the fact that the role directive has no representation in > the doctree. No, the problem is getting you to show us a concrete example of what you mean! .. role:: red :html: font :color: red .. role:: green :html: font :color: green :latex: \color{green} :red:`text` :green:`Green text.` Forget about the code & syntax details; just show us what should be in the doctree after the parser is finished with the above, but before the transforms are applied. > Just as a substitution_definition has a representation in the > doctree, perhaps we should add a role_definition type of object Substitutions are based on text from the document, so it makes sense to store the definition in the doctree. Roles are callable code; they should not be in the doctree. Most roles are built-in. Roles created by the "role" directive are based on built-in roles; they're just aliases for built-in roles, with a bit of data. Their definitions are stored in instances of docutils.parsers.rst.roles.CustomRole, whose __call__ method calls the base role. IOW, dirctive-created roles are functionally identical to built-in roles: they're just callable code with a specific API. > whose name is in its names attribute and attach a role attribute to > inline for defined roles. I'm not following you here. Examples, please! Are you under the impression that all directive-created roles use the "inline" element? They don't! .. role:: custom(strong) :custom:`text` results in: <paragraph> <strong classes="custom"> text -- David Goodger <http://python.net/~goodger> |
From: Mark N. <Mar...@fr...> - 2005-09-30 14:53:28
|
David Goodger wrote: > > > David Goodger wrote: > >> So, given the definition above, how would the following usage be > >> represented in the doctree? > >> > >> colored :red:`text` > > [Mark Nodine] > > The problem really is trying to get communication between the > > role's definition and the use of the role, which is impeded > > by the fact that the role directive has no representation in > > the doctree. > > No, the problem is getting you to show us a concrete example of what > you mean! I thought I had given an example in my first email under the shot-down-because-unscalable category. But here goes. Given this input (I've arbitrarily picked one of the alternatives you suggested) .. role:: red html :prefix: <font color="red"> :suffix: </font> latex :prefix: {\color{red} :suffix: } colored :red:`text` I'd suggest the following doctree representation <role_definition names="red" base-role="inline"> <definition_list> <definition_list_item> <term> html <definition> <field_list> <field> <field_name> prefix <field_body> <paragraph> <font color="red"> <field> <field_name> suffix <field_body> <paragraph> </font> <definition_list_item> <term> latex <definition> <field_list> <field> <field_name> prefix <field_body> <paragraph> {color{red} <field> <field_name> suffix <field_body> <paragraph> } <paragraph> colored <inline classes="red" custom-role="red"> text > Are you under the impression that all directive-created roles use the > "inline" element? Of course not. However, inline seems the most natural element to use when you want to specify writer-specific output. --Mark |
From: Felix W. <Fel...@gm...> - 2005-10-03 18:22:47
|
Mark Nodine wrote: > <role_definition names="red" base-role="inline"> > [...] > <paragraph> > colored > <inline classes="red" custom-role="red"> > text You can't expect the writer to resolve the role reference, so that's not the final representation in the doctree. I think we can go without role_definition, and for the doctree we can use the raw element: <paragraph> colored <raw format="html"> <font color="red"> <raw format="latex"> {\color{red} <inline classes="red"> text <raw format="html"> </font> <raw format="latex"> } So we do have a representation after all. The problem is the reST syntax. We could add a new role, like "raw-formatting" from which to subclass:: .. role:: red(raw-formatting) :prefix: :html: <font color="red"> :latex: {\color{red} :suffix: :html: </font> :latex: } The name ("raw-formatting") needs improvement, of course. We could alternatively or additionally add a role (let's call it "surrounded") which does the same without raw content, like :: .. role:: parenthesized(surrounded) :prefix: ( :suffix: ) (I'm not sure if there's a practical use case though.) These roles could share interface and implementation. -- For private mail please ensure that the header contains 'Felix Wiemann'. "the number of contributors [...] is strongly and inversely correlated with the number of hoops each project makes a contributing user go through." -- ESR |
From: David G. <go...@py...> - 2005-10-03 23:56:59
Attachments:
signature.asc
|
> David Goodger wrote: >> No, the problem is getting you to show us a concrete example of what >> you mean! [Mark Nodine] > I thought I had given an example in my first email under the > shot-down-because-unscalable category. No, you gave an HTML output example only. [... example omitted ...] We don't need any new doctree elements (role_definition) to do this. Roles themselves are purely a reST construct, and all roles are resolved at parse time. I don't see any reason why this should be any different. I was working on an alternative approach, but Felix beat me to the post. His directive syntax is better anyhow (putting the invariants -- the prefix & suffix options -- up front). The parser will call the role handler for the raw-formatting role, which will create a new role handler for the "red" role. So when the role is used (e.g. in "colored :red:`text`"), the "red" role handler (a callable object) is simply called. As for the name, perhaps "generated-raw", along the lines of CSS2 generated content? "raw-wrap", "raw-wrapped", "wrapped-raw", or "raw-wrapper"? This is the output Felix came up with: [Felix Wiemann] > <paragraph> > colored > <raw format="html"> > <font color="red"> > <raw format="latex"> > {\color{red} > <inline classes="red"> > text > <raw format="html"> > </font> > <raw format="latex"> > } It matches what I came up with, except for the "<inline classes="red">text</>" in the middle. Is this strictly necessary, and do we want it? Perhaps we do, for other unspecified output formats. > We could alternatively or additionally add a role (let's call it > "surrounded") which does the same without raw content, like :: > > .. role:: parenthesized(surrounded) > :prefix: ( > :suffix: ) > > (I'm not sure if there's a practical use case though.) I think not. Let's not add functionality without prior need. -- David Goodger <http://python.net/~goodger> |
From: Mark N. <Mar...@fr...> - 2005-10-04 15:37:59
|
David Goodger wrote: > This is the output Felix came up with: > > [Felix Wiemann] > > <paragraph> > > colored > > <raw format="html"> > > <font color="red"> > > <raw format="latex"> > > {\color{red} > > <inline classes="red"> > > text > > <raw format="html"> > > </font> > > <raw format="latex"> > > } > +1. > It matches what I came up with, except for the "<inline > classes="red">text</>" in the middle. Is this strictly necessary, and > do we want it? Perhaps we do, for other unspecified output formats. +1. > > We could alternatively or additionally add a role (let's call it > > "surrounded") which does the same without raw content, like :: > > > > .. role:: parenthesized(surrounded) > > :prefix: ( > > :suffix: ) > > > > (I'm not sure if there's a practical use case though.) > > I think not. Let's not add functionality without prior need. Agreed. --Mark |
From: Felix W. <Fel...@gm...> - 2005-10-04 17:41:52
|
David Goodger wrote: > As for the name, perhaps "generated-raw", along the lines of CSS2 > generated content? "raw-wrap", "raw-wrapped", "wrapped-raw", or > "raw-wrapper"? IMO "raw-wrapped" (or "raw-wrap") are the most descriptive names. > Felix Wiemann wrote: > >> <paragraph> >> colored >> <raw format="html"> >> <font color="red"> >> <raw format="latex"> >> {\color{red} >> <inline classes="red"> >> text >> <raw format="html"> >> </font> >> <raw format="latex"> >> } > > It matches what I came up with, except for the "<inline > classes="red">text</>" in the middle. Is this strictly necessary, Probably not. > and do we want it? Probably yes. It can't hurt, I think. >> We could alternatively or additionally add a role (let's call it >> "surrounded") which does the same without raw content, > > I think not. Let's not add functionality without prior need. +1. -- For private mail please ensure that the header contains 'Felix Wiemann'. "the number of contributors [...] is strongly and inversely correlated with the number of hoops each project makes a contributing user go through." -- ESR |