[Gpg4win-devel] Minor Edits to Manual

[Bernhard Reiter]

Hi Brigitte,

now that you have typed in all the corrections in the email I will use it.
(Technically I can merge this in more easily when you just take the latest
novices.tex from SVN and use a text-editor to make the change yourself.)

On Tuesday 13 March 2007 14:13, Brigitte H wrote:
> p.6 "'Gpg4win for Novices"' is a quick guide to installing and everyday
> use...."  - grammatically incorrect, should read "...is a quick guide to
> the installation and everyday use ...."

I have to trust you on this one, as a non-native writer. ;)
Committed.

> p.6  "half an hour to work through this manual" (not: half and hour)

Good spotting.
Fixed.

> p.10 "roll OR move the mouse"  NOT 'hover the mouse' (hover refers to
> flying objects, like birds or helicopters)

I thought the analogy was fine that is why I did the change.
"move" is better, changed.

> p.14 "During the installation, a progress bar will be displayed, as well
> as showing the file currently be-
> ing installed."  This sentence is grammatically incorrect, because when
> you use 'as well as' as part of a list, the verbs need to be in the same
> tense.
>
> better:  "During the installation process a progress bar displays the files
> being
> installed."

Rereading the German original I have now used:

During the installation a progress bar displays the file being installed.
You can click on \Button{Show details} to see a log of the installation.

> p. 17 "You have now installed Gpg4win and can use the program"  should
> read: "You have now installed Gpg4win and are ready to use the program".
> Not a major issue, I just think this reads easier because the first
> sentence feels like it is missing the 'you' before the 'can use'.

Fixed.

> "Of course you do not need to know the insides of Gpg4win to be able to
> use it. However, you will use Gpg4win to handle your most sensitive
> correspondence and it seems a good
> idea to understand the theory behind it."
>
> I would not use the word 'insides' - it is commonly used in association
> with internal organs only.  Please replace with "all the intricacies" OR
> "all the technical details"

The association with internal organs seem fitting somehow. :)
(I took "all the technical details" now.)

> "Of course you do not need to know all the intricacies (OR technical
> details) of Gpg4win to be able to
> use it. However, SINCE Gpg4win will be used to handle your most sensitive
> correspondence, it IS PROBABLY a good
> idea to understand the theory behind it."

Changed.

> p.18
> now reads: "After reading the information explaining the security features
> of Gpg4win, as well as creating good
> passphrase to protect your private key, this section shows you how to
> create a key pair."    Grammatically incorrect, should read: After reading
> the information explaining Gpg4win's security features and the creation of
> a good passphrase to protect your private key,....."

Yes and "a" was missing at least... fixed.

> p.18
> "The processes of creating a key, encryption and decryption are very
> important; it is a good idea
> to practice these steps until you are very comfortable with the procedures.
> . . ."
>
> Nothing wrong with this sentence, except the dots after the sentence, which
> should be removed?

The English translation has a slightly different meaning than the German
original. Here is my attempt to be closer to the original, which tries
to be a bit more informal here:

\textbf{
The processes of creating a key, encryption and decryption are very
important - so important that it should be possible to practice $\ldots$
}

\textbf{And this is what you actually can do:}
Run through the whole processes as often as you want.
Those "dry-runs" help you gain confidence in
using the program, so that some of the more intricate steps in creating
keys will not pose any problems later on. 

(I did commit this, but feel free to make suggestions.)

> p.21
> "Again, if this is a test run, you can use an imaginary emailaddress
> such...."   nothing wrong, except there needs to be a space between email
> and address; same with the sentence  "Or you can enter your real
> emailaddress...."   below the screen shot on the same page.

Fixed.

> p.22
> now reads: "So, at this point you should have thought your
> own passphrase - one that is private, easy to remember, and...."
>
> This sentence is grammatically incorrect, it should read either "At this
> point you should have thought OF your own passphrase ....."  or :  "At this
> point you should have come up with your own passphrase....."

Took the latter.

> p.22
> now reads: "If the passphrase you entered is not very secure, the program
> will warn you about it, allowing you to
> enter a more secure passphrase."   Awkward structure.  Should read "....is
> not very secure, a warning will be displayed, allowing ....."

Changed.

> p.25
> now reads: "Depending on the number of communication partners, can do this
> in two ways:...  better: "Depending on the number of CORRESPONDENCE
> partners, YOU can ...."    The word 'communication partners' is not
> technically wrong, but not widely used.

Committed.

>
> p.25
> now reads: "emailaddress available", same problem as above, needs space
> between email and address.

Fixed.

> p.26
> now reads: "good emailrobot for practicing...."  - not sure about this one
> - i checked on the Net, and saw the word emailrobot used in connection with
> specific program names (ex. Emailrobot 2000);  the expression 'email robot'
> was used in a more general nature, ie. not in reference to a specific
> program.  You may want to check into this as there may be trademark issues
> in using Emailrobot as one word?

I don't know, but I have added a space now.
Thanks for looking this up.

> p.29
> now reads: "Before doing this, your should configure your email program to
> send messages in text-only format rather than HTML."  Typing error - should
> read "Before doing this, YOU should configure...."

Fixed.

> p.30
> now reads: "Ä The "'Copy & Paste"'-method shown in this....", delete the
> '-' before 'method, i.e. "The "Copy & Paste" method ...."

Fixed.

> p.31
> now reads: "Now anyone can
> download your key, and use it to send you secure email."  Is missing 'a'
> before 'secure email'. ("....and use it to send you A secure email.")

Fixed.

> p.31
> now reads: "If this is a practice run, do NOT send your practice key to the
> key server because, once send, it cannot
> be removed."  Grammar error, wrong tense, should read: "....send your
> practice key to the key server because once it is sent (or: once sent), it
> cannot be removed."

Fixed.

> p.33
> now reads: "(Please note that the encryption sequence has been considerably
> shortened to save space in this manual.)"  Awkward wording, does not sound
> very professional.  Better : "Please note that the encryption sequence has
> been shortened considerably for demonstration purposes".
>
>
> p.34
> now reads: "WinPT (Windows Privacy Tray key management tool) serves as
> PnuPG's "'front end"'. This program
> is used to encrypt and decrypt emails; it also creates and verifies digital
> signatures. One...."
>
> small error - delete the ' in front of the word 'front'
>
> same problem with this sentence: "manual "'Gpg4win for Advanced Users"'
> provides...", has the ' in the wrong place
>
> I noticed this in other spots too - might want to do a search on these.

This is technical problem with the layout markup from the system called LaTeX
that is used to typeset the manual currently.
   "` will be typeset to a lower double quotation mark which is common
in German if the option "german" is given to LaTex.
Similiar "' will be an upper double quotation mark. 
If LaTeX is used without that option "german", a single character " should
be used in the source code file.

So I have searched and replaced them all.

> p.39
> now reads: "It does not matter whether you save the key as text or directly
> as an emailattachment, as both methods
> import the key into your GnuPG-"'Key Ring"'.
>
> Error: Put space between 'email' and 'attachment'.
>
> p.41
> now reads: "....verification process is fairly simple. To do it, you ...."
>
> grammatical error; should read: "...simple.  To do this, you...."   or :
> "simple. For this, you...."

Changed.

> p.43
> now reads: "Open your emailprogram and write...."
>
> I think there should be a space between email and program, as this is the
> more commonly used way of writing.  I also came across some programs called
> 'emailprogram' on the Web, so there may also be a trademark concern.
> However, I just want to point this out, I am not entirely sure which one is
> better suited - maybe someone can comment on this one.

I do not think there will be trademark issues with general things like 
'emailprogram' - at least it is not likely.
However to be consistent I have added a space.
Note that in Germany, lots of things will be written together without space
and the lack of space here results out of that there is a special markup 
command which might have thrown Werner or myself off mark here. ;)


> p.43
> now reads: "Open your emailprogram and write a message (if you are sending
> the message to Adele, any text will
> do). . ."
>
> Delete . . . after the sentence, it is not necessary.

Ah, I know understand why you did not translate the original sence with the 
continuation of though, because the markup does not actual show the dots,
they hide behind the command '$\ldots$'. :)
I have now used:

Open your \Email{} program and write a message (if you are sending the
message to Adele, any text will do as Adele can not actually read $\ldots$)

Would that be fine with you? 

> p.44
> now reads: "You should now see a window containing the keys on your key
> ring. Using the examples featured in
> this guide, you would see Adele's key (the one she sent to you), as well as
> your own key, which you
> created in Chapter 2."
>
> This manual does not contain a Chapter 2 (unless we are talking about the
> Advanced user manual?) - it would be better to refer to the actual page
> number, in this case 19.  Unless I missed something.
>
> Therefore: "you should now see a window.....created using the method
> outlined on page 19 of this manual."

Good point, I think we should add a dynamic reference to the section
or page where the creation of the key was described.
Still TODO I have added a FIXME in there for now.

Thanks a lot for the precise suggestions,

Bernhard

-- 
Managing Director - Owner: www.intevation.net       (Free Software Company)
Germany Coordinator: fsfeurope.org. Coordinator: www.Kolab-Konsortium.com.
Intevation GmbH, Osnabrück, DE; Amtsgericht Osnabrück, HRB 18998
Geschäftsführer Frank Koormann, Bernhard Reiter, Dr. Jan-Oliver Wagner
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.wald.intevation.org/pipermail/gpg4win-devel/attachments/20070406/8f8b40f4/attachment.pgp