Re: [Monotone-devel] nvm.options

[Thomas Keller]

Am 21.07.10 12:18, schrieb Stephen Leake:
> We need a NEWS entry, and something in monotone.texi. How about this:
> 
> NEWS
>         New Features
> 
>         - Options can now be overridden; you can specify --no-unknown
>           --unknown on the command line. Similarly, you can specify
>           --no-unknown in the get_default_command_options hook, then
>           change it to --unknown on the command line.

As I mentioned in my earlier mail the NEWS entry should include more
details what options got hidden, deprecated, replaced and / or removed
exactly. Yes, this is also a tedious task, but given the fact that not
mentioning it might lead to weird user experiences, especially if the
information is also nowhere available else, its a must.

> monotone.texi, in Command Reference header:
> 
>     Many command options come in pairs that affect the same value. For 
> example,
>     @command{mtn log} takes a @var{brief} option; this can be reversed by
>     @var{no-brief}. This is convenient when building command strings
>     automatically; @command{mtn log --brief --no-brief} is the same as
>     @command{mtn log}.
> 
>     It also helps when setting options in the
>     @var{get_default_command_options} hook; those options can be
>     overridden on the command line. For example, if
>     @var{get_default_command_options} specifies @var{brief} for
>     @command{log}, you can override that with @command{mtn log
>     --no-brief}.
> 
>     The command descriptions describe the most important options for each
>     command, and only one of each pair of options. For a complete list of
>     options, see the online help (@command{mtn help cmd}), or the manpage.

Since we have quite a few things now which we at least plan to remove in
2.0, I start to think that adding a dedicated manual section for that
purpose is a good idea. What do others think about that?

> We could modify the description of _every_ command that now has a
> resettable option. Tedious, but do-able. But perhaps we should consider
> generating the command options from the help texts, automatically? This
> would be a modification of the 'mtn manpage' command. That way the info
> manual would be as complete as the online help.
> 
> Or maybe it's ok as is.

Actually not quite, e.g. "mtn serve" currently lists two hidden options,
--stdio and --no-transport-auth, so again I think we have to go over all
these sections and tweak them accordingly, if nobody steps up and finds
a good way to include at least the command calling syntax from the main
program.

> I scanned thru the Tutorial; I did not see a good place to use an
> overridden option. I don't think we want to specify the
> get_default_command_options hook in the tutorial.

We don't have to pack every little feature in the tutorial, this way the
tutorial just gets bigger and bigger. Some things might as well be put
in the advanced uses section.

Thomas.

-- 
GPG-Key 0x160D1092 | address@hidden | http://thomaskeller.biz
Please note that according to the EU law on data retention, information
on every electronic information exchange might be retained for a period
of six months or longer: http://www.vorratsdatenspeicherung.de/?lang=en

signature.asc
Description: OpenPGP digital signature