Re: [Python-Dev] Markup of command-line options in Python's .rst documentation

2010-07-19 Thread Eli Bendersky
> > '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

Re: [Python-Dev] Markup of command-line options in Python's .rst documentation

2010-07-19 Thread Eli Bendersky
> > > > More input on this issue: > > > > '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 option

Re: [Python-Dev] Markup of command-line options in Python's .rst documentation

2010-07-19 Thread Éric Araujo
Le 19/07/2010 04:57, Eli Bendersky a écrit : > On Sat, Jul 17, 2010 at 16:44, Éric Araujo wrote: >> I think this is a doc bug in Doc/documenting/markup.rst >> :cmdoption: and :option: are not clearly distinguished; the latter >> creates references to using/cmdline, the former is what you’re lookin

Re: [Python-Dev] Markup of command-line options in Python's .rst documentation

2010-07-19 Thread Éric Araujo
Le 19/07/2010 04:57, Eli Bendersky a écrit : > On Sat, Jul 17, 2010 at 16:44, Éric Araujo wrote: >> I think this is a doc bug in Doc/documenting/markup.rst >> :cmdoption: and :option: are not clearly distinguished; the latter >> creates references to using/cmdline, the former is what you’re lookin

Re: [Python-Dev] Markup of command-line options in Python's .rst documentation

2010-07-19 Thread Georg Brandl
Am 19.07.2010 04:28, schrieb Eli Bendersky: > On Mon, Jul 19, 2010 at 05:57, Eli Bendersky > wrote: > > On Sat, Jul 17, 2010 at 16:44, Éric Araujo > wrote: > > > The "--help" option appears as a hyperlink leading to > >

Re: [Python-Dev] Markup of command-line options in Python's .rst documentation

2010-07-18 Thread Alexander Belopolsky
On Sun, Jul 18, 2010 at 11:46 PM, Eli Bendersky wrote: .. > However, I wonder what this means for backwards compatibility. Is it valid > to switch trace.py to use the newer command-line argument parsing module > that's only available in the newest versions of Python? I guess it could be > since tr

Re: [Python-Dev] Markup of command-line options in Python's .rst documentation

2010-07-18 Thread Eli Bendersky
On Mon, Jul 19, 2010 at 06:40, Alexander Belopolsky < alexander.belopol...@gmail.com> wrote: > On Sun, Jul 18, 2010 at 11:28 PM, Eli Bendersky wrote: > > .. So a policy has to be define regarding the > > correct usage of these directives/markups, and probably documented in > > Doc/documenting/mar

Re: [Python-Dev] Markup of command-line options in Python's .rst documentation

2010-07-18 Thread Alexander Belopolsky
On Sun, Jul 18, 2010 at 11:28 PM, Eli Bendersky wrote: > .. So a policy has to be define regarding the > correct usage of these directives/markups, and probably documented in > Doc/documenting/markup.rst I wonder if in addition to documenting proper markup you could add an option to argparse to g

Re: [Python-Dev] Markup of command-line options in Python's .rst documentation

2010-07-18 Thread Eli Bendersky
On Mon, Jul 19, 2010 at 05:57, Eli Bendersky wrote: > On Sat, Jul 17, 2010 at 16:44, Éric Araujo wrote: > >> > The "--help" option appears as a hyperlink leading to >> > http://docs.python.org/dev/py3k/using/cmdline.html#cmdoption--help, >> which is >> > hardly relevant or useful. [...] >> > >>

Re: [Python-Dev] Markup of command-line options in Python's .rst documentation

2010-07-18 Thread Eli Bendersky
On Sat, Jul 17, 2010 at 16:44, Éric Araujo wrote: > > The "--help" option appears as a hyperlink leading to > > http://docs.python.org/dev/py3k/using/cmdline.html#cmdoption--help, > which is > > hardly relevant or useful. [...] > > > > -h/:option:`--help` > >print a short usage message and ex

Re: [Python-Dev] Markup of command-line options in Python's .rst documentation

2010-07-18 Thread Michael Foord
On 17/07/2010 14:44, Eli Bendersky wrote: On Sat, Jul 17, 2010 at 16:26, Michael Foord mailto:fuzzy...@voidspace.org.uk>> wrote: On 17/07/2010 14:23, Eli Bendersky wrote: Hello, I'm currently working, together with Terry Reedy, on improving the documentation of the trace mo

Re: [Python-Dev] Markup of command-line options in Python's .rst documentation

2010-07-17 Thread Eli Bendersky
On Sat, Jul 17, 2010 at 16:26, Michael Foord wrote: > On 17/07/2010 14:23, Eli Bendersky wrote: > > Hello, > > I'm currently working, together with Terry Reedy, on improving the > documentation of the trace module, and I ran into a peculiar convention of > marking command-line options which seems

Re: [Python-Dev] Markup of command-line options in Python's .rst documentation

2010-07-17 Thread Éric Araujo
> The "--help" option appears as a hyperlink leading to > http://docs.python.org/dev/py3k/using/cmdline.html#cmdoption--help, which is > hardly relevant or useful. [...] > > -h/:option:`--help` >print a short usage message and exit I think this is a doc bug in Doc/documenting/markup.rst :cmdo

Re: [Python-Dev] Markup of command-line options in Python's .rst documentation

2010-07-17 Thread Michael Foord
On 17/07/2010 14:23, Eli Bendersky wrote: Hello, I'm currently working, together with Terry Reedy, on improving the documentation of the trace module, and I ran into a peculiar convention of marking command-line options which seems to be widespread. Consider the documentation of timeit, for

[Python-Dev] Markup of command-line options in Python's .rst documentation

2010-07-17 Thread Eli Bendersky
Hello, I'm currently working, together with Terry Reedy, on improving the documentation of the trace module, and I ran into a peculiar convention of marking command-line options which seems to be widespread. Consider the documentation of timeit, for instance: http://docs.python.org/dev/py3k/libra