Encourage having separate userids for name and email

Closes #22

1 files changed, 22 insertions, 21 deletions

diff --git a/sq-guide.md b/sq-guide.md
index a7bc59c..750ad62 100644
--- a/sq-guide.md
+++ b/sq-guide.md
@@ -1,7 +1,7 @@
 ---
-title: "User guide for Sequoia PGP `sq`"
+title: "User guide for Sequoia-PGP `sq`"
 subtitle: "Keeping private things private"
-author: "The Sequoia PGP project"
+author: "The Sequoia-PGP project"
 documentclass: report
 ...
 
@@ -27,7 +27,7 @@ chapter distils the main content of this guide into examples showing
 a small number of common use cases. No explanations.
 
 ```{.sh .numberLines}
-$ sq key generate --userid="My Name <me@example.com>" --export=key.pgp
+$ sq key generate --userid="My Name" --userid="<me@example.com>" --export=key.pgp
 $ sq key extract-cert --output=cert.pgp key.pgp
 $ ls -l
 total 8
@@ -77,13 +77,13 @@ $ ls -l decrypted.md
 
 # Introduction
 
-## What are Sequoia PGP and `sq`?
+## What are Sequoia-PGP and `sq`?
 
-[Sequoia PGP project]: https://sequoia-pgp.org/
+[Sequoia-PGP project]: https://sequoia-pgp.org/
 [Rust programming language]: https://www.rust-lang.org/
 [sequoia-openpgp]: https://gitlab.com/sequoia-pgp/sequoia/-/tree/main/openpgp
 
-The [Sequoia PGP project][] works to make use of cryptography for privacy
+The [Sequoia-PGP project][] works to make use of cryptography for privacy
 and authentication in communication more commonplace. The project
 produces and maintains an implementation of the OpenPGP standard
 that's easy and uncomplicated to use.
@@ -92,8 +92,8 @@ OpenPGP is used widely in the IT industry and by free and open source
 projects to verify the authenticity of software packages, and for
 encrypting and authenticating messages.
 
-`sq` is the command line tool provided by Sequoia PGP. It's easy and
-uncomplicated to use. Sequoia PGP also provides a library for the
+`sq` is the command line tool provided by Sequoia-PGP. It's easy and
+uncomplicated to use. Sequoia-PGP also provides a library for the
 [Rust programming language][], called [sequoia-openpgp][]. However,
 the library is only of interest to software developers, and this guide
 is aimed at users of the `sq` tool.
@@ -149,7 +149,7 @@ specified by the OpenPGP standard:
 * encrypting and decrypting data
 
 The guide shows how to use the `sq` command line tool from
-Sequoia PGP. It does not cover integrating Sequoia PGP with mail
+Sequoia-PGP. It does not cover integrating Sequoia-PGP with mail
 software, version control, file transfer software, or other
 applications. (That will be covered by other documentation.)
 
@@ -171,7 +171,7 @@ This guide has the following structure:
   underlying concepts.
 * There is also an appendix with a glossary, which can be helpful for
   looking up unknown terminology, and another appendix with links to
-  additional material relevant to Sequoia PGP and cryptography.
+  additional material relevant to Sequoia-PGP and cryptography.
 * The rest of this guide is discussions of the concepts needed
   to understand how cryptography works, and how to use it well.
 
@@ -705,17 +705,18 @@ better to have a non-expiring key than not have a key at all.
 To generate a key with `sq`:
 
 ```sh
-sq key generate --userid="My Name <me@example.com>" --export=key.pgp
+sq key generate --userid="My Name" --userid="<me@example.com>" --export=key.pgp
 ```
 
-The _user id_ should usually have the form "`Name <email@address>`".
-The software doesn't mandate this, but much software that uses OpenPGP
-relies on the convention. For example, when a email program looks up a
-certificate for a recipient, it uses the email address to do so. If
-the user id does not include the email address, the lookup fails.
+A key can have any number of _user identifiers_ (or _user ids_). The
+Sequoia project suggests that it's best to have separate user ids for
+name and email address to allow them to be certified separately (we'll
+discuss what that means later). Traditionally they have been combined
+into one id, and that still works.
 
-A key can have several user ids, which is handy for people who have
-several email addresses at once or over time.
+When a email program looks up a certificate for a recipient, it uses
+the email address to do so. At least one user id should contain the
+email address for the lookup to work.
 
 You can set an expiration time at the time of creating a key, if you
 want. See the `--expires` and `--expires-in` options.
@@ -986,7 +987,7 @@ specifics that have been covered in the rest of the book.
 
 
 
-# Appendix: Switching from GnuPG to Sequoia PGP {.unnumbered}
+# Appendix: Switching from GnuPG to Sequoia-PGP {.unnumbered}
 
 This appendix is aimed at people who already know how to use `gpg`,
 the command line tool from GnuPG that roughly corresponds to `sq`. It
@@ -1119,7 +1120,7 @@ gpg --decrypt hello.txt.gpg
 # Appendix: Glossary {#glossary .unnumbered}
 
 This appendix explains all the specialist terminology related to
-OpenPGP and Sequoia PGP. It includes both the terms Sequoia prefers
+OpenPGP and Sequoia-PGP. It includes both the terms Sequoia prefers
 (e.g., "certificate") and the older terminology for the same thing
 ("public key").
 
@@ -1204,7 +1205,7 @@ verify
 * [Public key cryptography on Wikipedia](https://en.wikipedia.org/wiki/Public-key_cryptography)
 * [RFC 4880](https://datatracker.ietf.org/doc/html/rfc4880), the
   Internet standard specification for OpenPGP
-* [Sequoia PGP website](https://sequoia-pgp.org/)
+* [Sequoia-PGP website](https://sequoia-pgp.org/)
 
 
 # Appendix: Copyright license {.unnumbered}