Reformat README and minor gpg.texi improvement.

--

The second thing is to explain the file names below under
~/.gnupg/openpgp-revocs.d/.

README

@@ -8,29 +8,27 @@
           Copyright 1998-2013 Free Software Foundation, Inc.
 
 
-INTRODUCTION
+* INTRODUCTION
-============
 
-GnuPG is a tool for secure communication and data storage.  It can be
+  GnuPG is a tool for secure communication and data storage.  It can
-used to encrypt data and to create digital signatures.  It includes an
+  be used to encrypt data and to create digital signatures.  It
-advanced key management facility and is compliant with the proposed
+  includes an advanced key management facility and is compliant with
-OpenPGP Internet standard as described in RFC4880 and the S/MIME
+  the proposed OpenPGP Internet standard as described in RFC4880 and
-standard as described by several RFCs.
+  the S/MIME standard as described by several RFCs.
 
   GnuPG is distributed under the terms of the GNU General Public
   License.  See the file COPYING for details.  GnuPG works best on
   GNU/Linux or *BSD systems.  Most other Unices are also supported but
   are not as well tested as the Free Unices.
 
-GnuPG-2 is the stable version of GnuPG integrating support for OpenPGP
+  GnuPG-2 is the stable version of GnuPG integrating support for
-and S/MIME.  It does not conflict with an installed 1.4 OpenPGP-only
+  OpenPGP and S/MIME.  It does not conflict with an installed 1.4
-version.
+  OpenPGP-only version.
 
 
-BUILD INSTRUCTIONS
+* BUILD INSTRUCTIONS
-==================
 
-GnuPG 2.1 depends on the following packages:
+  GnuPG 2.1 depends on the following GnuPG related packages:
 
     npth         (ftp://ftp.gnupg.org/gcrypt/npth/)
     libgpg-error (ftp://ftp.gnupg.org/gcrypt/libgpg-error/)
@@ -41,18 +39,18 @@ GnuPG 2.1 depends on the following packages:
   You should get the latest versions of course, the GnuPG configure
   script complains if a version is not sufficient.
 
-For some advanced features several other libraries are required.  The
+  For some advanced features several other libraries are required.
-configure script prints diagnostic messages if one of these libraries
+  The configure script prints diagnostic messages if one of these
-is not available and a feature will not be available..
+  libraries is not available and a feature will not be available..
 
   You also need the Pinentry package for most functions of GnuPG;
   however it is not a build requirement.  Pinentry is available at
   ftp://ftp.gnupg.org/gcrypt/pinentry/ .
 
-After building and installing the above packages in the order as given
+  After building and installing the above packages in the order as
-above, you may continue with GnuPG installation (you may also just try
+  given above, you may continue with GnuPG installation (you may also
-to build GnuPG to see whether your already installed versions are
+  just try to build GnuPG to see whether your already installed
-sufficient).
+  versions are sufficient).
 
   As with all packages, you just have to do
 
@@ -64,8 +62,8 @@ As with all packages, you just have to do
 
   If everything succeeds, you have a working GnuPG with support for
   OpenPGP, S/MIME, ssh-agent, and smartcards.  Note that there is no
-binary gpg but a gpg2 so that this package won't conflict with a GnuPG
+  binary gpg but a gpg2 so that this package won't conflict with a
-1.4 installation.  gpg2 behaves just like gpg.
+  GnuPG 1.4 installation.  gpg2 behaves just like gpg.
 
   In case of problem please ask on the gnupg-users@gnupg.org mailing
   list for advise.
@@ -74,10 +72,10 @@ Instruction on how to build for Windows can be found in the file
   doc/HACKING in the section "How to build an installer for Windows".
   This requires some experience as developer.
 
-Note that the PKITS tests are always skipped unless you copy the PKITS
+  Note that the PKITS tests are always skipped unless you copy the
-test data file into the tests/pkits directory.  There is no need to
+  PKITS test data file into the tests/pkits directory.  There is no
-run these test and some of them may even fail because the test scripts
+  need to run these test and some of them may even fail because the
-are not yet complete.
+  test scripts are not yet complete.
 
   You may run
 
@@ -92,30 +90,41 @@ Speedo method may be used:
 
   This method downloads all required libraries and does a native build
   of GnuPG to PLAY/inst/.  GNU make is required and you need to set
-LD_LIBRARY_PATH to $(pwd)/PLAY/inst/lib.
+  LD_LIBRARY_PATH to $(pwd)/PLAY/inst/lib to test the binaries.
+
+** Specific build problems on some machines:
+
+*** Apple OSX 10.x using XCode
+
+  On some versions the correct location of a header file can't be
+  detected by configure.  To fix that you should run configure like
+  this
+
+    ./configure  gl_cv_absolute_stdint_h=/usr/include/stdint.h
+
+  Add other options as needed.
 
 
-MIGRATION FROM 1.4 or 2.0 to 2.1
+* MIGRATION from 1.4 or 2.0 to 2.1
-================================
 
-The major change in 2.1 is gpg-agent taking care of the OpenPGP secret
+  The major change in 2.1 is gpg-agent taking care of the OpenPGP
-keys (those managed by GPG).  The former file "secring.gpg" will not
+  secret keys (those managed by GPG).  The former file "secring.gpg"
-be used anymore.  Newly generated keys are stored in the agent's key
+  will not be used anymore.  Newly generated keys are stored in the
-store directory "~/.gnupg/private-keys-v1.d/".  The first time gpg
+  agent's key store directory "~/.gnupg/private-keys-v1.d/".  The
-needs a secret key it checks whether a "secring.gpg" exists and
+  first time gpg needs a secret key it checks whether a "secring.gpg"
-copies them to the new store.  The old secring.gpg is kept for use by
+  exists and copies them to the new store.  The old secring.gpg is
-older versions of gpg.
+  kept for use by older versions of gpg.
-
-Note that gpg-agent now uses a fixed socket by default.  All tools
-will start the gpg-agent as needed.  In general there is no more need
-to set the GPG_AGENT_INFO environment variable.  The SSH_AUTH_SOCK
-environment variable should be set to a fixed value.
 
   GPG's smartcard commands --card-edit and --card-status as well as some
   of the card related sub-commands of --edit-key are not yet fully
   supported.  However, signing and decryption with a smartcard does
   work.
 
+  Note that gpg-agent now uses a fixed socket by default.  All tools
+  will start the gpg-agent as needed.  In general there is no more
+  need to set the GPG_AGENT_INFO environment variable.  The
+  SSH_AUTH_SOCK environment variable should be set to a fixed value.
+
   The Dirmngr is now part of GnuPG proper and also used to access
   OpenPGP keyservers.  The directroy layout of Dirmngr changed to make
   use of the GnuPG directories.  Dirmngr is started by gpg or gpgsm as
@@ -124,43 +133,40 @@ package.
 
 
 
-DOCUMENTATION
+* DOCUMENTATION
-=============
 
   The complete documentation is in the texinfo manual named
-`gnupg.info'.  Run "info gnupg" to read it.  If you want a a printable
+  `gnupg.info'.  Run "info gnupg" to read it.  If you want a a
-copy of the manual, change to the "doc" directory and enter "make pdf"
+  printable copy of the manual, change to the "doc" directory and
-For a HTML version enter "make html" and point your browser to
+  enter "make pdf" For a HTML version enter "make html" and point your
-gnupg.html/index.html.  Standard man pages for all components are
+  browser to gnupg.html/index.html.  Standard man pages for all
-provided as well.  An online version of the manual is available at
+  components are provided as well.  An online version of the manual is
-http://www.gnupg.org/documentation/manuals/gnupg/ .  A version of the
+  available at http://www.gnupg.org/documentation/manuals/gnupg/ .  A
-manual pertaining to the current development snapshot is at
+  version of the manual pertaining to the current development snapshot
-http://www.gnupg.org/documentation/manuals/gnupg-devel/ .
+  is at http://www.gnupg.org/documentation/manuals/gnupg-devel/ .
 
 
-GNUPG 1.4 AND GNUPG 2.0
+* GnuPG 1.4 and GnuPG 2.0
-=======================
 
   GnuPG 2.0 is a newer version of GnuPG with additional support for
   S/MIME.  It has a different design philosophy that splits
-functionality up into several modules.  Both versions may be installed
+  functionality up into several modules.  Both versions may be
-simultaneously without any conflict (gpg is called gpg2 in GnuPG 2).
+  installed simultaneously without any conflict (gpg is called gpg2 in
-In fact, the gpg version from GnuPG 1.4 is able to make use of the
+  GnuPG 2).  In fact, the gpg version from GnuPG 1.4 is able to make
-gpg-agent as included in GnuPG 2 and allows for seamless passphrase
+  use of the gpg-agent as included in GnuPG 2 and allows for seamless
-caching.  The advantage of GnuPG 1.4 is its smaller size and no
+  passphrase caching.  The advantage of GnuPG 1.4 is its smaller size
-dependency on other modules at run and build time.
+  and no dependency on other modules at run and build time.
 
 
-HOW TO GET MORE INFORMATION
+* HOW TO GET MORE INFORMATION
-===========================
 
   The primary WWW page is "https://www.gnupg.org"
              or using TOR "http://ic6au7wa3f6naxjq.onion"
   The primary FTP site is "ftp://ftp.gnupg.org/gcrypt/"
 
-See https://www.gnupg.org/download/mirrors.html for a list of mirrors
+  See https://www.gnupg.org/download/mirrors.html for a list of
-and use them if possible.  You may also find GnuPG mirrored on some of
+  mirrors and use them if possible.  You may also find GnuPG mirrored
-the regular GNU mirrors.
+  on some of the regular GNU mirrors.
 
   We have some mailing lists dedicated to GnuPG:
 
@@ -181,30 +187,36 @@ We have some mailing lists dedicated to GnuPG:
      gnupg-devel@gnupg.org      GnuPG developers main forum.
 
   You subscribe to one of the list by sending mail with a subject of
-"subscribe" to x-request@gnupg.org, where x is the name of the mailing
+  "subscribe" to x-request@gnupg.org, where x is the name of the
-list (gnupg-announce, gnupg-users, etc.).  An archive of the mailing
+  mailing list (gnupg-announce, gnupg-users, etc.). See
-lists are available at http://www.gnupg.org/documentation/mailing-lists.html
+  https://www.gnupg.org/documentation/mailing-lists.html for archives
+  of the mailing lists.
 
-Please direct bug reports to http://bugs.gnupg.org or post them direct
+  Please direct bug reports to http://bugs.gnupg.org or post them
-to the mailing list <gnupg-devel@gnupg.org>.
+  direct to the mailing list <gnupg-devel@gnupg.org>.
 
   Please direct questions about GnuPG to the users mailing list or one
-of the pgp newsgroups; please do not direct questions to one of the
+  of the PGP newsgroups; please do not direct questions to one of the
-authors directly as we are busy working on improvements and bug fixes.
+  authors directly as we are busy working on improvements and bug
-The English and German mailing lists are watched by the authors and we
+  fixes.  The English and German mailing lists are watched by the
-try to answer questions when time allows us to do so.
+  authors and we try to answer questions when time allows us.
 
   Commercial grade support for GnuPG is available; for a listing of
   offers see https://www.gnupg.org/service.html .  Maintaining and
   improving GnuPG is costly.  Since 2001, g10 Code GmbH, a German
   company owned and headed by GnuPG's principal author Werner Koch, is
-bearing the majority of these costs.  To help them carry on this work,
+  bearing the majority of these costs.  To help them carry on this
-they need your support.  See https://gnupg.org/donate/ .
+  work, they need your support.  See https://gnupg.org/donate/ .
 
-  This file is Free Software; as a special exception the authors gives
+
-  unlimited permission to copy and/or distribute it, with or without
+# This file is Free Software; as a special exception the authors gives
-  modifications, as long as this notice is preserved. For conditions
+# unlimited permission to copy and/or distribute it, with or without
-  of the whole package, please see the file COPYING.  This file is
+# modifications, as long as this notice is preserved. For conditions
-  distributed in the hope that it will be useful, but WITHOUT ANY
+# of the whole package, please see the file COPYING.  This file is
-  WARRANTY, to the extent permitted by law; without even the implied
+# distributed in the hope that it will be useful, but WITHOUT ANY
-  warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# WARRANTY, to the extent permitted by law; without even the implied
+# warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+#
+# Local Variables:
+# mode:org
+# End:

doc/gpg.texi

@@ -3159,12 +3159,13 @@ files; They all live in in the current home directory (@pxref{option
 
   @item ~/.gnupg/openpgp-revocs.d/
   This is the directory where gpg stores pre-generated revocation
-  certificates.  It is suggested to backup those certificates and if the
+  certificates.  The file name corresponds to the OpenPGP fingerprint of
-  primary private key is not stored on the disk to move them to an
+  the respective key.  It is suggested to backup those certificates and
-  external storage device.  Anyone who can access theses files is able to
+  if the primary private key is not stored on the disk to move them to
-  revoke the corresponding key.  You may want to print them out.  You
+  an external storage device.  Anyone who can access theses files is
-  should backup all files in this directory and take care to keep this
+  able to revoke the corresponding key.  You may want to print them out.
-  backup closed away.
+  You should backup all files in this directory and take care to keep
+  this backup closed away.
 
   @item /usr[/local]/share/gnupg/options.skel
   The skeleton options file.