Remove what is now in the texi docs.

1 files changed, 3 insertions, 346 deletions

diff --git a/tools/README.gpgconf b/tools/README.gpgconf
index c0d3c7c61..084711441 100644
--- a/tools/README.gpgconf
+++ b/tools/README.gpgconf
@@ -2,344 +2,7 @@
   GPG Conf
 ============
 
-CONCEPT
-=======
-
-gpgconf provides access to the configuration of one or more components
-of the GnuPG system.  These components correspond more or less to the
-programs that exist in the GnuPG framework, like GnuPG, GPGSM,
-DirMngr, etc.  But this is not a strict one-to-one relationship.  Not
-all configuration options are available through GPGConf.  GPGConf
-provides a generic and abstract method to access the most important
-configuration options that can feasibly be controlled via such a
-mechanism.
-
-GPGConf can be used to gather and change the options available in each
-component, and can also provide their default values.  GPGConf will
-give detailed type information that can be used to restrict the user's
-input without making an attempt to commit the changes.
-
-GPGConf provides the backend of a configuration editor.  The
-configuration editor would usually be a graphical user interface
-program, that allows to display the current options, their default
-values, and allows the user to make changes to the options.  These
-changes can then be made active with GPGConf again.  Such a program
-that uses GPGConf in this way will be called 'GUI' throughout this
-document.
-
-
-Format Conventions
-==================
-
-Some lines in the output of GPGConf contain a list of colon-separated
-fields.  The following conventions apply:
-
-The GUI program is required to strip off trailing newline and/or carriage
-return characters from the output.
-
-GPGConf will never leave out fields.  If a certain version documents a
-certain field, this field will always be present in all GPGConf
-versions from that time on.
-
-Future versions of GPGConf might append fields to the list.  New
-fields will always be separated from the previously last field by a
-colon separator.  The GUI should be prepared to parse the last field
-it knows about up until a colon or end of line.
-
-Not all fields are defined under all conditions.  You are required to
-ignore the content of undefined fields.
-
-Some fields contain strings that are not escaped in any way.  Such
-fields are described to be used "verbatim".  These fields will never
-contain a colon character (for obvious reasons).  No de-escaping or
-other formatting is required to use the field content.  This is for
-easy parsing of the output, when it is known that the content can
-never contain any special characters.
-
-Some fields contain strings that are described to be
-"percent-escaped".  Such strings need to be de-escaped before their
-content can be presented to the user.  A percent-escaped string is
-de-escaped by replacing all occurences of %XY by the byte that has the
-hexadecimal value XY.  X and Y are from the set { '0'..'9', 'a'..'f' }.
-
-Some fields contain strings that are described to be "localised".  Such
-strings are translated to the active language and formatted in the
-active character set.
-
-Some fields contain an unsigned number.  This number will always fit
-into a 32-bit unsigned integer variable.  The number may be followed
-by a space, followed by a human readable description of that value.
-You should ignore everything in the field that follows the number.
-
-Some fields contain a signed number.  This number will always fit into
-a 32-bit signed integer variable.  The number may be followed by a
-space, followed by a human readable description of that value.  You
-should ignore everything in the field that follows the number.
-
-Some fields contain an option argument.  The format of an option
-argument depends on the type of the option and on some flags:
-
-The simplest case is that the option does not take an argument at all
-(TYPE is 0).  Then the option argument is an unsigned number that
-specifies how often the option occurs.  If the LIST flag is not set,
-then the only valid number is 1.  Options that don't take an argument
-never have the "default" or "optional arg" flag set.
-
-If the option takes a number argument (ALT-TYPE is 2 or 3), and it can
-only occur once (LIST flag is not set), then the option argument is
-either empty (only allowed if the argument is optional), or it is a
-number.  A number is a string that begins with an optional minus
-character, followed by one or more digits.  The number must fit into
-an integer variable (unsigned or signed, depending on ALT-TYPE).
-
-If the option takes a number argument and it can occur more than once,
-then the option argument is either empty, or it is a comma-separated
-list of numbers as described above.
-
-If the option takes a string argument (ALT-TYPE is 1), and it can only
-occur once (LIST flag is not set) then the option argument is either
-empty (only allowed if the argument is optional), or it starts with a
-double quote character (") followed by a percent-escaped string that
-is the argument value.  Note that there is only a leading double quote
-character, no trailing one.  The double quote character is only needed
-to be able to differentiate between no value and the empty string as
-value.
-
-If the option takes a number argument and it can occur more than once,
-then the option argument is either empty, or it is a comma-separated
-list of string arguments as described above.
-
-FIXME: Document the active language and active character set.  Allow
-to change it via the command line?
-
-
-Components
-==========
-
-A component is a set of configuration options that semantically belong
-together.  Furthermore, several changes to a component can be made in
-an atomic way with a single operation.  The GUI could for example
-provide a menu with one entry for each component, or a window with one
-tabulator sheet per component.
-
-The following interface is provided to list the available components:
-
-Command --list-components
--------------------------
-
-Outputs a list of all components available, one per line.  The format
-of each line is:
-
-NAME:DESCRIPTION
-
-NAME
-
-This field contains a name tag of the component.  The name tag is used
-to specify the component in all communication with GPGConf.  The name
-tag is to be used verbatim.  It is not in any escaped format.
-
-DESCRIPTION
-
-The string in this field contains a human-readable description of the
-component.  It can be displayed to the user of the GUI for
-informational purposes.  It is percent-escaped and localized.
-
-Example:
-$ gpgconf --list-components
-gpg-agent:GPG Agent
-dirmngr:CRL Manager
-
-
-OPTIONS
-=======
-
-Every component contains one or more options.  Options may belong to a
-group.  The following command lists all options and the groups they
-belong to:
-
-Command --list-options COMPONENT
---------------------------------
-
-Lists all options (and the groups they belong to) in the component
-COMPONENT.  COMPONENT is the string in the field NAME in the
-output of the --list-components command.
-
-There is one line for each option and each group.  First come all
-options that are not in any group.  Then comes a line describing a
-group.  Then come all options that belong into each group.  Then comes
-the next group and so on.
-
-The format of each line is:
-
-NAME:FLAGS:LEVEL:DESCRIPTION:TYPE:ALT-TYPE:ARGNAME:DEFAULT:ARGDEF:VALUE
-
-NAME
-
-This field contains a name tag for the group or option.  The name tag
-is used to specify the group or option in all communication with
-GPGConf.  The name tag is to be used verbatim.  It is not in any
-escaped format.
-
-FLAGS
-
-The flags field contains an unsigned number.  Its value is the
-OR-wise combination of the following flag values:
-
-	 1 group	If this flag is set, this is a line describing
-			a group and not an option.
-  O	 2 optional arg	If this flag is set, the argument is optional.
-			This is never set for arg type 0 (none) options.
-  O	 4 list		If this flag is set, the option can be given
-			multiple times.
-  O	 8 runtime	If this flag is set, the option can be changed
-			at runtime.
-  O	16 default	If this flag is set, a default value is available.
-  O	32 default desc If this flag is set, a (runtime) default is available.
-                        This and the 'default' flag are mutually exclusive.
-  O     64 no arg desc	If this flag is set, and the 'optional arg' flag
-			is set, then the option has a special meaning if no
-			argument is given.
-
-Flags marked with a 'O' are only defined for options (ie, if the GROUP
-flag is not set).
-
-LEVEL
-
-This field is defined for options and for groups.  It contains an
-unsigned number that specifies the expert level under which this group
-or option should be displayed.  The following expert levels are
-defined for options (they have analogous meaning for groups):
-
-	0 basic		This option should always be offered to the user.
-	1 advanced	This option may be offered to advanced users.
-	2 expert	This option should only be offered to expert users.
-	3 invisible	This option should normally never be displayed,
-			not even to expert users.
-	4 internal	This option is for internal use only.  Ignore it.
-
-The level of a group will always be the lowest level of all options it
-contains.
-
-DESCRIPTION
-
-This field is defined for options and groups.  The string in this
-field contains a human-readable description of the option or group.
-It can be displayed to the user of the GUI for informational purposes.
-It is percent-escaped and localized.
-
-TYPE
-
-This field is only defined for options.  It contains an unsigned
-number that specifies the type of the option's argument, if any.
-The following types are defined:
-
-	Basic types
-	 0 none		No argument allowed.
-	 1 string	An unformatted string.
-	 2 int32	A signed integer number.
-	 3 uint32	An unsigned integer number.
-
-	Complex types
-	32 pathname	A string that describes the pathname of a file.
-			The file does not necessarily need to exist.
-	33 ldap server	A string that describes an LDAP server in the format
-			HOSTNAME:PORT:USERNAME:PASSWORD:BASE_DN.
-
-More types will be added in the future.  Please see the ALT-TYPE field
-for information on how to cope with unknown types.
-
-ALT-TYPE
-
-This field is identical to TYPE, except that only the types 0 to 31
-are allowed.  The GUI is expected to present the user the option in
-the format specified by TYPE.  But if the argument type TYPE is not
-supported by the GUI, it can still display the option in the more
-generic basic type ALT-TYPE.  The GUI must support all the defined
-basic types to be able to display all options.  More basic types may
-be added in future versions.  If the GUI encounters a basic type it
-doesn't support, it should report an error and abort the operation.
-
-ARGNAME
-
-This field is only defined for options with an argument type TYPE that
-is not 0.  In this case it may contain a percent-escaped and localised
-string that gives a short name for the argument.  The field may also
-be empty, though, in which case a short name is not known.
-
-DEFAULT
-
-This field is defined only for options.  Its format is that of an
-option argument (see section Format Conventions for details).  If the
-default value is empty, then no default is known.  Otherwise, the
-value specifies the default value for this option.  Note that this
-field is also meaningful if the option itself does not take a real
-argument.
-
-ARGDEF
-
-This field is defined only for options for which the "optional arg"
-flag is set.  If the "no arg desc" flag is not set, its format is that
-of an option argument (see section Format Conventions for details).
-If the default value is empty, then no default is known.  Otherwise,
-the value specifies the default value for this option.  If the "no arg
-desc" flag is set, the field is either empty or contains a description
-of the effect of this option if no argument is given.  Note that this
-field is also meaningful if the option itself does not take a real
-argument.
-
-VALUE
-
-This field is defined only for options.  Its format is that of an
-option argument.  If it is empty, then the option is not explicitely
-set in the current configuration, and the default applies (if any).
-Otherwise, it contains the current value of the option.  Note that
-this field is also meaningful if the option itself does not take a
-real argument.
-
-
-CHANGING OPTIONS
-================
-
-To change the options for a component, you must provide them in the
-following format:
-
-NAME:FLAGS:NEW-VALUE
-
-NAME
-
-This is the name of the option to change.
-
-FLAGS
-
-The flags field contains an unsigned number.  Its value is the
-OR-wise combination of the following flag values:
-
-	16 default	If this flag is set, the option is deleted and the
-			default value is used instead (if applicable).
-
-NEW-VALUE
-
-The new value for the option.  This field is only defined if the
-"default" flag is not set.  The format is that of an option argument.
-If it is empty (or the field is omitted), the default argument is used
-(only allowed if the argument is optional for this option).
-Otherwise, the option will be set to the specified value.
-
-
-Example:
-To set the option force, which is of basic type 0 (none).
-$ echo 'force:0:1' | gpgconf --change-options dirmngr
-To delete the option force:
-$ echo 'force:16:' | gpgconf --change-options dirmngr
-
-
-Option --runtime
-----------------
-
-If this option is set, the changes will take effect at run-time, as
-far as this is possible.  Otherwise, they will take effect at the next
-start of the respective backend programs.
-
+Main documentation for this tool can be found in doc/tools.texi.
 
 BACKENDS
 ========
@@ -409,14 +72,8 @@ max-replies:10
 TODO
 ----
 
+* Implement --dry-run and --quiet.
+
 * Extend the backend interface to include gettext domain and
 description, if available, to avoid repeating this information in
 gpgconf.
-
-* Left out string arguments (optional) are written out exactly as
-empty string arguments.  Should we do quoting?
-
-* More string argument trouble: Special characters like newlines etc
-cause trouble.  Again, should we do quoting?
-
-