program_options/doc/todo.txt

Say that variables_map is actually derived from std::map.

Make parse_config_file("foo.cfg", desc) work.

Document handling of positional options which depends on precedding options.
I.e scanning the parsed options and creating new variables_map when we see
a positional option. (Email from Tony).

> My instinctive reaction is to provide both via an options argument to
> split_command_line (a name that would now be more appropriate). But I
> haven't devoted much time to thinking this through, so I may be wrong. :-)
>
> In any event, the tokenization isn't much fun. I'd expect the library to
> provide a convenient mechanism for parsing a response file.


> Similarly, is there some easy to use hook for customizing the "arg" to
> indicate the type of the data (similar to how the textual representation
> of the default argument can be changed, e.g.
> value<Infile>(&forests_file)->default_value(default_in,"STDIN"), so that
> I could get something like: "-f filename (=STDIN)   :" instead of "-f
> arg (=STDIN)  :"?

> A minor nit pick, with option groups (chained options_description), the
> colons for the same group align but not across groups.


There's another possibility:

   value<type>(&variable, "filename")->......

something like that was in the pre-review version, with the difference that the value name was also used to specify flags, e.g "filename?" would mean the value is optional.


Should we also store the name specified on the command line in basic_option,
so that validation_error can mention the *specified* option name?


The config file is a bit different from command line. E.g. 'bool_switch' can't
be specified in the config file. Further, it's not possible to specify a list
of values in config file. For example, you can't write

   include=a,b,c,d

(or some other separator). You need:

   include=a
   ...
   include=d


> I often find it beneficial to start a log file, by tracing all options
> in effect. Thus, it would be nice if one could iterate over all values
> in a variable_map and get a string representation of all values. Perhaps
> as an iterator range to the original string that was parsed into the
> value in the first place. Using as<string> delegates to boost::any and
> only succeeds if the value is indeed a string (a design decision I can
> only applaud, btw), so I'm out of luck there.


UML diagram?

src/cmdline.cpp: function strncmp_nocase():
>     maybe it can be replaced by something from string_algorithms
>     library. AFAIK the library should be in 1.32.

> 24. the documentation may contain info what source files are needed
>     for which feature or whether they need to be included always all.

The program_options.reference.html may contain one-liner
   overview for every header and every class/typedef/function
   listed here - just for quick browsing and overview.


> > > 5. Maybe more overcommented code examples can be added into
> > >    docs, each exploring single feature of library.
> > >
> > >    Some people learn mostly from such examples.
> > >
> > >    Later note: definitely would be useful, IMO.
> >
> > Maybe. Do you have specific ideas what the examples can be about?
>
> One tiny example concentrating on one feature as short/long options,
> multiple sources, hidden options, positional options, INI handling etc.
> Something what user can skim over and cut/paste into app.


> I would prefer that all occurrences of ASCII be capitalized.  It is the
> abbreviation of the name of the Standard.  You may show it in lower case,
> though, to distinguish "char strings in local 8-bit encoding" from the
> Standard but it may confuse some readers.  I can't think of a good
> alternative right now.

> [By the way, "positional options" _desperately_ needs an entry in the
> glossary. It's the most mystifying term in the library.]

> If not already stated, you should note that all options must appear in the
> options description layer (or class or object).  No options may make their
> first appearance in the runtime configuration file, for instance.  The
> library doesn't like surprises.  (I bring this up because other
> initialization libraries allow an option to be declared in the
> configuration file alone.  The file reader stores the option and parses it
> to determine its type, for example, Boolean, double, integer or string.)

-----------
> "In the simplest case, the name is explicitly specified, which allows the
> program to decide if such an option is known."
>
> or
>
> "In the simplest case, the name is explicitly specified and the program
> decides that the option is known."
> (This paragraph is a bit hard to read.  Maybe when I understand the library
> better I can suggest some wording which flows more smoothly.)

Maybe some explanation can help. Most of the time, input source contains both
the name of option and the value, for example, --foo=10. In this case, we
just lookup the option name, decide we know this option, and process it.

In one specific case -- positional command line options, we don't have
explicit name. For example:

   my_prog 1 2 3

so more complex logic is necessary.


> Rather than clutter up this list it might be better for the word "sources"
> to be a link to another part of the document which lists the sources and
> the order of precedence.

Style of 'screen' in docs.

> Perhaps you should include some sample output to show correct and incorrect
> locale support or include a link to somewhere else in Boost where the
> reader can find more information.  I wouldn't know a Unicode if it came up
> and bit me on the ankle.


> "Common cases are when the value is explicitly specified by the user, and
> when the value cannot be specified by the user, but the presense of the
> option implies some value (for example, <code>true</code>). So, the parser
> checks that the value is specified when needed and not specified when not
> needed, and returns new (name, value) pair."
>
> This wording is quite stiff and I can't decipher it, especially the "not
> specified when not needed" phrase.  Can you rewrite this?

> While I'm thinking about it, can you add the "Last revised..." line at the
> bottom of each HTML page as it is on program_options.html or it that
> governed by an xsl file?

> If it doesn't already exist, there should be something in the tutorial to
> explicitly define the steps required prior to the use of a configuration
> variable as:
> 1. declaration
> 2. addition or composition
> 3. storage or insertion
> 4. notification.


> I think a few lines should be added to aid the library user with the test
> programs.  You could place them here in howto.xml or elsewhere or in a new
> section entirely.  Users will want to know if their compiler is known to
> work with the library and should be directed to the Boost Compiler Status
> Tables page (\status\compiler_status.html or similar) or directly to the
> Compiler Status Summary (http://boost.sourceforge.net/regression-logs/).

> Many users will want to run the test programs on their own computer.  Your
> documentation should answer these questions:
> Which libraries must be linked to build the programs? (Dynamic? Static?)
> Are there any other special considerations or any compiler switches to be
> set? For those without a full Boost package, which other Boost libraries
> are "included" by the test programs and, therefore, must be available?

Basically, it's assumed that test programs with be run with Boost.Build.
Maybe it's worth noting that if a user wants to compiler them himself,
he should link the program_options library.

> If you decide to make a separate section to describe the implementation of
> the test programs, you might move the "test_convert" paragraphs starting at
> line 379 of howto.xml there and put a referring link in its place.

> I thought there was a bit of correspondence on one of the Boost mailing
> lists concerning the inability of program_options to show the stored
> variables 'en masse' but I can't find it now.  You should include that in
> the documentation. Most users will be searching for a method to verify that
> command line and configuration file values were actually stored in place of
> the default values, for instance.  You could put in a line or two stating
> that there is no one function which will send the entire database to a file
> for later review.  (I think it had something to do with the fact that
> program_options doesn't "know" the type of each option.)  I think it will
> acquire the status of a Frequently-Asked Question.)


> > Agreed. Though it's no FAQ section yet.... maybe, I can add this to howto
>
> section, though a question without full solution is not good.
>
> For the time being, those who want to know if such a display function
> exists will have their question answered and the reason for it.  I suppose
> that the library user could insert a series of statements in his program
> immediately after the "notify" function which would write each known option
> to a file for later examination.  Some people may use a number of "assert"
> statements instead. They would only come into play in the debug mode.

More visibility for bool_switch.


> BTW: I thought of one other comment. One of the things I missed a little
> in the documentation is a description of the config file format, as well
> as what can be achieved with the po::command_line_style::style_t enum. I
> think most users will need this information sooner or later. A few
> examples would be fine... But then again time is such a precious thing

> Does the library supports sections in config files

> What about the combination of (if some user-settable switch is thrown,
> but not by default):
>
> * allowing unknown options -- these are considered positional parameters
> * rearranging the argument list such that all positional parameters
> are moved to the end
>
> This way:
>
> program --unknown 42 --known-flag --known-arg value
>
> is handled as if it were (in standard UNIX command-line-ese):
>
> program --known-flag --known-arg value -- --unknown 42