From f27dce4ed4bb84fb0347f8455db64135e7478343 Mon Sep 17 00:00:00 2001 From: Vladimir Prus Date: Fri, 21 Jan 2005 16:11:26 +0000 Subject: [PATCH] Initial docs for text formatting rules. [SVN r26785] --- doc/overview.xml | 154 ++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 131 insertions(+), 23 deletions(-) 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. + + +
+