<div dir="ltr"><div class="gmail_quote">On Mon, Jul 19, 2010 at 05:57, Eli Bendersky <span dir="ltr"><<a href="mailto:eliben@gmail.com">eliben@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
<div dir="ltr"><div class="im"><div class="gmail_quote">On Sat, Jul 17, 2010 at 16:44, Éric Araujo <span dir="ltr"><<a href="mailto:merwok@netwok.org" target="_blank">merwok@netwok.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
<div>> The "--help" option appears as a hyperlink leading to<br>
> <a href="http://docs.python.org/dev/py3k/using/cmdline.html#cmdoption--help" target="_blank">http://docs.python.org/dev/py3k/using/cmdline.html#cmdoption--help</a>, which is<br>
</div>> hardly relevant or useful. [...]<br>
<div>><br>
> -h/:option:`--help`<br>
> print a short usage message and exit<br>
<br>
</div>I think this is a doc bug in Doc/documenting/markup.rst<br>
:cmdoption: and :option: are not clearly distinguished; the latter<br>
creates references to using/cmdline, the former is what you’re looking<br>
for for documenting trace.py.<br></blockquote></div><br></div>How would you guys recommend to proceed from here?<br><br>The simplest approach for me is just use :cmdoption: instead of :option: in my work on trace.py . However, a few more things can be done if this is indeed "official policy":<br>
<br>1. Fix other modules that use :option: to use :cmdoption: instead (timeit, unittest and others)<br>2. Fix Doc/documenting/markup.rst to clarify which option kind goes where<br><br>If these steps get approved I'll be happy to create an issue and submit patches to the relevant files.<br>
<br>Eli<br></div></blockquote><div><br>More input on this issue:<br><br>'cmdoption' is a directive, while 'option' is inline markup. Therefore I wouldn't say they're completely similar, just meant for different purposes. Both a directive and inline markup is useful for describing "official python executable options/flags". Regarding per-module options, I'm not sure special markup is needed at all. So a policy has to be define regarding the correct usage of these directives/markups, and probably documented in Doc/documenting/markup.rst<br>
<br>Eli<br> <br></div></div><br></div>