Docs: talk about SSH-2 before SSH-1.

Because SSH-1 is a very niche interest these days. Mostly this affects
the public key documentation.

Also, a couple of unrelated concessions to modernity.

doc/errors.but

@@ -153,16 +153,16 @@ If you see one of these messages, it often indicates that you've tried
 to load a key of an inappropriate type into PuTTY, Plink, PSCP, PSFTP,
 or Pageant.
 
-You may have specified a key that's inappropriate for the connection
-you're making. The SSH-1 and SSH-2 protocols require different private
-key formats, and a SSH-1 key can't be used for a SSH-2 connection (or
-vice versa).
-
-Alternatively, you may have tried to load an SSH-2 key in a \q{foreign}
+You may have tried to load an SSH-2 key in a \q{foreign}
 format (OpenSSH or \cw{ssh.com}) directly into one of the PuTTY tools,
 in which case you need to import it into PuTTY's native format
 (\c{*.PPK}) using PuTTYgen \dash see \k{puttygen-conversions}.
 
+Alternatively, you may have specified a key that's inappropriate for
+the connection you're making. The SSH-2 and the old SSH-1 protocols
+require different private key formats, and a SSH-1 key can't be used
+for a SSH-2 connection (or vice versa).
+
 \H{errors-refused} \q{Server refused our key},
 \q{Server refused our public key}, \q{Key refused}
 
@@ -212,8 +212,8 @@ you to an SSH server.  This may be because PuTTY has TIS or
 keyboard-interactive authentication disabled, in which case see
 \k{config-ssh-tis} and \k{config-ssh-ki}.
 
-\H{errors-crc} \q{Incorrect \i{CRC} received on packet} or \q{Incorrect
-\i{MAC} received on packet}
+\H{errors-crc} \q{Incorrect \i{MAC} received on packet} or
+\q{Incorrect \i{CRC} received on packet}
 
 This error occurs when PuTTY decrypts an SSH packet and its checksum
 is not correct. This probably means something has gone wrong in the

doc/pageant.but

@@ -65,12 +65,12 @@ something like this:
 
 For each key, the list box will tell you:
 
-\b The type of the key. Currently, this can be \c{ssh1} (an RSA key
-for use with the SSH-1 protocol), \c{ssh-rsa} (an RSA key for use
-with the SSH-2 protocol), \c{ssh-dss} (a DSA key for use with
-the SSH-2 protocol), \c{ecdsa-sha2-*} (an ECDSA key for use with
-the SSH-2 protocol), or \c{ssh-ed25519} (an Ed25519 key for use with
-the SSH-2 protocol).
+\b The type of the key. Currently, this can be
+\c{ssh-rsa} (an RSA key for use with the SSH-2 protocol),
+\c{ssh-dss} (a DSA key for use with the SSH-2 protocol),
+\c{ecdsa-sha2-*} (an ECDSA key for use with the SSH-2 protocol),
+\c{ssh-ed25519} (an Ed25519 key for use with the SSH-2 protocol),
+or \c{ssh1} (an RSA key for use with the old SSH-1 protocol).
 
 \b The size (in bits) of the key.
 
@@ -167,9 +167,10 @@ Use \c{-restrict-putty-acl} to change this. (Again, see
 Agent forwarding is a mechanism that allows applications on your SSH
 server machine to talk to the agent on your client machine.
 
-Note that at present, agent forwarding in SSH-2 is only available
-when your SSH server is \i{OpenSSH}. The \i\cw{ssh.com} server uses a
-different agent protocol, which PuTTY does not yet support.
+Note that at present, whether agent forwarding in SSH-2 is available
+depends on your server. Pageant's protocol is compatible with the
+\i{OpenSSH} server, but the \i\cw{ssh.com} server uses a different
+agent protocol, which PuTTY does not yet support.
 
 To enable agent forwarding, first start Pageant. Then set up a PuTTY
 SSH session in which \q{Allow agent forwarding} is enabled (see

doc/pubkey.but

@@ -66,7 +66,7 @@ public and private keys to be used with PuTTY, PSCP, and Plink, as well
 as the PuTTY authentication agent, Pageant (see \k{pageant}).  PuTTYgen
 generates RSA, DSA, ECDSA, and Ed25519 keys.
 
-When you run PuTTYgen you will see a window where you have two
+When you run PuTTYgen you will see a window where you have two main
 choices: \q{Generate}, to generate a new public/private key pair, or
 \q{Load} to load in an existing private key.
 
@@ -105,12 +105,12 @@ server to accept it.
 \S{puttygen-keytype} Selecting the type of key
 
 Before generating a key pair using PuTTYgen, you need to select
-which type of key you need. PuTTYgen currently supports these types
-of key:
+which type of key you need.
 
-\b An \i{RSA} key for use with the SSH-1 protocol.
+The current version of the SSH protocol, SSH-2, supports several
+different key types. PuTTYgen can generate:
 
-\b An RSA key for use with the SSH-2 protocol.
+\b An \i{RSA} key for use with the SSH-2 protocol.
 
 \b A \i{DSA} key for use with the SSH-2 protocol.
 
@@ -120,12 +120,10 @@ SSH-2 protocol.
 \b An \i{Ed25519} key (another elliptic curve algorithm) for use
 with the SSH-2 protocol.
 
-The SSH-1 protocol only supports RSA keys; if you will be connecting
-using the SSH-1 protocol, you must select the first key type or your
-key will be completely useless.
-
-The SSH-2 protocol supports more than one key type. The types
-supported by PuTTY are RSA, DSA, ECDSA, and Ed25519.
+PuTTYgen can also generate an RSA key suitable for use with the old
+SSH-1 protocol (which only supports RSA); for this, you need to select
+the \q{SSH-1 (RSA)} option. Since the SSH-1 protocol is no longer
+considered secure, it's rare to need this option.
 
 \S{puttygen-strength} Selecting the size (strength) of the key
 
@@ -282,9 +280,9 @@ public keys.
 \S{puttygen-pastekey} \q{Public key for pasting into \i{authorized_keys
 file}}
 
-All SSH-1 servers require your public key to be given to it in a
-one-line format before it will accept authentication with your
-private key. The \i{OpenSSH} server also requires this for SSH-2.
+The \i{OpenSSH} server, among others, requires your public key to be
+given to it in a one-line format before it will accept authentication
+with your private key. (SSH-1 servers also used this method.)
 
 The \q{Public key for pasting into authorized_keys file} gives the
 public-key data in the correct one-line format. Typically you will
@@ -315,12 +313,7 @@ for information about importing foreign key formats.
 
 \S{puttygen-conversions} Dealing with private keys in other formats
 
-Most SSH-1 clients use a standard format for storing private keys on
-disk. PuTTY uses this format as well; so if you have generated an
-SSH-1 private key using OpenSSH or \cw{ssh.com}'s client, you can use
-it with PuTTY, and vice versa.
-
-However, SSH-2 private keys have no standard format. \I{OpenSSH private
+SSH-2 private keys have no standard format. \I{OpenSSH private
 key format}OpenSSH and \I{ssh.com private key format}\cw{ssh.com} have
 different formats, and PuTTY's is different again.
 So a key generated with one client cannot immediately be used with
@@ -332,8 +325,8 @@ menu, PuTTYgen can load SSH-2 private keys in OpenSSH's format and
 can then save it back out as a PuTTY-format key (\c{*.\i{PPK}}) so that
 you can use it with the PuTTY suite. The passphrase will be unchanged by this
 process (unless you deliberately change it). You may want to change
-the key comment before you save the key, since OpenSSH's SSH-2 key
-format contains no space for a comment and \cw{ssh.com}'s default
+the key comment before you save the key, since some OpenSSH key
+formats contained no space for a comment, and \cw{ssh.com}'s default
 comment format is long and verbose.
 
 PuTTYgen can also \i{export private keys} in OpenSSH format and in
@@ -353,8 +346,12 @@ reason for wanting to use OpenSSH's newer format even for RSA, DSA,
 or ECDSA keys, you can choose \q{Export OpenSSH key (force new file
 format)}.
 
-Note that since only SSH-2 keys come in different formats, the export
-options are not available if you have generated an SSH-1 key.
+Most clients for the older SSH-1 protocol use a standard format for
+storing private keys on disk. PuTTY uses this format as well; so if
+you have generated an SSH-1 private key using OpenSSH or
+\cw{ssh.com}'s client, you can use it with PuTTY, and vice versa.
+Hence, the export options are not available if you have generated an
+SSH-1 key.
 
 \H{pubkey-gettingready} Getting ready for public key authentication
 
@@ -363,21 +360,21 @@ connection succeeds you will be prompted for your user name and
 password to login. Once logged in, you must configure the server to
 accept your public key for authentication:
 
-\b If your server is using the SSH-1 protocol, you should change
-into the \i\c{.ssh} directory and open the file \i\c{authorized_keys}
-with your favourite editor. (You may have to create this file if
-this is the first key you have put in it). Then switch to the
-PuTTYgen window, select all of the text in the \q{Public key for
-pasting into authorized_keys file} box (see \k{puttygen-pastekey}),
-and copy it to the clipboard (\c{Ctrl+C}). Then, switch back to the
-PuTTY window and insert the data into the open file, making sure it
-ends up all on one line. Save the file.
+\b If your server is \i{OpenSSH}, you should change into the
+\i\c{.ssh} directory under your home directory, and open the file
+\i\c{authorized_keys} with your favourite editor. (You may have to
+create this file, if this is the first key you have put in it.) Then
+switch to the PuTTYgen window, select all of the text in the \q{Public
+key for pasting into authorized_keys file} box (see
+\k{puttygen-pastekey}), and copy it to the clipboard (\c{Ctrl+C}).
+Then, switch back to the PuTTY window and insert the data into the
+open file, making sure it ends up all on one line. Save the file.
 
-\b If your server is \i{OpenSSH} and is using the SSH-2 protocol, you
-should follow the same instructions, except that in earlier versions
-of OpenSSH 2 the file might be called \c{authorized_keys2}. (In
-modern versions the same \c{authorized_keys} file is used for both
-SSH-1 and SSH-2 keys.)
+\lcont{
+(In very old versions of OpenSSH, SSH-2 keys had to be put in a
+separate file called \c{authorized_keys2}. In all current versions,
+the same \c{authorized_keys} file is used for both SSH-1 and SSH-2 keys.)
+}
 
 \b If your server is \i\cw{ssh.com}'s product and is using SSH-2, you
 need to save a \e{public} key file from PuTTYgen (see
@@ -393,8 +390,9 @@ that server.
 You may also need to ensure that your home directory, your \c{.ssh}
 directory, and any other files involved (such as
 \c{authorized_keys}, \c{authorized_keys2} or \c{authorization}) are
-not group-writable or world-writable. You can typically do this by
-using a command such as
+not group-writable or world-writable; servers will typically ignore
+the keys unless this is done. You can typically do this by using a
+command such as
 
 \c chmod go-w $HOME $HOME/.ssh $HOME/.ssh/authorized_keys