From b4b0c7e72d7eaee2fbfc7022022c9698323203dd Mon Sep 17 00:00:00 2001
From: ivan <ivan>
Date: Thu, 31 Dec 2009 13:16:41 +0000
Subject: import rt 3.8.7

---
 rt/docs/creating_external_custom_fields.pod        |   97 ++
 rt/docs/design_docs/TransactionTypes.txt           |    6 +-
 .../design_docs/gnupg_details_on_output_formats    | 1253 ++++++++++++++++++++
 rt/docs/design_docs/rql_parser_machine.graphviz    |    3 +
 rt/docs/design_docs/string-extraction-guide.txt    |    6 +-
 rt/docs/extending_clickable_links.pod              |  157 +++
 rt/docs/gnupg_integration.pod                      |    1 +
 rt/docs/porting.windows                            |   24 +
 rt/docs/queue_subject_tag.pod                      |   79 ++
 rt/docs/templates.pod                              |   60 +
 rt/docs/using_forms_widgets.pod                    |  113 ++
 11 files changed, 1793 insertions(+), 6 deletions(-)
 create mode 100644 rt/docs/creating_external_custom_fields.pod
 create mode 100644 rt/docs/design_docs/gnupg_details_on_output_formats
 create mode 100644 rt/docs/extending_clickable_links.pod
 create mode 100644 rt/docs/gnupg_integration.pod
 create mode 100644 rt/docs/porting.windows
 create mode 100644 rt/docs/queue_subject_tag.pod
 create mode 100644 rt/docs/templates.pod
 create mode 100644 rt/docs/using_forms_widgets.pod

(limited to 'rt/docs')

diff --git a/rt/docs/creating_external_custom_fields.pod b/rt/docs/creating_external_custom_fields.pod
new file mode 100644
index 000000000..f8eca44fb
--- /dev/null
+++ b/rt/docs/creating_external_custom_fields.pod
@@ -0,0 +1,97 @@
+=head1 External custom fields
+
+=head2 Description
+
+C<External custom fields> is extension to custom fields that allow
+you to define CF with a dynamic list of values. Loading values into
+this custom fields requires writing a little Perl code to fetch the
+data from the external source; the code that we added to RT 3.7
+allows it to load data from arbitrary external sources.
+
+=head2 Introduction into writing source of values
+
+For each type of data source that you want, you'll need to put a file
+in F</opt/rt3/local/lib/RT/CustomFieldValues/> (or equivilent if you
+installed RT someplace other than F</opt/rt3>). To get a sense of the
+code that you'll need to write, take a look at the code in 
+L</opt/rt3/lib/RT/CustomFieldValues/Groups.pm> for a simple example
+which just uses RT's API to pull in a list of RT's groups.
+
+Running C<perldoc /opt/rt3/lib/RT/CustomFieldValues/External.pm> will
+show you the documentation for the API that needs to be fulfilled, by
+copying and editing the C<Groups> example is probably a fine place to
+start.
+
+Later in this doc we'll describe the example a little bit more.
+
+=head2 Configuration
+
+After the custom code is written, you need to tell RT about its
+existence by adding something like following to your RT_SiteConfig.pm:
+Set(@CustomFieldValuesSources, "RT::CustomFieldValues::MySource");
+
+The value in quotes should be the name of the class that you created.
+
+Stop and start your web server to enable any config changes. Open the web interface with
+as an administrative user (such as root) create new custom field. In order to use
+a custom source of values, you should select a custom field type
+that lets users pick values from a list, for example it could be C<Select *>
+or a type with autocompletion. It shouldn't be C<Enter one value> type
+as this type doesn't allow user to choose values. Other types that
+don't have a defined list of values are also unacceptable.
+
+Save the changes, now you have ability to select a "source" for values.
+Choose the class you wrote from the list and save changes.
+
+=head2 How to write custom source
+
+You have to implement a subclass of L<RT::CustomFieldValues::External>.
+There are two main methods you want to override:
+
+=over 4
+
+=item SourceDescription
+
+This method should return a string describing the data source; this is
+the identifier which the adimistrator will see in the dropdown in the web
+interface. See L</Configuration>.
+
+=item ExternalValues
+
+This method should return an array reference of hash references.  The
+hash references should contain keys for C<name>, C<description>, and
+C<sortorder>. C<name> is most important one. The others are optional
+
+=back
+
+Here's a simple static example:
+
+  package RT::CustomFieldValues::MySource;
+  
+  # define class inheritance
+  use base qw(RT::CustomFieldValues::External);
+
+  # admin friendly description, the default valuse is the name of the class
+  sub SourceDescription {
+      return 'My Source';
+  }
+  
+  # actual values provider method
+  sub ExternalValues {
+      # return reference to array ([])
+      return [
+          # each element of the array is a reference to hash that describe a value
+          # possible keys are name, description and sortorder
+          { name => 'value1', description => 'external value', sortorder => 1 },
+          { name => 'value2', description => 'another external value', sortorder => 2 },
+          # values without description are also valid, the default description is empty string
+          { name => 'value3', sortorder => 3 },
+          # you can skip sortorder too, but note that the default sortorder is 0 (zero)
+          { name => 'value3' },
+      ];
+  }
+  
+  1; # don't forget to return some true value
+
+That's all. Install and configure your class as described in the L</Configuration> section.
+
diff --git a/rt/docs/design_docs/TransactionTypes.txt b/rt/docs/design_docs/TransactionTypes.txt
index 942b72371..6edc408de 100755
--- a/rt/docs/design_docs/TransactionTypes.txt
+++ b/rt/docs/design_docs/TransactionTypes.txt
@@ -28,8 +28,8 @@ generalized methods for
 when new transaction types are needed.
 
 
-$RT::TransactionTypes  ...and...
-%RT::TransactionTypes
+RT->Config->Get('TransactionTypes')  ...and...
+RT->Config->Get('TransactionTypes')
    - global object which contains all TransactionTypes
    - used by all UIs to create menues of possible (user) actions (one TransactionType is a user action)
 
@@ -37,7 +37,7 @@ The UIs should call sth like
 $Ticket->AddTransaction($TransactionName), which should be equivalent
 with i.e.  $Ticket->Correspond when $TransactionName is 'Correspond'
 (AUTOLOAD should call the do-sub if exists
-$RT::TransactionTypes{$TransactionName})
+RT->Config->Get('TransactionTypes')->{$TransactionName})
 
 The RT::Ticket::AddTransaction will create a new transaction of the
 right TransactionClass (maybe via a sub
diff --git a/rt/docs/design_docs/gnupg_details_on_output_formats b/rt/docs/design_docs/gnupg_details_on_output_formats
new file mode 100644
index 000000000..e2fc1756f
--- /dev/null
+++ b/rt/docs/design_docs/gnupg_details_on_output_formats
@@ -0,0 +1,1253 @@
+
+*NOTE* This file is a copy of doc/DETAILS file that comes
+with gnupg-1.9.94 distribution.
+
+Format of colon listings
+========================
+First an example:
+
+$ gpg --fixed-list-mode --with-colons --list-keys \
+   --with-fingerprint --with-fingerprint wk@gnupg.org
+
+pub:f:1024:17:6C7EE1B8621CC013:899817715:1055898235::m:::scESC:
+fpr:::::::::ECAF7590EB3443B5C7CF3ACB6C7EE1B8621CC013:
+uid:f::::::::Werner Koch <wk@g10code.com>:
+uid:f::::::::Werner Koch <wk@gnupg.org>:
+sub:f:1536:16:06AD222CADF6A6E1:919537416:1036177416:::::e:
+fpr:::::::::CF8BCC4B18DE08FCD8A1615906AD222CADF6A6E1:
+sub:r:1536:20:5CE086B5B5A18FF4:899817788:1025961788:::::esc:
+fpr:::::::::AB059359A3B81F410FCFF97F5CE086B5B5A18FF4:
+
+The double --with-fingerprint prints the fingerprint for the subkeys
+too, --fixed-list-mode is themodern listing way printing dates in
+seconds since Epoch and does not merge the first userID with the pub
+record.
+
+
+ 1. Field:  Type of record
+	    pub = public key
+            crt = X.509 certificate
+            crs = X.509 certificate and private key available
+	    sub = subkey (secondary key)
+	    sec = secret key
+	    ssb = secret subkey (secondary key)
+	    uid = user id (only field 10 is used).
+	    uat = user attribute (same as user id except for field 10).
+            sig = signature
+            rev = revocation signature
+	    fpr = fingerprint: (fingerprint is in field 10)
+	    pkd = public key data (special field format, see below)
+            grp = reserved for gpgsm
+            rvk = revocation key
+            tru = trust database information
+            spk = signature subpacket
+
+ 2. Field:  A letter describing the calculated trust. This is a single
+	    letter, but be prepared that additional information may follow
+	    in some future versions. (not used for secret keys)
+		o = Unknown (this key is new to the system)
+                i = The key is invalid (e.g. due to a missing self-signature)
+		d = The key has been disabled
+		    (deprecated - use the 'D' in field 12 instead)
+		r = The key has been revoked
+		e = The key has expired
+		- = Unknown trust (i.e. no value assigned)
+		q = Undefined trust
+	            '-' and 'q' may safely be treated as the same
+		    value for most purposes
+		n = Don't trust this key at all
+		m = There is marginal trust in this key
+		f = The key is fully trusted
+		u = The key is ultimately trusted.  This often means
+		    that the secret key is available, but any key may
+		    be marked as ultimately trusted.
+ 3. Field:  length of key in bits.
+ 4. Field:  Algorithm:	1 = RSA
+		       16 = Elgamal (encrypt only)
+		       17 = DSA (sometimes called DH, sign only)
+		       20 = Elgamal (sign and encrypt - don't use them!)
+	    (for other id's see include/cipher.h)
+ 5. Field:  KeyID
+ 6. Field:  Creation Date (in UTC).  For UID and UAT records, this is the
+            self-signature date.  Note that the dae is usally printed
+            in seconds since epoch, however, we are migrating to an ISO
+            8601 format (e.g. "19660205T091500").  This is currently
+            only relevant for X.509, A simple way to detect the format
+            is be scannning for the 'T'.
+ 7. Field:  Key or user ID/user attribute expiration date or empty if none.
+ 8. Field:  Used for serial number in crt records (used to be the Local-ID).
+            For UID and UAT records, this is a hash of the user ID contents
+            used to represent that exact user ID.  For trust signatures,
+            this is the trust depth seperated by the trust value by a
+            space.
+ 9. Field:  Ownertrust (primary public keys only)
+	    This is a single letter, but be prepared that additional
+	    information may follow in some future versions.  For trust
+	    signatures with a regular expression, this is the regular
+	    expression value, quoted as in field 10.
+10. Field:  User-ID.  The value is quoted like a C string to avoid
+	    control characters (the colon is quoted "\x3a").
+            This is not used with --fixed-list-mode in gpg.
+            A UAT record puts the attribute subpacket count here, a
+	    space, and then the total attribute subpacket size.
+            In gpgsm the issuer name comes here
+            An FPR record stores the fingerprint here.
+            The fingerprint of an revocation key is stored here.
+11. Field:  Signature class.  This is a 2 digit hexnumber followed by
+            either the letter 'x' for an exportable signature or the
+            letter 'l' for a local-only signature.
+            The class byte of an revocation key is also given here,
+            'x' and 'l' ist used the same way.
+12. Field:  Key capabilities:
+                e = encrypt
+                s = sign
+                c = certify
+                a = authentication
+	    A key may have any combination of them in any order.  In
+	    addition to these letters, the primary key has uppercase
+	    versions of the letters to denote the _usable_
+	    capabilities of the entire key, and a potential letter 'D'
+	    to indicate a disabled key.
+13. Field:  Used in FPR records for S/MIME keys to store the fingerprint of
+            the issuer certificate.  This is useful to build the
+            certificate path based on certificates stored in the local
+            keyDB; it is only filled if the issue certificate is
+            available. The advantage of using this value is that it is
+            guaranteed to have been been build by the same lookup
+            algorithm as gpgsm uses.
+            For "uid" recods this lists the preferences n the sameway the 
+            -edit menu does.
+	    For "sig" records, this is the fingerprint of the key that
+	    issued the signature.  Note that this is only filled in if
+	    the signature verified correctly.  Note also that for
+	    various technical reasons, this fingerprint is only
+	    available if --no-sig-cache is used.
+
+14. Field   Flag field used in the --edit menu output:
+
+15. Field   Used in sec/sbb to print the serial number of a token
+            (internal protect mode 1002) or a '#' if that key is a
+            simple stub (internal protect mode 1001)
+
+All dates are displayed in the format yyyy-mm-dd unless you use the
+option --fixed-list-mode in which case they are displayed as seconds
+since Epoch.  More fields may be added later, so parsers should be
+prepared for this. When parsing a number the parser should stop at the
+first non-number character so that additional information can later be
+added.
+
+If field 1 has the tag "pkd", a listing looks like this:
+pkd:0:1024:B665B1435F4C2 .... FF26ABB:
+    !  !   !-- the value
+    !  !------ for information number of bits in the value
+    !--------- index (eg. DSA goes from 0 to 3: p,q,g,y)
+
+
+The "tru" trust database records have the fields:
+
+ 2: Reason for staleness of trust.  If this field is empty, then the
+    trustdb is not stale.  This field may have multiple flags in it:
+
+    o: Trustdb is old
+    t: Trustdb was built with a different trust model than the one we
+       are using now.
+
+ 3: Trust model:
+    0: Classic trust model, as used in PGP 2.x.
+    1: PGP trust model, as used in PGP 6 and later.  This is the same
+       as the classic trust model, except for the addition of trust
+       signatures.
+
+    GnuPG before version 1.4 used the classic trust model by default.
+    GnuPG 1.4 and later uses the PGP trust model by default.
+
+ 4: Date trustdb was created in seconds since 1/1/1970.
+ 5: Date trustdb will expire in seconds since 1/1/1970.
+
+The "spk" signature subpacket records have the fields:
+
+ 2: Subpacket number as per RFC-2440 and later.
+ 3: Flags in hex.  Currently the only two bits assigned are 1, to
+    indicate that the subpacket came from the hashed part of the
+    signature, and 2, to indicate the subpacket was marked critical.
+ 4: Length of the subpacket.  Note that this is the length of the
+    subpacket, and not the length of field 5 below.  Due to the need
+    for %-encoding, the length of field 5 may be up to 3x this value.
+ 5: The subpacket data.  Printable ASCII is shown as ASCII, but other
+    values are rendered as %XX where XX is the hex value for the byte.
+
+
+Format of the "--status-fd" output
+==================================
+Every line is prefixed with "[GNUPG:] ", followed by a keyword with
+the type of the status line and a some arguments depending on the
+type (maybe none); an application should always be prepared to see
+more arguments in future versions.
+
+
+    NEWSIG
+        May be issued right before a signature verification starts.  This
+        is useful to define a context for parsing ERROR status
+        messages.  No arguments are currently defined.
+
+    GOODSIG	<long keyid>  <username>
+	The signature with the keyid is good.  For each signature only
+        one of the three codes GOODSIG, BADSIG or ERRSIG will be
+        emitted and they may be used as a marker for a new signature.
+        The username is the primary one encoded in UTF-8 and %XX
+        escaped.
+
+    EXPSIG	<long keyid>  <username>
+	The signature with the keyid is good, but the signature is
+	expired. The username is the primary one encoded in UTF-8 and
+	%XX escaped.
+
+    EXPKEYSIG	<long keyid>  <username>
+	The signature with the keyid is good, but the signature was
+	made by an expired key. The username is the primary one
+	encoded in UTF-8 and %XX escaped.
+
+    REVKEYSIG	<long keyid>  <username>
+	The signature with the keyid is good, but the signature was
+	made by a revoked key. The username is the primary one
+	encoded in UTF-8 and %XX escaped.
+
+    BADSIG	<long keyid>  <username>
+	The signature with the keyid has not been verified okay.
+        The username is the primary one encoded in UTF-8 and %XX
+        escaped.
+
+    ERRSIG  <long keyid>  <pubkey_algo> <hash_algo> \
+	    <sig_class> <timestamp> <rc>
+	It was not possible to check the signature.  This may be
+	caused by a missing public key or an unsupported algorithm.
+	A RC of 4 indicates unknown algorithm, a 9 indicates a missing
+	public key. The other fields give more information about
+	this signature.  sig_class is a 2 byte hex-value.
+
+        Note, that TIMESTAMP may either be a number with seconds since
+        epoch or an ISO 8601 string which can be detected by the
+        presence of the letter 'T' inside.
+
+    VALIDSIG	<fingerprint in hex> <sig_creation_date> <sig-timestamp>
+		<expire-timestamp> <sig-version> <reserved> <pubkey-algo>
+		<hash-algo> <sig-class> <primary-key-fpr>
+
+	The signature with the keyid is good. This is the same as
+	GOODSIG but has the fingerprint as the argument. Both status
+	lines are emitted for a good signature.  All arguments here
+	are on one long line.  sig-timestamp is the signature creation
+	time in seconds after the epoch. expire-timestamp is the
+	signature expiration time in seconds after the epoch (zero
+	means "does not expire"). sig-version, pubkey-algo, hash-algo,
+	and sig-class (a 2-byte hex value) are all straight from the
+	signature packet.  PRIMARY-KEY-FPR is the fingerprint of the
+	primary key or identical to the first argument.  This is
+	useful to get back to the primary key without running gpg
+	again for this purpose.
+
+        Note, that *-TIMESTAMP may either be a number with seconds
+        since epoch or an ISO 8601 string which can be detected by the
+        presence of the letter 'T' inside.
+
+    SIG_ID  <radix64_string>  <sig_creation_date>  <sig-timestamp>
+	This is emitted only for signatures of class 0 or 1 which
+	have been verified okay.  The string is a signature id
+	and may be used in applications to detect replay attacks
+	of signed messages.  Note that only DLP algorithms give
+	unique ids - others may yield duplicated ones when they
+	have been created in the same second.
+
+        Note, that SIG-TIMESTAMP may either be a number with seconds
+        since epoch or an ISO 8601 string which can be detected by the
+        presence of the letter 'T' inside.
+
+
+    ENC_TO  <long keyid>  <keytype>  <keylength>
+	The message is encrypted to this keyid.
+	keytype is the numerical value of the public key algorithm,
+	keylength is the length of the key or 0 if it is not known
+	(which is currently always the case).
+
+    NODATA  <what>
+	No data has been found. Codes for what are:
+	    1 - No armored data.
+	    2 - Expected a packet but did not found one.
+	    3 - Invalid packet found, this may indicate a non OpenPGP
+                message.
+            4 - signature expected but not found
+	You may see more than one of these status lines.
+
+    UNEXPECTED <what>
+        Unexpected data has been encountered
+            0 - not further specified               1       
+  
+
+    TRUST_UNDEFINED <error token>
+    TRUST_NEVER  <error token>
+    TRUST_MARGINAL
+    TRUST_FULLY
+    TRUST_ULTIMATE
+	For good signatures one of these status lines are emitted
+	to indicate how trustworthy the signature is.  The error token
+        values are currently only emiited by gpgsm.
+
+    PKA_TRUST_GOOD <mailbox>
+    PKA_TRUST_BAD  <mailbox>
+        Depending on the outcome of the PKA check one of the above
+        status codes is emitted in addition to a TRUST_* status.
+        Without PKA info available or 
+
+    SIGEXPIRED
+	This is deprecated in favor of KEYEXPIRED.
+
+    KEYEXPIRED <expire-timestamp>
+	The key has expired.  expire-timestamp is the expiration time
+	in seconds after the epoch.
+
+        Note, that TIMESTAMP may either be a number with seconds since
+        epoch or an ISO 8601 string which can be detected by the
+        presence of the letter 'T' inside.
+
+    KEYREVOKED
+	The used key has been revoked by its owner.  No arguments yet.
+
+    BADARMOR
+	The ASCII armor is corrupted.  No arguments yet.
+
+    RSA_OR_IDEA
+	The IDEA algorithms has been used in the data.  A
+	program might want to fallback to another program to handle
+	the data if GnuPG failed.  This status message used to be emitted
+        also for RSA but this has been dropped after the RSA patent expired.
+        However we can't change the name of the message.
+
+    SHM_INFO
+    SHM_GET
+    SHM_GET_BOOL
+    SHM_GET_HIDDEN
+
+    GET_BOOL
+    GET_LINE
+    GET_HIDDEN
+    GOT_IT
+
+    NEED_PASSPHRASE <long main keyid> <long keyid> <keytype> <keylength>
+	Issued whenever a passphrase is needed.
+	keytype is the numerical value of the public key algorithm
+	or 0 if this is not applicable, keylength is the length
+	of the key or 0 if it is not known (this is currently always the case).
+
+    NEED_PASSPHRASE_SYM <cipher_algo> <s2k_mode> <s2k_hash>
+	Issued whenever a passphrase for symmetric encryption is needed.
+
+    NEED_PASSPHRASE_PIN <card_type> <chvno> [<serialno>]
+        Issued whenever a PIN is requested to unlock a card.
+
+    MISSING_PASSPHRASE
+	No passphrase was supplied.  An application which encounters this
+	message may want to stop parsing immediately because the next message
+	will probably be a BAD_PASSPHRASE.  However, if the application
+	is a wrapper around the key edit menu functionality it might not
+	make sense to stop parsing but simply ignoring the following
+	BAD_PASSPHRASE.
+
+    BAD_PASSPHRASE <long keyid>
+	The supplied passphrase was wrong or not given.  In the latter case
+	you may have seen a MISSING_PASSPHRASE.
+
+    GOOD_PASSPHRASE
+	The supplied passphrase was good and the secret key material
+	is therefore usable.
+
+    DECRYPTION_FAILED
+	The symmetric decryption failed - one reason could be a wrong
+	passphrase for a symmetrical encrypted message.
+
+    DECRYPTION_OKAY
+	The decryption process succeeded.  This means, that either the
+	correct secret key has been used or the correct passphrase
+	for a conventional encrypted message was given.  The program
+	itself may return an errorcode because it may not be possible to
+	verify a signature for some reasons.
+
+    NO_PUBKEY  <long keyid>
+    NO_SECKEY  <long keyid>
+	The key is not available
+
+    IMPORT_CHECK <long keyid> <fingerprint> <user ID>
+        This status is emitted in interactive mode right before
+        the "import.okay" prompt.
+
+    IMPORTED   <long keyid>  <username>
+	The keyid and name of the signature just imported
+
+    IMPORT_OK  <reason> [<fingerprint>]
+        The key with the primary key's FINGERPRINT has been imported.
+        Reason flags:
+          0 := Not actually changed
+          1 := Entirely new key.
+          2 := New user IDs
+          4 := New signatures
+          8 := New subkeys 
+         16 := Contains private key.
+        The flags may be ORed.
+
+    IMPORT_PROBLEM <reason> [<fingerprint>]
+        Issued for each import failure.  Reason codes are:
+          0 := "No specific reason given".
+          1 := "Invalid Certificate".
+          2 := "Issuer Certificate missing".
+          3 := "Certificate Chain too long".
+          4 := "Error storing certificate".
+
+    IMPORT_RES <count> <no_user_id> <imported> <imported_rsa> <unchanged>
+	<n_uids> <n_subk> <n_sigs> <n_revoc> <sec_read> <sec_imported> <sec_dups> <not_imported>
+	Final statistics on import process (this is one long line)
+
+    FILE_START <what> <filename>
+	Start processing a file <filename>.  <what> indicates the performed
+	operation:
+	    1 - verify
+            2 - encrypt
+            3 - decrypt        
+
+    FILE_DONE
+	Marks the end of a file processing which has been started
+	by FILE_START.
+
+    BEGIN_DECRYPTION
+    END_DECRYPTION
+	Mark the start and end of the actual decryption process.  These
+	are also emitted when in --list-only mode.
+
+    BEGIN_ENCRYPTION  <mdc_method> <sym_algo>
+    END_ENCRYPTION
+	Mark the start and end of the actual encryption process.
+
+    BEGIN_SIGNING
+       Mark the start of the actual signing process. This may be used
+       as an indication that all requested secret keys are ready for
+       use.
+
+    DELETE_PROBLEM reason_code
+	Deleting a key failed.	Reason codes are:
+	    1 - No such key
+	    2 - Must delete secret key first
+            3 - Ambigious specification
+
+    PROGRESS what char cur total
+	Used by the primegen and Public key functions to indicate progress.
+	"char" is the character displayed with no --status-fd enabled, with
+	the linefeed replaced by an 'X'.  "cur" is the current amount
+	done and "total" is amount to be done; a "total" of 0 indicates that
+	the total amount is not known.	100/100 may be used to detect the
+	end of operation.
+        Well known values for WHAT:
+             "pk_dsa"   - DSA key generation
+             "pk_elg"   - Elgamal key generation
+             "primegen" - Prime generation
+             "need_entropy" - Waiting for new entropy in the RNG
+             "file:XXX" - processing file XXX
+                          (note that current gpg versions leave out the
+                           "file:" prefix).
+             "tick"     - generic tick without any special meaning - useful
+                          for letting clients know that the server is
+                          still working.
+             "starting_agent" - A gpg-agent was started because it is not
+                          running as a daemon.
+
+        
+    SIG_CREATED <type> <pubkey algo> <hash algo> <class> <timestamp> <key fpr>
+	A signature has been created using these parameters.
+	    type:  'D' = detached
+		   'C' = cleartext
+		   'S' = standard
+		   (only the first character should be checked)
+	    class: 2 hex digits with the signature class
+
+        Note, that TIMESTAMP may either be a number with seconds since
+        epoch or an ISO 8601 string which can be detected by the
+        presence of the letter 'T' inside.
+        
+    KEY_CREATED <type> <fingerprint> [<handle>]
+        A key has been created
+            type: 'B' = primary and subkey
+                  'P' = primary
+                  'S' = subkey
+        The fingerprint is one of the primary key for type B and P and
+        the one of the subkey for S.  Handle is an arbitrary
+        non-whitespace string used to match key parameters from batch
+        key creation run.
+
+    KEY_NOT_CREATED [<handle>]
+        The key from batch run has not been created due to errors.
+
+
+    SESSION_KEY  <algo>:<hexdigits>
+	The session key used to decrypt the message.  This message will
+	only be emitted when the special option --show-session-key
+	is used.  The format is suitable to be passed to the option
+	--override-session-key
+
+    NOTATION_NAME <name> 
+    NOTATION_DATA <string>
+        name and string are %XX escaped; the data may be splitted
+        among several notation_data lines.
+
+    USERID_HINT <long main keyid> <string>
+        Give a hint about the user ID for a certain keyID. 
+
+    POLICY_URL <string>
+        string is %XX escaped
+
+    BEGIN_STREAM
+    END_STREAM
+        Issued by pipemode.
+
+    INV_RECP <reason> <requested_recipient>
+        Issued for each unusable recipient. The reasons codes
+        currently in use are:
+          0 := "No specific reason given".
+          1 := "Not Found"
+          2 := "Ambigious specification"
+          3 := "Wrong key usage"
+          4 := "Key revoked"
+          5 := "Key expired"
+          6 := "No CRL known"
+          7 := "CRL too old"
+          8 := "Policy mismatch"
+          9 := "Not a secret key"
+	 10 := "Key not trusted"
+
+        Note that this status is also used for gpgsm's SIGNER command
+        where it relates to signer's of course.
+
+    NO_RECP <reserved>
+        Issued when no recipients are usable.
+
+    ALREADY_SIGNED <long-keyid>
+        Warning: This is experimental and might be removed at any time.
+
+    TRUNCATED <maxno>
+        The output was truncated to MAXNO items.  This status code is issued
+        for certain external requests
+
+    ERROR <error location> <error code> 
+
+        This is a generic error status message, it might be followed
+        by error location specific data. <error token> and
+        <error_location> should not contain a space.  The error code
+        is a either a string commencing with a letter or such string
+        prefix with a numerical error code and an underscore; e.g.:
+        "151011327_EOF"
+
+    ATTRIBUTE <fpr> <octets> <type> <index> <count>
+	      <timestamp> <expiredate> <flags>
+	This is one long line issued for each attribute subpacket when
+	an attribute packet is seen during key listing.  <fpr> is the
+	fingerprint of the key. <octets> is the length of the
+	attribute subpacket. <type> is the attribute type
+	(1==image). <index>/<count> indicates that this is the Nth
+	indexed subpacket of count total subpackets in this attribute
+	packet.  <timestamp> and <expiredate> are from the
+	self-signature on the attribute packet.  If the attribute
+	packet does not have a valid self-signature, then the
+	timestamp is 0.  <flags> are a bitwise OR of:
+		0x01 = this attribute packet is a primary uid
+		0x02 = this attribute packet is revoked
+		0x04 = this attribute packet is expired
+
+    CARDCTRL <what> [<serialno>]
+        This is used to control smartcard operations.
+        Defined values for WHAT are:
+           1 = Request insertion of a card.  Serialnumber may be given
+               to request a specific card.
+           2 = Request removal of a card.
+           3 = Card with serialnumber detected
+           4 = No card available.
+           5 = No card reader available
+
+
+    PLAINTEXT <format> <timestamp> <filename>
+        This indicates the format of the plaintext that is about to be
+        written.  The format is a 1 byte hex code that shows the
+        format of the plaintext: 62 ('b') is binary data, 74 ('t') is
+        text data with no character set specified, and 75 ('u') is
+        text data encoded in the UTF-8 character set.  The timestamp
+        is in seconds since the epoch.  If a filename is available it
+        gets printed as the third argument, percent-escaped as usual.
+
+    PLAINTEXT_LENGTH <length>
+        This indicates the length of the plaintext that is about to be
+        written.  Note that if the plaintext packet has partial length
+        encoding it is not possible to know the length ahead of time.
+        In that case, this status tag does not appear.
+
+    SIG_SUBPACKET <type> <flags> <len> <data>
+        This indicates that a signature subpacket was seen.  The
+        format is the same as the "spk" record above.
+
+    SC_OP_FAILURE [<code>]
+        An operation on a smartcard definitely failed.  Currently
+        there is no indication of the actual error code, but
+        application should be prepared to later accept more arguments.
+        Defined values for CODE are:
+           0 - unspecified error (identically to a missing CODE)
+           1 - canceled
+           2 - bad PIN
+
+    SC_OP_SUCCESS
+        A smart card operaion succeeded.  This status is only printed
+        for certain operation and is mostly useful to check whether a
+        PIN change really worked.
+
+    BACKUP_KEY_CREATED fingerprint fname
+        A backup key named FNAME has been created for the key with
+        KEYID.
+
+
+Format of the "--attribute-fd" output
+=====================================
+
+When --attribute-fd is set, during key listings (--list-keys,
+--list-secret-keys) GnuPG dumps each attribute packet to the file
+descriptor specified.  --attribute-fd is intended for use with
+--status-fd as part of the required information is carried on the
+ATTRIBUTE status tag (see above).
+
+The contents of the attribute data is specified by 2440bis, but for
+convenience, here is the Photo ID format, as it is currently the only
+attribute defined:
+
+   Byte 0-1:  The length of the image header.  Due to a historical
+              accident (i.e. oops!) back in the NAI PGP days, this is
+              a little-endian number.  Currently 16 (0x10 0x00).
+
+   Byte 2:    The image header version.  Currently 0x01.
+
+   Byte 3:    Encoding format.  0x01 == JPEG.
+
+   Byte 4-15: Reserved, and currently unused.
+
+   All other data after this header is raw image (JPEG) data.
+
+
+Format of the "--list-config" output
+====================================
+
+--list-config outputs information about the GnuPG configuration for
+the benefit of frontends or other programs that call GnuPG.  There are
+several list-config items, all colon delimited like the rest of the
+--with-colons output.  The first field is always "cfg" to indicate
+configuration information.  The second field is one of (with
+examples):
+
+version: the third field contains the version of GnuPG.
+
+   cfg:version:1.3.5
+
+pubkey: the third field contains the public key algorithmdcaiphers
+	this version of GnuPG supports, separated by semicolons.  The
+	algorithm numbers are as specified in RFC-2440.
+
+   cfg:pubkey:1;2;3;16;17
+
+cipher: the third field contains the symmetric ciphers this version of
+	GnuPG supports, separated by semicolons.  The cipher numbers
+	are as specified in RFC-2440.
+
+   cfg:cipher:2;3;4;7;8;9;10
+
+digest: the third field contains the digest (hash) algorithms this
+	version of GnuPG supports, separated by semicolons.  The
+	digest numbers are as specified in RFC-2440.
+
+   cfg:digest:1;2;3;8;9;10
+
+compress: the third field contains the compression algorithms this
+	  version of GnuPG supports, separated by semicolons.  The
+	  algorithm numbers are as specified in RFC-2440.
+
+   cfg:compress:0;1;2;3
+
+group: the third field contains the name of the group, and the fourth
+       field contains the values that the group expands to, separated
+       by semicolons.
+
+For example, a group of:
+   group mynames = paige 0x12345678 joe patti
+
+would result in:
+   cfg:group:mynames:patti;joe;0x12345678;paige
+
+
+Key generation
+==============
+    Key generation shows progress by printing different characters to
+    stderr:
+	     "."  Last 10 Miller-Rabin tests failed
+	     "+"  Miller-Rabin test succeeded
+	     "!"  Reloading the pool with fresh prime numbers
+	     "^"  Checking a new value for the generator
+	     "<"  Size of one factor decreased
+	     ">"  Size of one factor increased
+
+    The prime number for Elgamal is generated this way:
+
+    1) Make a prime number q of 160, 200, 240 bits (depending on the keysize)
+    2) Select the length of the other prime factors to be at least the size
+       of q and calculate the number of prime factors needed
+    3) Make a pool of prime numbers, each of the length determined in step 2
+    4) Get a new permutation out of the pool or continue with step 3
+       if we have tested all permutations.
+    5) Calculate a candidate prime p = 2 * q * p[1] * ... * p[n] + 1
+    6) Check that this prime has the correct length (this may change q if
+       it seems not to be possible to make a prime of the desired length)
+    7) Check whether this is a prime using trial divisions and the
+       Miller-Rabin test.
+    8) Continue with step 4 if we did not find a prime in step 7.
+    9) Find a generator for that prime.
+
+    This algorithm is based on Lim and Lee's suggestion from the
+    Crypto '97 proceedings p. 260.
+
+
+Unattended key generation
+=========================
+This feature allows unattended generation of keys controlled by a
+parameter file.  To use this feature, you use --gen-key together with
+--batch and feed the parameters either from stdin or from a file given
+on the commandline.
+
+The format of this file is as follows:
+  o Text only, line length is limited to about 1000 chars.
+  o You must use UTF-8 encoding to specify non-ascii characters.
+  o Empty lines are ignored.
+  o Leading and trailing spaces are ignored.
+  o A hash sign as the first non white space character indicates a comment line.
+  o Control statements are indicated by a leading percent sign, the
+    arguments are separated by white space from the keyword.
+  o Parameters are specified by a keyword, followed by a colon.  Arguments
+    are separated by white space.
+  o The first parameter must be "Key-Type", control statements
+    may be placed anywhere.
+  o Key generation takes place when either the end of the parameter file
+    is reached, the next "Key-Type" parameter is encountered or at the
+    control statement "%commit"
+  o Control statements:
+    %echo <text>
+	Print <text>.
+    %dry-run
+	Suppress actual key generation (useful for syntax checking).
+    %commit
+	Perform the key generation.  An implicit commit is done
+	at the next "Key-Type" parameter.
+    %pubring <filename>
+    %secring <filename>
+	Do not write the key to the default or commandline given
+	keyring but to <filename>.  This must be given before the first
+	commit to take place, duplicate specification of the same filename
+	is ignored, the last filename before a commit is used.
+	The filename is used until a new filename is used (at commit points)
+	and all keys are written to that file.	If a new filename is given,
+	this file is created (and overwrites an existing one).
+	Both control statements must be given.
+   o The order of the parameters does not matter except for "Key-Type"
+     which must be the first parameter.  The parameters are only for the
+     generated keyblock and parameters from previous key generations are not
+     used. Some syntactically checks may be performed.
+     The currently defined parameters are:
+     Key-Type: <algo-number>|<algo-string>
+	Starts a new parameter block by giving the type of the
+	primary key. The algorithm must be capable of signing.
+	This is a required parameter.
+     Key-Length: <length-in-bits>
+	Length of the key in bits.  Default is 1024.
+     Key-Usage: <usage-list>
+        Space or comma delimited list of key usage, allowed values are
+        "encrypt", "sign", and "auth".  This is used to generate the
+        key flags.  Please make sure that the algorithm is capable of
+        this usage.  Note that OpenPGP requires that all primary keys
+        are capable of certification, so no matter what usage is given
+        here, the "cert" flag will be on.  If no Key-Usage is
+        specified, all the allowed usages for that particular
+        algorithm are used.
+     Subkey-Type: <algo-number>|<algo-string>
+	This generates a secondary key.  Currently only one subkey
+	can be handled.
+     Subkey-Length: <length-in-bits>
+	Length of the subkey in bits.  Default is 1024.
+     Subkey-Usage: <usage-list>
+        Similar to Key-Usage.
+     Passphrase: <string>
+	If you want to specify a passphrase for the secret key,
+	enter it here.	Default is not to use any passphrase.
+     Name-Real: <string>
+     Name-Comment: <string>
+     Name-Email: <string>
+	The 3 parts of a key. Remember to use UTF-8 here.
+	If you don't give any of them, no user ID is created.
+     Expire-Date: <iso-date>|(<number>[d|w|m|y])
+	Set the expiration date for the key (and the subkey).  It
+	may either be entered in ISO date format (2000-08-15) or as
+	number of days, weeks, month or years. Without a letter days
+	are assumed.
+     Preferences: <string>
+        Set the cipher, hash, and compression preference values for
+	this key.  This expects the same type of string as "setpref"
+	in the --edit menu.
+     Revoker: <algo>:<fpr> [sensitive]
+        Add a designated revoker to the generated key.  Algo is the
+	public key algorithm of the designated revoker (i.e. RSA=1,
+	DSA=17, etc.)  Fpr is the fingerprint of the designated
+	revoker.  The optional "sensitive" flag marks the designated
+	revoker as sensitive information.  Only v4 keys may be
+	designated revokers.
+     Handle: <string>
+        This is an optional parameter only used with the status lines
+        KEY_CREATED and KEY_NOT_CREATED.  STRING may be up to 100
+        characters and should not contain spaces.  It is useful for
+        batch key generation to associate a key parameter block with a
+        status line.
+     Keyserver: <string>
+        This is an optional parameter that specifies the preferred
+        keyserver URL for the key.
+
+
+Here is an example:
+$ cat >foo <<EOF
+     %echo Generating a standard key
+     Key-Type: DSA
+     Key-Length: 1024
+     Subkey-Type: ELG-E
+     Subkey-Length: 1024
+     Name-Real: Joe Tester
+     Name-Comment: with stupid passphrase
+     Name-Email: joe@foo.bar
+     Expire-Date: 0
+     Passphrase: abc
+     %pubring foo.pub
+     %secring foo.sec
+     # Do a commit here, so that we can later print "done" :-)
+     %commit
+     %echo done
+EOF
+$ gpg --batch --gen-key foo
+ [...]
+$ gpg --no-default-keyring --secret-keyring ./foo.sec \
+				  --keyring ./foo.pub --list-secret-keys
+/home/wk/work/gnupg-stable/scratch/foo.sec
+------------------------------------------
+sec  1024D/915A878D 2000-03-09 Joe Tester (with stupid passphrase) <joe@foo.bar>
+ssb  1024g/8F70E2C0 2000-03-09
+
+
+
+Layout of the TrustDB
+=====================
+The TrustDB is built from fixed length records, where the first byte
+describes the record type.  All numeric values are stored in network
+byte order. The length of each record is 40 bytes. The first record of
+the DB is always of type 1 and this is the only record of this type.
+
+FIXME:  The layout changed, document it here.
+
+  Record type 0:
+  --------------
+    Unused record, can be reused for any purpose.
+
+  Record type 1:
+  --------------
+    Version information for this TrustDB.  This is always the first
+    record of the DB and the only one with type 1.
+     1 byte value 1
+     3 bytes 'gpg'  magic value
+     1 byte Version of the TrustDB (2)
+     1 byte marginals needed
+     1 byte completes needed
+     1 byte max_cert_depth
+	    The three items are used to check whether the cached
+	    validity value from the dir record can be used.
+     1 u32  locked flags [not used]
+     1 u32  timestamp of trustdb creation
+     1 u32  timestamp of last modification which may affect the validity
+	    of keys in the trustdb.  This value is checked against the
+	    validity timestamp in the dir records.
+     1 u32  timestamp of last validation [currently not used]
+	    (Used to keep track of the time, when this TrustDB was checked
+	     against the pubring)
+     1 u32  record number of keyhashtable [currently not used]
+     1 u32  first free record
+     1 u32  record number of shadow directory hash table [currently not used]
+	    It does not make sense to combine this table with the key table
+	    because the keyid is not in every case a part of the fingerprint.
+     1 u32  record number of the trusthashtbale
+
+
+  Record type 2: (directory record)
+  --------------
+    Informations about a public key certificate.
+    These are static values which are never changed without user interaction.
+
+     1 byte value 2
+     1 byte  reserved
+     1 u32   LID     .	(This is simply the record number of this record.)
+     1 u32   List of key-records (the first one is the primary key)
+     1 u32   List of uid-records
+     1 u32   cache record
+     1 byte  ownertrust
+     1 byte  dirflag
+     1 byte  maximum validity of all the user ids
+     1 u32   time of last validity check.
+     1 u32   Must check when this time has been reached.
+	     (0 = no check required)
+
+
+  Record type 3:  (key record)
+  --------------
+    Informations about a primary public key.
+    (This is mainly used to lookup a trust record)
+
+     1 byte value 3
+     1 byte  reserved
+     1 u32   LID
+     1 u32   next   - next key record
+     7 bytes reserved
+     1 byte  keyflags
+     1 byte  pubkey algorithm
+     1 byte  length of the fingerprint (in bytes)
+     20 bytes fingerprint of the public key
+	      (This is the value we use to identify a key)
+
+  Record type 4: (uid record)
+  --------------
+    Informations about a userid
+    We do not store the userid but the hash value of the userid because that
+    is sufficient.
+
+     1 byte value 4
+     1 byte reserved
+     1 u32  LID  points to the directory record.
+     1 u32  next   next userid
+     1 u32  pointer to preference record
+     1 u32  siglist  list of valid signatures
+     1 byte uidflags
+     1 byte validity of the key calculated over this user id
+     20 bytes ripemd160 hash of the username.
+
+
+  Record type 5: (pref record)
+  --------------
+    This record type is not anymore used.
+
+     1 byte value 5
+     1 byte   reserved
+     1 u32  LID; points to the directory record (and not to the uid record!).
+	    (or 0 for standard preference record)
+     1 u32  next
+     30 byte preference data
+
+  Record type 6  (sigrec)
+  -------------
+    Used to keep track of key signatures. Self-signatures are not
+    stored.  If a public key is not in the DB, the signature points to
+    a shadow dir record, which in turn has a list of records which
+    might be interested in this key (and the signature record here
+    is one).
+
+     1 byte   value 6
+     1 byte   reserved
+     1 u32    LID	    points back to the dir record
+     1 u32    next   next sigrec of this uid or 0 to indicate the
+		     last sigrec.
+     6 times
+	1 u32  Local_id of signatures dir or shadow dir record
+	1 byte Flag: Bit 0 = checked: Bit 1 is valid (we have a real
+			     directory record for this)
+			 1 = valid is set (but may be revoked)
+
+
+
+  Record type 8: (shadow directory record)
+  --------------
+    This record is used to reserve a LID for a public key.  We
+    need this to create the sig records of other keys, even if we
+    do not yet have the public key of the signature.
+    This record (the record number to be more precise) will be reused
+    as the dir record when we import the real public key.
+
+     1 byte value 8
+     1 byte  reserved
+     1 u32   LID      (This is simply the record number of this record.)
+     2 u32   keyid
+     1 byte  pubkey algorithm
+     3 byte reserved
+     1 u32   hintlist	A list of records which have references to
+			this key.  This is used for fast access to
+			signature records which are not yet checked.
+			Note, that this is only a hint and the actual records
+			may not anymore hold signature records for that key
+			but that the code cares about this.
+    18 byte reserved
+
+
+
+  Record Type 10 (hash table)
+  --------------
+    Due to the fact that we use fingerprints to lookup keys, we can
+    implement quick access by some simple hash methods, and avoid
+    the overhead of gdbm.  A property of fingerprints is that they can be
+    used directly as hash values.  (They can be considered as strong
+    random numbers.)
+      What we use is a dynamic multilevel architecture, which combines
+    hashtables, record lists, and linked lists.
+
+    This record is a hashtable of 256 entries; a special property
+    is that all these records are stored consecutively to make one
+    big table. The hash value is simple the 1st, 2nd, ... byte of
+    the fingerprint (depending on the indirection level).
+
+    When used to hash shadow directory records, a different table is used
+    and indexed by the keyid.
+
+     1 byte value 10
+     1 byte reserved
+     n u32  recnum; n depends on the record length:
+	    n = (reclen-2)/4  which yields 9 for the current record length
+	    of 40 bytes.
+
+    the total number of such record which makes up the table is:
+	 m = (256+n-1) / n
+    which is 29 for a record length of 40.
+
+    To look up a key we use the first byte of the fingerprint to get
+    the recnum from this hashtable and look up the addressed record:
+       - If this record is another hashtable, we use 2nd byte
+	 to index this hash table and so on.
+       - if this record is a hashlist, we walk all entries
+	 until we found one a matching one.
+       - if this record is a key record, we compare the
+	 fingerprint and to decide whether it is the requested key;
+
+
+  Record type 11 (hash list)
+  --------------
+    see hash table for an explanation.
+    This is also used for other purposes.
+
+    1 byte value 11
+    1 byte reserved
+    1 u32  next 	 next hash list record
+    n times		 n = (reclen-5)/5
+	1 u32  recnum
+
+    For the current record length of 40, n is 7
+
+
+
+  Record type 254 (free record)
+  ---------------
+    All these records form a linked list of unused records.
+     1 byte  value 254
+     1 byte  reserved (0)
+     1 u32   next_free
+
+
+
+Packet Headers
+===============
+
+GNUPG uses PGP 2 packet headers and also understands OpenPGP packet header.
+There is one enhancement used with the old style packet headers:
+
+   CTB bits 10, the "packet-length length bits", have values listed in
+   the following table:
+
+      00 - 1-byte packet-length field
+      01 - 2-byte packet-length field
+      10 - 4-byte packet-length field
+      11 - no packet length supplied, unknown packet length
+
+   As indicated in this table, depending on the packet-length length
+   bits, the remaining 1, 2, 4, or 0 bytes of the packet structure field
+   are a "packet-length field".  The packet-length field is a whole
+   number field.  The value of the packet-length field is defined to be
+   the value of the whole number field.
+
+   A value of 11 is currently used in one place: on compressed data.
+   That is, a compressed data block currently looks like <A3 01 . .  .>,
+   where <A3>, binary 10 1000 11, is an indefinite-length packet. The
+   proper interpretation is "until the end of the enclosing structure",
+   although it should never appear outermost (where the enclosing
+   structure is a file).
+
++  This will be changed with another version, where the new meaning of
++  the value 11 (see below) will also take place.
++
++  A value of 11 for other packets enables a special length encoding,
++  which is used in case, where the length of the following packet can
++  not be determined prior to writing the packet; especially this will
++  be used if large amounts of data are processed in filter mode.
++
++  It works like this: After the CTB (with a length field of 11) a
++  marker field is used, which gives the length of the following datablock.
++  This is a simple 2 byte field (MSB first) containing the amount of data
++  following this field, not including this length field. After this datablock
++  another length field follows, which gives the size of the next datablock.
++  A value of 0 indicates the end of the packet. The maximum size of a
++  data block is limited to 65534, thereby reserving a value of 0xffff for
++  future extensions. These length markers must be inserted into the data
++  stream just before writing the data out.
++
++  This 2 byte field is large enough, because the application must buffer
++  this amount of data to prepend the length marker before writing it out.
++  Data block sizes larger than about 32k doesn't make any sense. Note
++  that this may also be used for compressed data streams, but we must use
++  another packet version to tell the application that it can not assume,
++  that this is the last packet.
+
+
+GNU extensions to the S2K algorithm
+===================================
+S2K mode 101 is used to identify these extensions.
+After the hash algorithm the 3 bytes "GNU" are used to make
+clear that these are extensions for GNU, the next bytes gives the
+GNU protection mode - 1000.  Defined modes are:
+  1001 - do not store the secret part at all
+  1002 - a stub to access smartcards (not used in 1.2.x)
+
+
+Pipemode
+========
+NOTE:  This is deprecated and will be removed in future versions.
+
+This mode can be used to perform multiple operations with one call to
+gpg. It comes handy in cases where you have to verify a lot of
+signatures. Currently we support only detached signatures.  This mode
+is a kludge to avoid running gpg n daemon mode and using Unix Domain
+Sockets to pass the data to it.  There is no easy portable way to do
+this under Windows, so we use plain old pipes which do work well under
+Windows.  Because there is no way to signal multiple EOFs in a pipe we
+have to embed control commands in the data stream: We distinguish
+between a data state and a control state.  Initially the system is in
+data state but it won't accept any data.  Instead it waits for
+transition to control state which is done by sending a single '@'
+character.  While in control state the control command os expected and
+this command is just a single byte after which the system falls back
+to data state (but does not necesary accept data now).  The simplest
+control command is a '@' which just inserts this character into the
+data stream.
+
+Here is the format we use for detached signatures:
+"@<"  - Begin of new stream
+"@B"  - Detached signature follows.
+        This emits a control packet (1,'B')
+<detached_signature>
+"@t"  - Signed text follows. 
+        This emits the control packet (2, 'B')
+<signed_text>
+"@."  - End of operation. The final control packet forces signature
+        verification
+"@>"  - End of stream   
+
+
+
+
+
+
+Other Notes
+===========
+    * For packet version 3 we calculate the keyids this way:
+	RSA	:= low 64 bits of n
+	ELGAMAL := build a v3 pubkey packet (with CTB 0x99) and calculate
+		   a rmd160 hash value from it. This is used as the
+		   fingerprint and the low 64 bits are the keyid.
+
+    * Revocation certificates consist only of the signature packet;
+      "import" knows how to handle this.  The rationale behind it is
+      to keep them small.
+
+
+
+
+
+
+
+Keyserver Message Format
+=========================
+
+The keyserver may be contacted by a Unix Domain socket or via TCP.
+
+The format of a request is:
+
+====
+command-tag
+"Content-length:" digits
+CRLF
+=======
+
+Where command-tag is
+
+NOOP
+GET <user-name>
+PUT
+DELETE <user-name>
+
+
+The format of a response is:
+
+======
+"GNUPG/1.0" status-code status-text
+"Content-length:" digits
+CRLF
+============
+followed by <digits> bytes of data
+
+
+Status codes are:
+
+     o	1xx: Informational - Request received, continuing process
+
+     o	2xx: Success - The action was successfully received, understood,
+	and accepted
+
+     o	4xx: Client Error - The request contains bad syntax or cannot be
+	fulfilled
+
+     o	5xx: Server Error - The server failed to fulfill an apparently
+	valid request
+
+
+
+Documentation on HKP (the http keyserver protocol):
+
+A minimalistic HTTP server on port 11371 recognizes a GET for /pks/lookup.
+The standard http URL encoded query parameters are this (always key=value):
+
+- op=index (like pgp -kv), op=vindex (like pgp -kvv) and op=get (like
+  pgp -kxa)
+
+- search=<stringlist>. This is a list of words that must occur in the key.
+  The words are delimited with space, points, @ and so on. The delimiters
+  are not searched for and the order of the words doesn't matter (but see
+  next option).
+
+- exact=on. This switch tells the hkp server to only report exact matching
+  keys back. In this case the order and the "delimiters" are important.
+
+- fingerprint=on. Also reports the fingerprints when used with 'index' or
+  'vindex'
+
+The keyserver also recognizes http-POSTs to /pks/add. Use this to upload
+keys.
+
+
+A better way to do this would be a request like:
+
+   /pks/lookup/<gnupg_formatierte_user_id>?op=<operation>
+
+This can be implemented using Hurd's translator mechanism.
+However, I think the whole key server stuff has to be re-thought;
+I have some ideas and probably create a white paper.
+
diff --git a/rt/docs/design_docs/rql_parser_machine.graphviz b/rt/docs/design_docs/rql_parser_machine.graphviz
index 36463ecc9..93ea989c1 100644
--- a/rt/docs/design_docs/rql_parser_machine.graphviz
+++ b/rt/docs/design_docs/rql_parser_machine.graphviz
@@ -2,6 +2,9 @@
 /* GraphViz graph representing the state diagram of the RQL parser.
 */
 
+/* XXX: It's not up to date anymore, we should delete it or update.
+*/
+
 digraph G {
 
     PAREN -> PAREN;
diff --git a/rt/docs/design_docs/string-extraction-guide.txt b/rt/docs/design_docs/string-extraction-guide.txt
index bd60a43fa..757a27014 100644
--- a/rt/docs/design_docs/string-extraction-guide.txt
+++ b/rt/docs/design_docs/string-extraction-guide.txt
@@ -1,5 +1,5 @@
 # $File: //depot/RT/rt-devel/docs/design_docs/string-extraction-guide.txt $ $Author: ivan $
-# $Revision: 1.1 $ $Change: 1431 $ $DateTime: 2002/10/15 17:24:45 $
+# $Revision: 1.1.1.2 $ $Change: 1431 $ $DateTime: 2002/10/15 17:24:45 $
 
 Run 'p4 edit lib/RT/I18N/zh_tw.pm' and 'perl l10n.pl' to add new
 extractions to the zh_tw.pm.
@@ -63,11 +63,11 @@ that this will genereate code which will not work in RT 2.1.3. I need
 to add a bit of framework to make it work in 2.1.4
 
 
-The string	<& /Elements/TitleBoxStart, width=> "40%", titleright => "RT $RT::VERSION for   $RT::rtname", title => 'Login' &>
+The string	<& /Elements/TitleBoxStart, width=> "40%", titleright => "RT $RT::VERSION for ". RT->Config->Get('rtname'), title => 'Login' &>
 
 should become 	<& /Elements/TitleBoxStart, 
 			width=> "40%",
-			titleright => loc("RT [_1] for [_2]",$RT::VERSION, $RT::rtname),
+			titleright => loc("RT [_1] for [_2]",$RT::VERSION, RT->Config->Get('rtname')),
 			title => loc('Login'),
 	      	&>
 	
diff --git a/rt/docs/extending_clickable_links.pod b/rt/docs/extending_clickable_links.pod
new file mode 100644
index 000000000..643267374
--- /dev/null
+++ b/rt/docs/extending_clickable_links.pod
@@ -0,0 +1,157 @@
+=head1 MakeClicky extension
+
+=head2 Description
+
+I<MakeClicky> detects various formats of data in headers and email
+messages, and extends them with supporting links.
+
+=head2 Configuration
+
+You can configure clicky actions from RT config with @Active_MakeClicky
+option. It's ordered of the actions you want to apply.
+
+By default, RT provides two actions:
+
+=over 4
+
+=item httpurl
+
+Detects http:// and https:// URLs and adds '[Open URL]' link after the URL.
+
+=item httpurl_overwrite
+
+Also detects URLs as 'httpurl' format, but replace URL with link
+and *adds spaces* into text if it's longer then 30 chars. This allow
+browser to wrap long URLs and avoid horizontal scrolling.
+
+=back
+
+RTIR is shipped with several actions you can use: 'ip', 'ipdecimal',
+'email', 'domain' and 'RIPE'.
+
+=head2 Order of clicky actions
+
+Order of actions is important in situations when you use actions that
+could match the same block of a text, in this case only the first matching
+action from the list would be applied. For example ot makes no sense to
+use C<httpurl> and C<httpurl_overwrite> at the same time as both actions
+always match the same piece of a text.
+
+=head2 How it works
+
+Each action consists of regular expression and function that do text replace.
+When you open history of a ticket RT search in the text with the regular expresion
+for matches. If some piece of the text matches it calls the function with the match
+as argument, then replace matched text with string returned by the function. So
+in two words this feature works like 'Search and Replace' with an active replacer.
+
+Text of tickets is plain, but actions could generate arbitrary HTML.
+
+=head2 Writing custom MakeClicky actions
+
+To extend the list of actions with your own types of data, use the callback. Create
+file F<local/html/Callbacks/MyCallbacks/Elements/MakeClicky/Default>.
+
+It will be provided with arguments:
+
+=over 4
+
+=item types
+
+An array reference of hash references.  Modify this array
+reference to add your own types; the first matching type will be
+used. Each hashref should contain:
+
+=over 4
+
+=item name
+
+The name of the data format; this is used in the
+configuration file to enable the format.
+
+=item regex
+
+A regular expression to match against.
+
+=item action
+
+The name of the action to run (see "actions", below)
+
+=back
+
+=item actions
+
+A hash reference of 'actions'.  Modify this hash reference to change or add
+action types.  Values are subroutine references which will get called when needed.
+They should return the modified string. Note that subroutine B<must escape> HTML.
+
+=item handler
+
+A subroutine reference; modify it only if you have to. This can be used
+to add pre- or post-processing around all actions.
+
+=back
+
+=head2 Actions' arguments
+
+A hash is passed to action with two keys that always exist:
+
+=over 4
+
+=item value - full match of the regular expression, this block of text will be
+replaced with action's result.
+
+=item all_matches - array with all matches including groups defined in the
+regular expression, for example if your regexp is C<qr{ticket\s+#(\d+)}> then
+the first element will be full match ("ticket #XXX") the same as in 'value' key,
+but the second one element of the array will be id of a ticket (XXX), so you
+can avoid parsing value in the action. Only eight groups of your regexps are
+passed to actions.
+
+=back
+
+=head2 Custom MakeClicky action example
+
+Create a new file F</opt/rt3/local/html/Callbacks/MyCallbacks/Elements/MakeClicky/Default>
+with the content:
+
+  <%ARGS>
+  $types   => []
+  $actions => {}
+  </%ARGS>
+  <%INIT>
+  my $web_path = RT->Config->Get('WebPath');
+  
+  # action that takes ticket ID as argument and returns link to the ticket
+  $actions->{'link_ticket'} = sub {
+      my %args = @_;
+      my $id = $args{'all_matches'}[1];
+      return qq{<a href="$web_path/Ticket/Display.html?id=$id">$args{value}</a>};
+  };
+  
+  # add action to the list
+  push @$types, {
+      # name, that should be used in config to activate action
+      name   => 'short_ticket_link',
+      # regular expression that matches text 'ticket #xxx'
+      regex  => qr{ticket\s+#(\d+)}i,
+      # name of the action that should be applied
+      action => 'link_ticket',
+  };
+  </%INIT>
+
+That's all. Add C<short_ticket_link> to C<@Active_MakeClicky> option in your C<RT_SiteConfig.pm>.
+Restart your server and create test ticket with 'ticket #1' text.
+
+=head2 Notes for custom clicky actions writers
+
+Note that an action B<must escape> illegal HTML characters with entities and/or
+arguments in URLs.
+
+Complex (slow) regular expressions could slow down RT as conversion is run each
+time user open a ticket.
+
+Try to match the shortest expression you need with your regular expression otherwise another action could miss its chance to match.
+
+Precalculate values, use closures for functions.
+
diff --git a/rt/docs/gnupg_integration.pod b/rt/docs/gnupg_integration.pod
new file mode 100644
index 000000000..805ed1b78
--- /dev/null
+++ b/rt/docs/gnupg_integration.pod
@@ -0,0 +1 @@
+This topic is described better in `perldoc lib/RT/Crypt/GnuPG.pm`.
diff --git a/rt/docs/porting.windows b/rt/docs/porting.windows
new file mode 100644
index 000000000..44b412b2e
--- /dev/null
+++ b/rt/docs/porting.windows
@@ -0,0 +1,24 @@
+Currently, RT is not very greatly supported on windows, 
+But we can really run RT now, though very basicly.
+
+Scary instructions( tested on windows xp ):
+1. Install stawberry perl 5.10 or later
+2. Install Bundle::libwin32
+3. Install all cpan modules in vessel except
+cpan-Module-Signature,cpan-GnuPG-Interface,cpan-GD,cpan-IO-Tty.
+
+If you have vessel, you can run the following cmd to install:
+perl bin\shipwright-builder --skip-test --noclean --make dmake --skip cpan-Module-Signature,cpan-GnuPG-Interface,cpan-GD,cpan-IO-Tty,perl,freetype,expat,fontconfig,ncurses,readline,gnupg,libjpeg,zlib,libpng,libgd,RT
+( If you install the modules to other place, e.g. with --install-base C:\test,
+remember to add C:/test/lib/perl5 to PERL5LIB env )
+
+Else, you can install them( the list is extracted from vessel ) by CPAN:
+
+$ perl -MCPAN -e "notest install Module::Build ExtUtils::MakeMaker Devel::Symdump Pod::Coverage Test::Pod::Coverage Regexp::Common Test::Portability::Files Pod::Readme Sub::Uplevel Test::Exception Tree::Simple URI::Escape Text::WikiFormat Locale::Maketext::Fuzzy Class::MethodMaker Devel::StackTrace Class::ReturnValue Carp::Assert Carp::Assert::More HTTP::Server::Simple Test::LongString HTML::Tagset HTML::Entities IO::Uncompress::Base Compress::Raw::Zlib IO::Uncompress::Gunzip Compress::Zlib Encode LWP::UserAgent WWW::Mechanize Test::WWW::Mechanize Text::Template HTML::TreeBuilder GD::Text Tree::DAG_Node Array::Compare Test::Warn Test::Tester Test::NoWarnings Class::Accessor Class::Accessor::Chained::Fast Text::vFile::asData Data::ICal Time::ParseDate Class::Data::Inheritable Exception::Class Params::Validate Class::Container Digest::SHA1 Error Cache::Cache HTML::Mason Test::More GD::Graph DBI XML::NamespaceSupport XML::SAX XML::Simple Cache::Simple::TimedExpiry Test::HTTP::Server::Simple Params::Util Class::Inspector File::ShareDir DBD::SQLite Clone Want DBIx::SearchBuilder PerlIO::eol Module::Refresh Text::Wrapper Log::Dispatch Log::Dispatch::Perl HTML::RewriteAttributes String::ShellQuote Email::Address FCGI Test::Deep Module::Versions::Report Text::Reform Text::Autoformat Text::Quoted Class::Singleton DateTime::TimeZone List::MoreUtils DateTime::Locale DateTime Calendar::Simple Apache::Session Term::ReadKey Hook::LexWrap HTTP::Server::Simple::Mason Net::Server IPC::Run3 DBD::mysql CSS::Squish HTML::Scrubber Expect Expect::Simple Test::Expect Locale::Maketext::Lexicon Font::AFM Pod::Escapes Pod::Simple HTML::FormatText Test::Pod MIME::Types CGI::Fast UNIVERSAL::require version DBD::Pg Date::Format Mail::Mailer IO::Stringy File::Temp MIME::Entity Test::Manifest XML::Parser DateTime::Format::W3CDTF DateTime::Format::Mail XML::RSS Time::Piece Test::MockTime"
+
+4. configure RT on unix box with inplace layout, copy the configured RT to the
+windows place you want, e.g. C:\RT 
+
+5. cd to C:\RT, you can run RT now by the cmd:
+perl bin\standalone_httpd 8080
+
diff --git a/rt/docs/queue_subject_tag.pod b/rt/docs/queue_subject_tag.pod
new file mode 100644
index 000000000..084c8132f
--- /dev/null
+++ b/rt/docs/queue_subject_tag.pod
@@ -0,0 +1,79 @@
+=head1 INTRODUCTION
+
+This text is about 'Subject Tag' property of a queue. This
+property allows you to use different tags in subjects of
+RT's notifications, by default it's rtname option from
+the config file as it's been for a long time, now you can
+use different values for different queues.
+
+=head1 CONFIGURATION
+
+=head2 Setting subject tag
+
+Open RT's web UI, goto -E<gt> Configuration -E<gt> Queues
+-E<gt> select a queue -E<gt> set 'subject tag' -E<gt>
+save changes.
+
+=head2 Using tag in templates
+
+Usually you don't need to add some code into templates to
+make subject tags work. A tag will be added in the
+beginning of subject right before sending email out.
+
+If you want to subjects to be "prefix [tag] real subject" like
+in default autoreply then you can use the following code in
+templates to place subject tag whenever you want in a template:
+
+    [{ $Ticket->QueueObj->SubjectTag || $rtname } #{$Ticket->id()}]
+
+B<Note> that in the extension from the CPAN Tag method have
+been used when in 3.8 and newer it's SubjectTag, so you have to upgrade
+your templates. Read L</UPGRADING> below.
+    
+=head1 This functionality vs. RT-Extension-BrandedQueues
+
+RT-Extension-BrandedQueues is extension that's available from
+the CPAN for older versions of RT. Starting from RT 3.8 it's
+been integrated into RT core. If you are B<UPGRADING> from
+older version and were using extension from the CPAN then you
+MUST read L</UPGRADING> below.
+
+=head1 UPGRADING
+
+=head2 For everyone who is upgrading
+
+You need to modify any of your email templates which use
+the $rtname variable. To edit your templates, log into RT
+as your administrative user, then click:
+
+Configuration -> Global -> Templates -> <Some template name>
+
+For example, RT's default "Autoreply" includes this line:
+
+ "There is no need to reply to this message right now.  Your ticket has been
+ assigned an ID of [{$rtname} #{$Ticket->id()}]."
+
+Change this line to read:
+
+ "There is no need to reply to this message right now.  Your ticket has been
+ assigned an ID of [{ $Ticket->QueueObj->SubjectTag || $rtname } #{$Ticket->id()}]."
+
+=head2 For users of RT-Extension-BrandedQueues
+
+1) You MUST uninstall RT-Extension-BrandedQueues before upgrade
+or use clean new dir for installation and reinstall your local
+customizations. The latter way is recommended as there are many
+changes in RT 3.8 and several extensions have been integrated
+into core.
+
+2) We expect that you have backup of your RT DB around during upgrade.
+
+3) After upgrade run perl script 'etc/upgrade/3.8-branded-queues-extension'.
+This script will convert data in the DB into new format.
+
+4) In templates where you were using Tag method (for example
+C<< $Ticket-E<gt>QueueObj-E<gt>Tag >>) replace it with
+C<< $Ticket-E<gt>QueueObj-E<gt>SubjectTag >>. Read more in
+L</"Using tag in templates">
+
+=cut
diff --git a/rt/docs/templates.pod b/rt/docs/templates.pod
new file mode 100644
index 000000000..76856d456
--- /dev/null
+++ b/rt/docs/templates.pod
@@ -0,0 +1,60 @@
+=head1 Templates
+
+Each template is split into two sections. A block of headers and a body. These
+sections are separated by a blank line.
+
+=head2 Headers
+
+Your template may specify arbitrary email headers. Each header is a name, a
+colon, then a value. So, for example, to specify a subject, you can use:
+
+    Subject: Thanks for your bug report.
+
+=head3 Special Headers
+
+=over
+
+=item Content-Type: text/html
+
+The special header "Content-Type: text/html" tells RT that the template should
+be parsed as HTML. RT will automatically make the outgoing message multipart.
+That way, recipients who can read only plaintext email will receive something
+readable, while users with clients which can display HTML will receive the full
+experience. Please be aware that HTML support in mail clients varies greatly,
+much more so than different web browsers.
+
+We welcome contributions of HTML-ization of builtin templates.
+
+=back
+
+=head2 Variables
+
+The variables that your templates may use include:
+
+=over 4
+
+=item C<$Transaction>
+
+The transaction object.
+
+=item C<$rtname>
+
+The value of the "rtname" config variable.
+
+=item C<$Ticket>
+
+The ticket object. This is only set during a ticket transaction.
+
+=item C<$Requestor>
+
+This is not an object, but the name of the first requestor on the ticket.
+If this is not what you need, inspect C<< $Ticket->Requestors >>.
+
+=item C<loc("text")>
+
+A localization function. See L<Locale::Maketext>.
+
+=back
+
+=cut
+
diff --git a/rt/docs/using_forms_widgets.pod b/rt/docs/using_forms_widgets.pod
new file mode 100644
index 000000000..8deb91362
--- /dev/null
+++ b/rt/docs/using_forms_widgets.pod
@@ -0,0 +1,113 @@
+=head1 Using widgets F<html/Widgets/Form*>
+
+This widgets was implemented to address several common issues in handling
+request arguments and allow developers to avoid reinventing the wheel.
+
+=head2 General info
+
+Each component shows widget by default and has two methods: Process and 
+InputOnly. The first one method process arguments and return new value
+of a parametr. The second one is helper that shows only form elements
+with minimum of required text labels.
+
+So you show a widget with:
+    <& /Widgets/Form/Integer,
+        Name => 'NameOfInputElement',
+        Description => 'Input integer',
+    &>
+
+You can show only C<input> box using:
+    <& /Widgets/Form/Integer:InputOnly,
+        Name => 'NameOfInputElement',
+    &>
+
+In such a simple case you even can avoid processing. Yeah, most probably
+you want to check if value is really integer, but these widgets don't
+do validation for you, but they are more about fetching values from
+hash of arguments, showing these values to user and preserving state
+of value between form reloads (see below).
+
+=head2 Processing
+
+Processing is required when you use L<extended features|/Extendent features>,
+such as Default, Multiple or Alternative.
+
+To process arguments of a request you have to do the following:
+    $ARGS{'NameOfInputElement'} = $m->comp(
+        '/Widgets/Form/Integer:Process',
+        Arguments => \%ARGS,
+        Name      => 'NameOfInputElement',
+    );
+
+The method returns processed value in canonical form. For different widgets
+a canonical form is different and depends on activated features, so you must
+always activate the same features during showing a widget and processing
+results.
+
+=head2 Extendent features
+
+=head3 Default value
+
+If C<Default> argument is true then widgets expect that there is some
+default value for argument if user fills nothing. 'Nothing' in each
+widget is different, for example in select box it's special option
+which is always the first one, in integer box string '' means empty
+value, but boolean box uses radio buttons in this case with three
+options: Yes, No and Default.
+
+Each widget that supports C<Default> feature as well has C<DefaultLabel> and
+C<DefaultValue> arguments.
+
+=head4 Processing and showing with activated Default feature
+
+When this option is activated then C<Process> method returns undef
+value if user selected default value. So for integer box it's empty
+string and so on.
+
+As well when you show a widget you should pass undef as C<CurrentValue>
+to inform widget that the current value is default one.
+
+As all methods of a widget are consistent in this behaviour so you
+shouldn't care much about that, but this allows you to implement
+custom actions if processing returned undef, for example delete user's
+preference record instead of updating it (default value may change later to).
+
+=head4 C<DefaultValue> when C<Default> is not active
+
+DefaultValue argument is still actual in the Process method even if
+C<Default> is not true. This argument defines intial value. If value
+of a key in Arguments is not defined then it's treated as intial state
+and the method returns default value.
+
+=head3 Multiple and Alternative
+
+These options are only supported by the select widget.
+
+TODO: Add more info
+
+=head2 Implementation details
+
+=head3 Boolean widget
+
+This widget a little bit tricky. When you use Default option then
+things are simple and you see three radio buttons, but in other
+case we use a checkbox. But as you know browsers don't pass unchecked
+boxes to server, so arguments of a request has no entry for them.
+
+In the latter case it's hard to figure out case when user unselected
+value. Imagine form with a checkbox, you want show it checked by
+default and as well form is reloadable (like Reply forms that have
+"Add Another File" buttons). User uncheck the box and then upload
+file, in this case you want to show user's choice instead of default,
+but browser doesn't send any value and you can not figure out if
+it's initial state or page reload. To solve this problem we use magic
+hidden input field with the same name as the box and value equal to
+zero (0). Mason folds arguments with the same name into array refs, so
+we get 0 if box is unchecked and [0, 1] if box is checked. An array
+reference is true value and 0 is defined value so we know that it's
+not initial state and avoid switching back to default. As well this
+trick works good in a case when you want show a link to a page and
+define default choice for some boolean argument, you don't need
+to set argument twice, you just set it to true value (for ex. 1) and
+things just work.
+
-- 
cgit v1.2.1