diff --git a/doc/overview.xml b/doc/overview.xml
index 619ff73..703731b 100644
--- a/doc/overview.xml
+++ b/doc/overview.xml
@@ -152,37 +152,145 @@ desc.add_options()
The syntactic information is provided by the
boost::program_options::options_description class
and some methods of the
- boost::program_options::value_semantic class.
- The simplest usage is illustrated below:
-
+ boost::program_options::value_semantic class
+ and includes:
+
+
+
+ name of the option, used to identify the option inside the
+ program,
+
+
+
+
+ description of the option, which can be presented to the user,
+
+
+
+
+ the allowed number of source tokens that comprise options's
+ value, which is used during parsing.
+
+
+
+
+
+ Consider the following example:
+
options_description desc;
desc.add_options()
("help", "produce help message")
- ;
-
- This declares one option named "help" and associates a description with
- it. The user is not allowed to specify any value.
-
-
- To make an option accept a value, you'd need the
- value function mentioned above:
-
-options_description desc;
-desc.add_options()
("compression", value<string>(), "compression level")
("verbose", value<string>()->implicit(), "verbosity level")
("email", value<string>()->multitoken(), "email to send to")
;
-
- With these declarations, the user must specify a value for
- the first option, using a single token. For the second option, the user
- may either provide a single token for the value, or no token at
- all. For the last option, the value can span several tokens. For
- example, the following command line is OK:
-
- test --compression 10 --verbose --email beadle@mars beadle2@mars
-
+
+ For the first parameter, we specify only the name and the
+ description. No value can be specified in the parsed source.
+ For the first option, the user must specify a value, using a single
+ token. For the third option, the user may either provide a single token
+ for the value, or no token at all. For the last option, the value can
+ span several tokens. For example, the following command line is OK:
+
+ test --help --compression 10 --verbose --email beadle@mars beadle2@mars
+
+
+
+ Description formatting
+
+
+ Sometimes the description can get rather long, for example, when
+ several option's values need separate documentation. Below we
+ describe some simple formatting mechanisms you can use.
+
+
+ The description string has one or more paragraphs, separated by
+ the newline character ('\n'). When an option is output, the library
+ will compute the indentation for options's description. Each of the
+ paragraph is output as a separate line with that intentation. If
+ a paragraph does not fit on one line it is spanned over multiple
+ lines (which will have the same intentation).
+>!!!!!!!!!! The library tries to prevent chopped words and leading spaces in new lines.
+>!!!!!!! Words are chopped only if longer than half the available space. Leading
+> spaces are only skipped if not followed by a space.
+
+
+ You may specify additional indent for the first specified by
+ inserting spaces at the beginning of a paragraph. For example:
+
+options.add_options()
+ ("help", " A long help msg a long help msg a long help msg a long help
+msg a long help msg a long help msg a long help msg a long help msg ")
+ ;
+
+ will specify a four-space indent for the first line. The output will
+ look like:
+
+ --help A long help msg a long
+ help msg a long help msg
+ a long help msg a long
+ help msg a long help msg
+ a long help msg a long
+ help msg
+
+
+
+
+ For the case where line is wrapped, you can want an additional
+ indent for wrapped text. This can be done by
+ inserting a tabulator character ('\t') at the desired position. For
+ example:
+
+options.add_options()
+ ("well_formated", "As you can see this is a very well formatted
+option description.\n"
+ "You can do this for example:\n\n"
+ "Values:\n"
+ " Value1: \tdoes this and that, bla bla bla bla
+bla bla bla bla bla bla bla bla bla bla bla\n"
+ " Value2: \tdoes something else, bla bla bla bla
+bla bla bla bla bla bla bla bla bla bla bla\n\n"
+ " This paragraph has a first line indent only,
+bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla");
+
+ will produce:
+
+ --well_formated As you can see this is a
+ very well formatted
+ option description.
+ You can do this for
+ example:
+
+ Values:
+ Value1: does this and
+ that, bla bla
+ bla bla bla bla
+ bla bla bla bla
+ bla bla bla bla
+ bla
+ Value2: does something
+ else, bla bla
+ bla bla bla bla
+ bla bla bla bla
+ bla bla bla bla
+ bla
+
+ This paragraph has a
+ first line indent only,
+ bla bla bla bla bla bla
+ bla bla bla bla bla bla
+ bla bla bla
+
+ The tab character is removed before output. Only one tabulator per
+ paragraph is allowed, otherwisee an exception of type
+ program_options::error is thrown. Finally, the tabulator is ignored if
+ it's is not on the first line of the paragraph or is on the last
+ possible position of the first line.
+
+
+
+