GNOME.org
 

[seahorse/wip/userdocs: 2/4] Help: Review Aruna's mallard-help docs

commit d4db1724c174d4b409ce6a29958a8ce127cd0c4b
Author: Hashem Nasarat <hashem riseup net>
Date:   Sun Mar 16 01:31:25 2014 -0400

    Help: Review Aruna's mallard-help docs
    
    I checked over Aruna's writing for technical and grammatical
    correctness. The following files were reviewed:
    
    git log --pretty="%H" --author="Aruna" | while read commit_hash; \
    do git show --oneline --name-only $commit_hash | tail -n+2; \
    done | sort | uniq

 help/C/introduction.page          |    2 +-
 help/C/key-servers-add.page       |   12 +++++++++-
 help/C/keyring-unlock.page        |    2 +-
 help/C/misc-key-backup.page       |   22 +++++++++++++------
 help/C/misc-key-fingerprint.page  |    3 +-
 help/C/passwords-view.page        |   22 ++++++++++++++++++-
 help/C/pgp-create.page            |   20 +++++++++++++----
 help/C/pgp-delete.page            |   41 ++++++++++++++++++++++++------------
 help/C/pgp-expiration-change.page |    2 +-
 help/C/pgp-publish.page           |    4 +-
 help/C/pgp-retrieve-remote.page   |    4 +-
 help/C/pgp-sign.page              |    3 +-
 help/C/pgp-sync.page              |    2 +-
 help/C/subkeys-revoke.page        |    4 +-
 14 files changed, 101 insertions(+), 42 deletions(-)
---
diff --git a/help/C/introduction.page b/help/C/introduction.page
index 71f787d..8db33fb 100644
--- a/help/C/introduction.page
+++ b/help/C/introduction.page
@@ -39,7 +39,7 @@
     <item>
       <p>Copy and <link xref="passwords-stored-create">save</link> passwords
       that are difficult to remember. To group related passwords,
-      <link xref="keyring-create">create keyrings</link></p>
+      <link xref="keyring-create">create keyrings</link>.</p>
     </item>
     <item>
       <p><link xref="pgp-create">Create</link> and
diff --git a/help/C/key-servers-add.page b/help/C/key-servers-add.page
index 0fc920a..74aca15 100644
--- a/help/C/key-servers-add.page
+++ b/help/C/key-servers-add.page
@@ -10,10 +10,15 @@
     <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>
 
     <credit type="author copyright">
-      <name>Arunai Sankaranarayanan</name>
+      <name>Aruna Sankaranarayanan</name>
       <email its:translate="no">aruna evam gmail com</email>
       <years>2013</years>
     </credit>
+    <credit type="editor copyright">
+      <name>Hashem Nasarat</name>
+      <email its:translate="no">hashem riseup net</email>
+      <years>2014</years>
+    </credit>
 
     <desc>Make additions to the list of keyservers in
     <app>Passwords and Keys</app></desc>
@@ -48,7 +53,10 @@
     </item>
     <item>
       <p>In the <gui style="input">Host</gui> field, paste the Internet URL of
-      your key server.</p><!--Not sure about port numbers?- Aruna-->
+      your key server. Consult the documentation for the key server you're
+      adding to see if it operates on a non-standard port. If so, enter the
+      port after the ':'. If you're unsure, leave the text box after the ':'
+      blank.</p>
     </item>
     <item>
       <p>Press <gui style="button">OK</gui> to finish.</p>
diff --git a/help/C/keyring-unlock.page b/help/C/keyring-unlock.page
index 52c4135..fca2912 100644
--- a/help/C/keyring-unlock.page
+++ b/help/C/keyring-unlock.page
@@ -23,7 +23,7 @@
   <title>Unlock your keyrings</title>
     <p>A keyring may often be
     <link xref="keyring-lock">locked</link> to protect the passwords
-    it contains, sort of like locking important things safely inside a trunk.
+    it contains, similar to locking important things safely inside a trunk.
     In order to look at your passwords, you must unlock the keyring first.</p>
 
   <steps>
diff --git a/help/C/misc-key-backup.page b/help/C/misc-key-backup.page
index f949f03..1338029 100644
--- a/help/C/misc-key-backup.page
+++ b/help/C/misc-key-backup.page
@@ -18,25 +18,33 @@
       <years>2013</years>
     </credit>
 
+    <credit type="editor copyright">
+      <name>Hashem Nasarat</name>
+      <email its:translate="no">hashem riseup net</email>
+      <years>2014</years>
+    </credit>
+
     <desc>Keep a copy of your keys in an external device.</desc>
   </info>
 
   <title>Securely back-up your keys</title>
 
   <p>It is always advisable to save a copy of your keys on an external memory
-  device like a USB. The device should then be kept locked or stored somewhere
-  safe. This way you will always have a copy of the key if your hard disk
-  crashes or if the data on your computer is corrupted in some way.</p>
+  device like a USB drive. The device should then be kept locked or stored
+  somewhere safe. This way you will always have a copy of the key if your
+  computer breaks or if the data on your computer is corrupted in some way.</p>
 
   <steps>
     <title>To back-up your keys:</title>
     <item>
-      <p>Export your <link xref="pgp-export">PGP</link> and
-      <link xref="ssh-export">SSH</link> keys.</p>
+      <p>Export your key files:</p>
+      <steps>
+        <item><p><link xref="pgp-export">Export your PGP keys</link>.</p></item>
+        <item><p><link xref="ssh-export">Export your SSH keys</link>.</p></item>
+      </steps>
     </item>
     <item>
-      <p>Save the exported key file on an external disk.</p>
+      <p>Copy the exported files on an external disk.</p>
     </item>
   </steps>
-
 </page>
diff --git a/help/C/misc-key-fingerprint.page b/help/C/misc-key-fingerprint.page
index 0847c6c..1206636 100644
--- a/help/C/misc-key-fingerprint.page
+++ b/help/C/misc-key-fingerprint.page
@@ -38,7 +38,8 @@
   <p>It is the fingerprint of a key that is verified when you try to login to a
   remote computer using <link xref="ssh">SSH</link>. While signing a
   <link xref="pgp">PGP</link> key, you must always check the key
-  fingerprint to ensure that you are signing the correct key.</p>
+  fingerprint and verify the key owner's identity to ensure that you are
+  signing the correct key.</p>
 
 <section id="fingerprint-ui">
   <title>Fingerprints on <app>Passwords and Keys</app></title>
diff --git a/help/C/passwords-view.page b/help/C/passwords-view.page
index eef0a34..63b7e9a 100644
--- a/help/C/passwords-view.page
+++ b/help/C/passwords-view.page
@@ -17,6 +17,12 @@
       <years>2013</years>
     </credit>
 
+    <credit type="editor copyright">
+      <name>Hashem Nasarat</name>
+      <email its:translate="no">hashem riseup net</email>
+      <years>2014</years>
+    </credit>
+
     <desc>Use <app>Passwords and Keys</app> to check a stored password you have
     forgotten.</desc>
   </info>
@@ -32,11 +38,11 @@
     <title>To view your passwords:</title>
 <!-- HEAD has a new patch submitted to
      https://bugzilla.gnome.org/show_bug.cgi?id=705592, which makes View->By
-     keyring the default view. -Aruna - 19/08/2013
+     keyring the default view. -Aruna - 19/08/2013-->
      <item>
       <p>Select <guiseq><gui style="menu">View</gui>
       <gui style="menuitem">By keyring</gui></guiseq>.</p>
-    </item>-->
+    </item>
     <item>
       <p><link xref="keyring-unlock">Unlock</link> the password
       keyring that contains your password. A list of passwords stored in the
@@ -52,5 +58,17 @@
       password.</p>
     </item>
   </steps>
+  <note style="important">
+    <p>Since the contents of any unlocked keyrings are available to programs
+    you may be running, and Passwords and Keys does not seek to give a false
+    sense of security, the contents of unlocked keyrings are able to be viewed
+    without entering the password.</p>
+    <p>This means that, if you are logged-in, the contents of the Login
+    keyring will available without entering a password from Passwords and Keys.
+    </p>
+    <p>If you need to lend your computer to another person, it is recommended
+    to create a user account for them, or allow them to use the Guest
+    account.</p>
+  </note>
 
 </page>
diff --git a/help/C/pgp-create.page b/help/C/pgp-create.page
index 76b920c..9f9d852 100644
--- a/help/C/pgp-create.page
+++ b/help/C/pgp-create.page
@@ -23,6 +23,12 @@
       <years>2013</years>
     </credit>
 
+    <credit type="editor copyright">
+      <name>Hashem Nasarat</name>
+      <email its:translate="no">hashem riseup net</email>
+      <years>2014</years>
+    </credit>
+
     <desc>Create and use GnuPG keys for encrypting and signing emails.</desc>
   </info>
 
@@ -58,9 +64,10 @@
   </steps>
 
   <p><app>Passwords and Keys</app> will take some time to generate your key.
-  While your key is being created, move your mouse around and press some keys
-  on your keyboard. This will help <app>Passwords and Keys</app> to create a
-  truly random key. The key will be listed under <gui>GnuPG keys</gui>.</p>
+  While your key is being created, move your mouse around, press some keys
+  on your keyboard, or browse the web. This will help <app>Passwords and
+  Keys</app> to create a truly random key. The key will be listed under
+  <gui>GnuPG keys</gui>.</p>
 
   <note style="tip">
     <p>The <gui>Full Name</gui>, <gui>Email Address</gui> and
@@ -92,10 +99,13 @@
     </item>
     <item>
     <title>Expiration Date</title>
-      <p>When a key <link xref="pgp-expired">expires</link>, you can no longer
-      use it to sign or encrypt. In <app>Passwords and Keys</app>, you can
+      <p>When a key expires, <link xref="pgp-expired">certain actions no longer
+      work</link>. In <app>Passwords and Keys</app>, you can
       either set your key to <gui style="checkbox">Never Expire</gui>, or
       select an expiration date and time for it.</p>
+      <p>It is recommended that you set an expiration date in case you lose
+      access to the key. Even if your key expires, you can
+      <link xref="pgp-expiration-change"> change the expiration to a later date</link>.</p>
     </item>
   </terms>
 
diff --git a/help/C/pgp-delete.page b/help/C/pgp-delete.page
index 5eef790..109c139 100644
--- a/help/C/pgp-delete.page
+++ b/help/C/pgp-delete.page
@@ -17,6 +17,12 @@
       <years>2013</years>
     </credit>
 
+    <credit type="editor copyright">
+      <name>Hashem Nasarat</name>
+      <email its:translate="no">hashem riseup net</email>
+      <years>2014</years>
+    </credit>
+
     <desc>Delete local copies of your keys or the keys of people you
     communicate with.</desc>
   </info>
@@ -32,12 +38,32 @@
   <steps>
     <title>To delete a key:</title>
     <item>
-      <p>Select the key.</p>
+      <p>Select the key. (You may need to show all keys, with
+        <guiseq>
+          <gui style="menu">View</gui><gui style="menuitem">Show any</gui>
+        </guiseq>)
+      </p>
     </item>
     <item>
       <p>Right click, and choose <gui>Delete</gui>. Alternatively you can also
       select <guiseq><gui style="menu">Edit</gui>
       <gui style="menuitem">Delete</gui></guiseq> to delete the key.</p>
+      <note style="important">
+        <p>When you delete a GnuPG key that has been published on a key server, you
+        only delete the key in your GnuPG keyring because a copy of the
+        public key will still be present on some key server.</p>
+        <p>If you delete your GnuPG key, this means that your private key will
+        be permanently deleted, even though your public key can still be
+        <link xref="pgp-retrieve-remote">retrieved</link>
+        from a key server and used to encrypt messages to you that you won't be
+        able to read! To prevent such a key from being used, retrieve and revoke
+        the key. <!--TODO add link on how to revoke from GUI-->
+        The revoked key can then be
+        <link xref="pgp-sync">synced</link> with a key server to prevent people
+        from retrieving and using it.</p>
+        <!-- or when you <link xref="misc-key-revoke">revoke</link> it.- No
+        revoking feature yet for SSH keys/PGP master keys-->
+      </note>
     </item>
     <item>
       <p>In the new dialog, confirm the deletion by ticking the
@@ -47,18 +73,5 @@
     </item>
   </steps>
 
-  <note style="important">
-    <p>When you delete a GnuPG key that has been published on a key server, you
-    only delete the secret key in the GnuPG keypair because a copy of the
-    public key will still be present on some key server. This means that your
-    public key can still be <link xref="pgp-retrieve-remote">retrieved</link>
-    from a key server and used to encrypt messages to you, even though the
-    secret key has been deleted. To prevent such a key from being used,
-    retrieve and revoke it. The revoked key can then be
-    <link xref="pgp-sync">synced</link> with a key server to prevent people
-    from retrieving and using it.</p>
-    <!-- or when you <link xref="misc-key-revoke">revoke</link> it.- No
-    revoking feature yet for SSH keys/PGP master keys-->
-  </note>
 
 </page>
diff --git a/help/C/pgp-expiration-change.page b/help/C/pgp-expiration-change.page
index 4b804c7..9bef0a9 100644
--- a/help/C/pgp-expiration-change.page
+++ b/help/C/pgp-expiration-change.page
@@ -55,7 +55,7 @@
     </item>
   </steps>
 
-  <note style="tip">
+  <note style="important">
     <p>If you are changing the expiration date of a key that has been
     published, you must <link xref="pgp-sync">synchronize</link> the key with
     the key server after making the desired changes.</p>
diff --git a/help/C/pgp-publish.page b/help/C/pgp-publish.page
index aba2ede..ff9ed2f 100644
--- a/help/C/pgp-publish.page
+++ b/help/C/pgp-publish.page
@@ -24,8 +24,8 @@
   <title>Share your public keys</title>
 
   <p>If you want people to send you encrypted communication, you must share
-  your <gui>GnuPG keys</gui> with them. To share your key with a selected few
-  people, <link xref="pgp-export">export</link> it and mail
+  your <gui>GnuPG key</gui> with them. To share your key with a selected few
+  people, <link xref="pgp-export">export it</link> and mail
   the resulting keyfile to them. To allow anyone to
   <link xref="pgp-retrieve-remote">retrieve</link> and use your public key,
   publish it on a key server.</p>
diff --git a/help/C/pgp-retrieve-remote.page b/help/C/pgp-retrieve-remote.page
index 51c458d..71882f4 100644
--- a/help/C/pgp-retrieve-remote.page
+++ b/help/C/pgp-retrieve-remote.page
@@ -24,8 +24,8 @@
 
   <title>Retrieve remote keys</title>
 
-  <p>You can retrieve someone's public GnuPG key using the Internet and store
-  it on <app>Passwords and Keys</app>.</p>
+  <p>You can retrieve someone's public GnuPG key from the Internet and store
+  it in <app>Passwords and Keys</app>.</p>
 
   <steps>
     <title>To retrieve a remote key:</title>
diff --git a/help/C/pgp-sign.page b/help/C/pgp-sign.page
index b8d1875..6eb7abc 100644
--- a/help/C/pgp-sign.page
+++ b/help/C/pgp-sign.page
@@ -24,7 +24,8 @@
   <p>To show that you trust and vouch for the genuineness of someone's key, you
   can sign it. A person's key must be signed only after you compare the
   <link xref="pgp-userid">user ID</link> on the key with a valid proof of their
-  identity. If the two IDs match, the key is said to be trustworthy.</p>
+  identity, such as a passport, driver's license, or similar. If the two IDs
+  match, the key is said to be trustworthy.</p>
 
   <steps>
     <title>To sign a key:</title>
diff --git a/help/C/pgp-sync.page b/help/C/pgp-sync.page
index 70b9005..ec3091e 100644
--- a/help/C/pgp-sync.page
+++ b/help/C/pgp-sync.page
@@ -27,7 +27,7 @@
   ensure that any changes made to the key on the key server, like a new
   signature, are updated in your local copy of the key. Similarly, when you
   change information on your local key copy, like the expiration date, or when
-  you sign someone's key, you could synchronize the keys to update the changes
+  you sign someone's key, you should synchronize the keys to update the changes
   on the remote copy of the key. You need a working Internet connection to
   synchronize your keys.</p>
 
diff --git a/help/C/subkeys-revoke.page b/help/C/subkeys-revoke.page
index 5214ede..34e53fb 100644
--- a/help/C/subkeys-revoke.page
+++ b/help/C/subkeys-revoke.page
@@ -23,8 +23,8 @@
 
   <title>Revoke your subkeys</title>
 
-  <p>If your subkey has been compromised or has remained unused for several
-  days, it might be a good idea to revoke it to prevent misuse of the key.</p>
+  <p>If your subkey has been compromised or is no longer in use, it might be a
+  good idea to revoke it to prevent misuse of the key.</p>
 
   <steps>
     <title>To revoke a subkey:</title>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]