From d25db3c903e3b54ab04e87650ee5bfdb4844f310 Mon Sep 17 00:00:00 2001 From: Werner Koch Date: Thu, 18 Aug 2016 12:41:55 +0200 Subject: [PATCH] doc: Add comments on how to parse --list-colons output. -- GnuPG-bug-id: 2437 --- doc/DETAILS | 11 +++++++++-- doc/gpg.texi | 5 +++-- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/doc/DETAILS b/doc/DETAILS index 794026bc1..dc8ba1f7a 100644 --- a/doc/DETAILS +++ b/doc/DETAILS @@ -31,11 +31,18 @@ sub:r:1536:20:5CE086B5B5A18FF4:899817788:1025961788:::::esc: fpr:::::::::AB059359A3B81F410FCFF97F5CE086B5B5A18FF4: #+end_example +Note that new version of GnuPG or the use of certain options may add +new fields to the output. Parsers should not assume a limit on the +number of fields per line. Some fields are not yet used or only used +with certain record types; parsers should ignore fields they are not +aware of. + The double =--with-fingerprint= prints the fingerprint for the subkeys too. Old versions of gpg used a slightly different format and required the use of the option =--fixed-list-mode= to conform to the format described here. + ** Description of the fields *** Field 1 - Type of record @@ -337,8 +344,8 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB: Every line is prefixed with "[GNUPG:] ", followed by a keyword with the type of the status line and some arguments depending on the type - (maybe none); an application should always be prepared to see more - arguments in future versions. + (maybe none); an application should always be prepared to see new + keyworkds or more arguments in future versions. ** General status codes *** NEWSIG [] diff --git a/doc/gpg.texi b/doc/gpg.texi index b9a3ddcd1..52a50f569 100644 --- a/doc/gpg.texi +++ b/doc/gpg.texi @@ -348,9 +348,10 @@ if the keyid format has been set to "none". @item --list-packets @opindex list-packets -List only the sequence of packets. This is mainly useful for +List only the sequence of packets. This command is only useful for debugging. When used with option @option{--verbose} the actual MPI -values are dumped and not only their lengths. +values are dumped and not only their lengths. Note that the output of +this command may change with new releases. @item --card-edit