X-Git-Url: http://mj.ucw.cz/gitweb/?a=blobdiff_plain;ds=inline;f=ucw%2Fdoc%2Fconf.txt;h=257447c05ac5654efb36e46ad4fb4d49ad67330e;hb=ae2b00416589dfe798fc40f0575f62a0c664798f;hp=c89136082a98fada89556b61f93d9df5bd0459d1;hpb=525cfaad2da3938626887e6543f43fc4618721a1;p=libucw.git

diff --git a/ucw/doc/conf.txt b/ucw/doc/conf.txt
index c8913608..257447c0 100644
--- a/ucw/doc/conf.txt
+++ b/ucw/doc/conf.txt
@@ -1,21 +1,22 @@
 Configuration and command line parser
 =====================================
 
-Libucw contains a parser for configuration files described in
-<<config:>>.
+Libucw contains a parser for configuration files. The syntax of the
+configuration files is described in <<config:>>, here we explain the
+interface of the parser.
 
-The principle is you specify the structure of the configuration file,
-the section names, variable names and types and your C variables that
-are assigned to them. Then you run the parser and it fills your
-variables with the values from the configuration file.
+Basically, you write a description of the configuration file syntax,
+which maps configuration items to variables of your program. Then
+Then you run the parser and it fills your variables with the values
+from the configuration file.
 
-It is modular. It means you do not have to write all configuration at
-the same place, you just declare the parts you need locally and do not
-care about the other parts.
+The descriptions are modular. The configuration can be split to sections,
+each section declared at a separate place. You can also define your own
+data types.
 
-The command line parser has the same interface as unix getopt_long(),
-but handles setting of configuration files and configuration values
-from command line.
+There is also a simple wrapper around getopt_long(), which processes
+options related to selection of a configuration file, overriding of
+configuration variables and loading of the default configuration.
 
 - <<example,Example>>
   * <<ex_structure,The structure>>
@@ -26,16 +27,17 @@ from command line.
   * <<custom_parser,Creating custom parsers>>
   * <<hooks,Hooks>>
 - <<conf_h,ucw/conf.h>>
+  * <<conf_ctxt,Configuration contexts>>
+  * <<conf_load,Safe configuration loading>>
   * <<conf_types,Data types>>
   * <<conf_macros,Convenience macros>>
   * <<alloc,Memory allocation>>
   * <<journal,Undo journal>>
+  * <<declare,Section declaration>>
   * <<bparser,Parsers for basic types>>
-- <<getopt_h,ucw/getopt.h>>
-  * <<conf_load,Safe configuration loading>>
   * <<conf_direct,Direct access>>
   * <<conf_dump,Debug dumping>>
-  * <<conf_journal,Journaling control>>
+- <<getopt_h,ucw/getopt.h>>
   * <<conf_getopt,Loading by cf_getopt()>>
 
 [[example]]
@@ -43,12 +45,12 @@ Example
 -------
 If you want to just load simple configuration, this is the part you
 want to read. This simple example should give you the overview. Look
-into the <<conf_macros,convenience macros>> section to see list of
+at the <<conf_macros,convenience macros>> section to see list of
 supported data types, sections, etc.
 
 [[ex_cfile]]
-Let's say you have configuration file with this content and want to
-load it:
+Suppose you have configuration file with the following content and you
+want to load it:
 
   HelloWorld {
     Text	"Hello planet"
@@ -82,10 +84,10 @@ it exists.
   }
 
 The variables are used to store the loaded values. Their initial
-values work as default, if nothing else is loaded. The hw_config()
+values work as defaults, if nothing else is loaded. The hw_config()
 structure assigns the variables to configuration names. The hw_init()
 function (because of the `CONSTRUCTOR` macro) is run before main()
-is called and it plugs in the whole section to the parser (alternatively,
+is called and it tells the parser that the section exists (alternatively,
 you can call @cf_declare_section() at the start of your main()).
 
 You can plug in as many configuration sections as you like, from
@@ -96,21 +98,21 @@ Loading of the values
 ~~~~~~~~~~~~~~~~~~~~~
 Suppose you need to parse the command line arguments and load the
 configuration. Then @cf_getopt() is there for you: it works like
-the the traditional @getopt() from the C library, but it also handles
+the traditional @getopt_long() from the C library, but it also handles
 configuration files.
 
   #include <ucw/lib.h>
   #include <ucw/conf.h>
   #include <ucw/getopt.h>
 
-  static byte short_opts[] = CF_SHORT_OPTS "v";
+  static char short_opts[] = CF_SHORT_OPTS "v";
   static struct option long_opts[] = {
     CF_LONG_OPTS
     { "verbose", 0, 0, 'v' },
     { NULL, 0, 0, 0 }
   };
 
-  int verbose;
+  static int verbose;
 
   int main(int argc, char *argv[]) {
     cf_def_file = "default.cf";
@@ -151,7 +153,7 @@ are three ways to do that:
 +
 For example, you can have an static array of five unsigned integers:
 +
-  static uns array = { 1, 2, 3, 4, 5 };
+  static uns array[] = { 1, 2, 3, 4, 5 };
 +
   static struct cf_section section = {
     CF_ITEMS {
@@ -163,7 +165,7 @@ For example, you can have an static array of five unsigned integers:
 *Dynamic arrays*::
   Similar to static array, but you provide pointer
   to pointer to the given item (eg. if you want dynamic array of
-  `int` s, you give `**int`). The parser allocates an array of needed
+  integers, you give `**int`). The parser allocates an array of needed
   size. You can use the <<def_DARY_LEN,`DARY_LEN`>> macro to find out
   the number of elements actually loaded.
 +
@@ -188,11 +190,12 @@ First element of your structure must be <<clist:type_cnode,`cnode`>>.
 +
 The first example is list of strings and uses <<clist:simple,simple
 lists>>:
-  struct clist list;
++
+  static struct clist list;
 +
   static struct cf_section section = {
     CF_ITEMS {
-      CF_LIST("list", &list, &cf_string_list_cofnig),
+      CF_LIST("list", &list, &cf_string_list_config),
       CF_END
     }
   };
@@ -213,7 +216,7 @@ this variable, `A` will have a value of `10` after a successful load.
 Furthermore, if the loading of a new configuration fails, the current
 configuration is preserved.
 
-All this is done with <<journal,config journaling>>. The load of the
+All this is done with <<journal,config journalling>>. The load of the
 first config creates a journal entry. If you try to load some new
 configuration, it is partially rolled back to defaults (the rollback
 happens, but instead of removing the journal entry, another journal
@@ -232,7 +235,7 @@ If you need to parse some data type the configuration system can't
 handle, you can write your own parser. But before you start, you
 should know a few things.
 
-The parser needs to support <<journal,journaling>>. To accomplish that,
+The parser needs to support <<journal,journalling>>. To accomplish that,
 you have to use the <<alloc,configuration mempool>> for memory allocation.
 
 Now, you need a function with the same signature as
@@ -263,8 +266,8 @@ them in configuration description using <<def_CF_INIT,`CF_INIT`>> and
 
 The hooks should follow similar guidelines as custom parsers (well,
 init hooks do not need to call @cf_journal_block()) to support
-journaling. If you change nothing in the commit hook, you do not need
-to care about the journaling either.
+journalling. If you change nothing in the commit hook, you do not need
+to care about the journalling either.
 
 You may use the return value to inform about errors. Just return the
 error message, or NULL if everything went well.
@@ -279,8 +282,7 @@ the same as the one of a hook.
 ucw/conf.h
 ----------
 
-Use this file if you want define a configuration section, request
-loading of some variables or create new item type.
+This header file contains the public interface of the configuration module.
 
 !!ucw/conf.h
 
@@ -289,6 +291,6 @@ ucw/getopt.h
 ------------
 
 This header contains routines for parsing command line arguments and
-loading the configuration.
+loading the default configuration.
 
 !!ucw/getopt.h