From: David G. <go...@py...> - 2004-04-19 01:31:24
|
I have some questions for everyone. But first, some deep background: In writing the "role" directive, I realized that the API of role functions needs to be expanded. For example, in:: .. role:: custom the role function generated by the directive needs to know that the "class" attribute of the generated "inline" element must be set to "custom". I accomplished this by adding an "attributes={}" parameter to the "generic_role" helper function and the dynamically defined role functions that call "generic_role":: def generic_role_helper(node_class, role, rawtext, text, lineno, inliner, attributes={}): return [node_class(rawtext, text, **attributes)], [] The attributes are simply passed on to the node class when instantiating a new node object, and will end up as element attributes in the doc tree. The next step for the "role" directive is to allow dynamic creation of aliases for existing roles, perhaps like this:: .. role:: pow :base-role: superscript ":base-role:" in combination with the ":class:" option would result in a more powerful role:: .. role:: pow :base-role: superscript :class: power Then ":pow:`2`" would result in:: <superscript class="power"> 2 So all role functions would have to be able to accept an "attributes" parameter. I'm prepared to implement this in the near future. The step after *that* could be to allow arbitrary data to be passed in to role functions. A simplistic example:: .. role:: myref :base-role: named-reference :data: :base-uri: http://example.org/ Then ":myref:`index.html`" could result in:: <reference refuri="http://example.org/index.html"> index.html The ":data:" option would expect a field list; ":base-uri:" is arbitrary. All options have to be known to directive functions beforehand, so we can't just tack on a non-standard ":base-uri:" directly without causing an error. Of course, the "named-reference" directive would have to be able to handle ":base-uri:". Perhaps a "data" function attribute on role functions, similar to the "options" attribute on directive functions? I'm not about to implement this functionality until clear & convincing use cases arise. Finally, the questions: * Does this API seem reasonable and sufficient? * How would you use an expanded "role" directive? * Any other ideas for the "role" directive or for roles in general? Further notes on the role directive are here: <http://docutils.sf.net/spec/notes.html#misc-role>. A new how-to document is now available, "Creating reStructuredText Interpreted Text Roles": <http://docutils.sf.net/spec/howto/rst-roles.html>. -- David Goodger http://python.net/~goodger For hire: http://python.net/~goodger/cv |
From: Lele G. <le...@na...> - 2004-04-19 13:07:54
|
>>>>> "David" =3D=3D David Goodger <go...@py...> writes: David> Finally, the questions: David> * How would you use an expanded "role" directive?=20=20 David> * Any other ideas for the "role" directive or for roles in David> general?=20 I used roles in the ongoing italian translation of the GNU/Emacs texinfo manual. The midterm goal is to provide a toolset able to digest reST and emit **valid** Info files. Ideally, I'd like to be able to emit standard texinfo sources, so I want a one-to-one relationship between texinfo and reST. Here are some thoughts on the first troubles I saw. In that context, there are a few elements that need to be mapped to interpreted roles, in two distinct areas: * "decoration": - @bold{text}, @emph, @samp...: some of these have an exact dtd equivalent, others don't. These are surely covered by your proposal/actual code. [1]_ - @key{a}: this, in texinfo, produce a little icon in the DVI (not in the textual info version). My original approach was to register a transform that at some point would augment these nodes with the appropriate "eyes-sugar" :) What'd you suggest for this case? * "references": - @var{varname}: although texinfo requires explicit index entry declaration, I can see it could be usefull to be able to attach "arbitrary" hooks upon node's creation - @ref{target}, @xref{}, @pxref{}: these expand in various kind of "see 'target' on page N.". A previous proposal was able to grok with this, allowing simple re-formatting. thanks a lot, bye, lele. .. [1] It's very common this form: ``@kbd{C-@key{Space}}``, but this is (currently) impossible, since it requires nested markup. --=20 nickname: Lele Gaifax | Quando vivr=F2 di quello che ho pensato ieri real: Emanuele Gaifas | comincer=F2 ad aver paura di chi mi copia. email: le...@se... | -- Fortunato Depero, 1929. |
From: David G. <go...@py...> - 2004-04-20 22:30:18
|
Lele Gaifax wrote: > I used roles in the ongoing italian translation of the GNU/Emacs > texinfo manual. The midterm goal is to provide a toolset able to > digest reST and emit **valid** Info files. Are you working on a texinfo Writer? If you are, how about putting it in a sandbox directory (under "texinfo" or "lele", as you like)? > .. [1] It's very common this form: ``@kbd{C-@key{Space}}``, but this > is (currently) impossible, since it requires nested markup. Nested markup should be possible before long I hope. That would allow simple custom roles without programming. In the meantime, Edward's suggestion is good. > - @key{a}: this, in texinfo, produce a little icon in the DVI (not > in the textual info version). My original approach was to > register a transform that at some point would augment these > nodes with the appropriate "eyes-sugar" :) > > What'd you suggest for this case? If @key{a} in a texinfo file already produces the icon after processing to DVI, you don't need to do anything else. Where do you want to have the eye-candy manifest itself? I don't understand the problem here. > * "references": > > - @var{varname}: although texinfo requires explicit index entry > declaration, I can see it could be usefull to be able to attach > "arbitrary" hooks upon node's creation This kind of hyperlinking can be done now. It's exactly what's done with regular hyperlinks like "this_". Transforms are required to get the job done, to connect references to targets. > - @ref{target}, @xref{}, @pxref{}: these expand in various kind of > "see 'target' on page N.". A previous proposal was able to grok > with this, allowing simple re-formatting. Again, if @ref{target} in texinfo already gets the job done, that's all that's needed. For other formats, some in-Docutils expansion would be required. There are some related notes at <http://docutils.sf.net/spec/notes.html#object-numbering-and-object-references>. Thanks for the input! -- David Goodger http://python.net/~goodger For hire: http://python.net/~goodger/cv |
From: Lele G. <le...@na...> - 2004-04-21 00:08:44
|
>>>>> "David" =3D=3D David Goodger <go...@py...> writes: David> Lele Gaifax wrote: >> I used roles in the ongoing italian translation of the >> GNU/Emacs texinfo manual. The midterm goal is to provide a >> toolset able to digest reST and emit **valid** Info files. David> Are you working on a texinfo Writer? No, not yet. But probably will.=20 David> If you are, how about putting it in a sandbox directory David> (under "texinfo" or "lele", as you like)? Sure will do. >> - @key{a}: this, in texinfo, produce a little icon in the DVI >> (not in the textual info version). My original approach was to >> register a transform that at some point would augment these >> nodes with the appropriate "eyes-sugar" :) >>=20 >> What'd you suggest for this case? David> If @key{a} in a texinfo file already produces the icon David> after processing to DVI, you don't need to do anything David> else. Where do you want to have the eye-candy manifest David> itself? I don't understand the problem here. Uhm, I won't be obtaining HTML from the texinfo chain. I guess the icon gets created with some tex "magic". What I meant is, if it's "interpreted", then one have plenty of space for his imagination :) In this particular case, it could be sufficient using a image subst, being able to install some kind of .. role:: key :node: substitution_reference >> * "references": >>=20 >> - @var{varname}: although texinfo requires explicit index entry >> declaration, I can see it could be usefull to be able to attach >> "arbitrary" hooks upon node's creation David> This kind of hyperlinking can be done now. It's exactly David> what's done with regular hyperlinks like "this_". David> Transforms are required to get the job done, to connect David> references to targets. It was more in view of registering the text with some kind of index, sort of contents directive but parametric. I thought about something like:: .. role:: var .. defindex:: variables :role: var The variable :var:`special` will go under the letter "s" in the :index-ref:`variables`. .. index:: variables :title: Variables index =20=20=20 thanx&bye, lele. --=20 nickname: Lele Gaifax | Quando vivr=F2 di quello che ho pensato ieri real: Emanuele Gaifas | comincer=F2 ad aver paura di chi mi copia. email: le...@se... | -- Fortunato Depero, 1929. |
From: Beni C. <cb...@us...> - 2004-04-27 10:35:37
|
Lele Gaifax wrote: >>>>>>"David" == David Goodger <go...@py...> writes: > > > David> Lele Gaifax wrote: > >> I used roles in the ongoing italian translation of the > >> GNU/Emacs texinfo manual. The midterm goal is to provide a > >> toolset able to digest reST and emit **valid** Info files. > > David> Are you working on a texinfo Writer? > > No, not yet. But probably will. > Cool. Perhaps one day reST will become the standard format of the GNU project (just dreaming ;). > David> If you are, how about putting it in a sandbox directory > David> (under "texinfo" or "lele", as you like)? > > Sure will do. > > >> - @key{a}: this, in texinfo, produce a little icon in the DVI > >> (not in the textual info version). My original approach was to > >> register a transform that at some point would augment these > >> nodes with the appropriate "eyes-sugar" :) > >> > >> What'd you suggest for this case? > > David> If @key{a} in a texinfo file already produces the icon > David> after processing to DVI, you don't need to do anything > David> else. Where do you want to have the eye-candy manifest > David> itself? I don't understand the problem here. > > Uhm, I won't be obtaining HTML from the texinfo chain. I guess the > icon gets created with some tex "magic". What I meant is, if it's > "interpreted", then one have plenty of space for his imagination :) > > In this particular case, it could be sufficient using a image subst, > being able to install some kind of > > .. role:: key > :node: substitution_reference > Image?!? Please, don't. Just emit <kbd> tags (or <span class="kbd"> if you are lazy) and add a border in CSS. > >> * "references": > >> > >> - @var{varname}: although texinfo requires explicit index entry > >> declaration, I can see it could be usefull to be able to attach > >> "arbitrary" hooks upon node's creation > > David> This kind of hyperlinking can be done now. It's exactly > David> what's done with regular hyperlinks like "this_". > David> Transforms are required to get the job done, to connect > David> references to targets. > > It was more in view of registering the text with some kind of index, > sort of contents directive but parametric. I thought about something > like:: > > .. role:: var > > .. defindex:: variables > :role: var > How about avoiding the defindex:: .. role:: var :index: variables ? > The variable :var:`special` will go under the letter "s" in the > :index-ref:`variables`. > > .. index:: variables > :title: Variables index > This part looks fine to me. -- Beni Cherniavsky <cb...@us...> Note: I can only read email on week-ends... |