Hi, Mon, 30 Apr 2012 21:44:12 +0200 Cédric Krier <[email protected]>: > On 30/04/12 21:27 +0200, Albert Cervera i Areny wrote: > > A Dilluns, 30 d'abril de 2012 20:36:14, Cédric Krier va escriure: > > > On 30/04/12 19:52 +0200, Albert Cervera i Areny wrote: > > > > A Dilluns, 20 de febrer de 2012 12:51:56, Albert Cervera i > > > > Areny va > > escriure: > > > > > > For inline usage, why not using the same syntax as sphinx > > > > > > inline. It > > > > > > could be something like: > > > > > > :field:`ir.cron/user` > > > > > What you suggest is named a role in sphinx terms. When I > > > > > looked at the docs to find out how to implement this, my > > > > > understanding was that I needed a Directive instead but I may > > > > > be wrong. Will take a look at this. > > > > I rechecked that, and I still think that we need the inline > > > > syntax I proposed. The problem with sphinx's inline syntax is > > > > that you cannot have one role inside another one so you cannot > > > > make your inline field bold, for example. So > > > > the following is not allowed: > > > > *:field:`ir.cron/user`* > > > Is it really a problem compared to the homogeneity of the text. > > IMHO, yes. I think it'd be quite usual that users wanted to use > > bold or italics with field names. > Could it be supporte? Or always put it in italic, > I think it is not > bad to have all those dynamic fields have the same style. Yes, it will be good to have a style guide for documenting modules. But I prefer to have it as convention. There can be always the case we need some special emphasizing of a field name.
E.g. think about a paragraph where we need to refer to the field @field:account.account/kind@. Without emphasizing the word 'kind' in the paragraph, we always need some long explanations like 'the field with the name kind'. This makes a text IMHO less readable then 'the field *kind*'. > > That said, I have not pushed it yet, but I've got the > > implementation using a role, so all options would be available. Alberts original implementation is fine for me. As I read [1], Rst-roles are about markup, not content. Following the discussion[2][3], it seems nested markup with rst-roles will never reach docutils, because it is considered fragile and complex. So for me Albert goes the correct way to implement a separate template substitution mechanism @@ for the inline syntax. Regards Udo [1] http://docutils.sourceforge.net/docs/howto/rst-roles.html [2] http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible [3] http://docutils.sourceforge.net/docs/dev/rst/alternatives.html#nested-inline-markup -- _____________________________ virtual things Preisler & Spallek GbR München - Aachen Windeckstr. 77 81375 München Tel: +49 (89) 710 481 55 Fax: +49 (89) 710 481 56 [email protected] http://www.virtual-things.biz
signature.asc
Description: PGP signature
