[Doc-SIG] New concept of "commands"?
Luc Saffre
luc.saffre at gmx.net
Wed Dec 3 04:52:41 EST 2003
Tilt! Thank you, David. You are right. There is no necessity for
commands. "Interpreted text roles" was the concept that I missed. I had
not seen http://docutils.sourceforge.net/spec/rst/interpreted.html
or perhaps I needed your example to understand that roles are what I'm
looking for.
Okay, I hope I will soon find time to implement some examples of
application-defined roles in WebMan.
Luc
On 3/12/2003 5:09, David Goodger wrote:
> Luc Saffre wrote:
> > Consider also that commands would enhance readability for specific
> > contexts::
> >
> > Don't execute [=fileref /setup.py]_ because it does not work yet.
> >
> > is much more readable than::
> >
> > Don't execute `setup.py <:fileref:/setup.py>`_ because it does
> > not work yet.
>
> I would write it either using substitutions and a directive::
>
> Don't execute |setup.py| because it does not work yet.
>
> .. |setup.py| fileref:: /setup.py
>
> Or using interpreted text roles::
>
> Don't execute :fileref:`setup.py` because it does not work yet.
>
> Directives and roles are Docutils' extension mechanisms. Before
> adding another mechanism, I'd like to see an example that clearly
> isn't covered by the existing two.
More information about the Doc-SIG
mailing list