| Date: | Mon, 07 May 2012 16:32:40 -0400 |
| From: | Jeff Blaine <jblaine@kickflop.net> |
| To: | krb5-bugs@mit.edu |
| Subject: | Documentation__Building Kerberos V5 |
1. This paragraph is kind of messed up:
Aside from the structure of it, I think it is always best not to
mention any specific version numbers in documentation unless it
directly applies to a version-specific piece of information.
Perhaps just say something like,
"For these instructions, we will refer to the Kerberos
source code packages and the extracted tree of files via the
form 'krb5-MAJOR.MINOR', where MAJOR is a placeholder for the
major version of Kerberos and MINOR is a placeholder for the
minor version of Kerberos.
For example, MIT Kerberos 1.9 has major version '1' and minor
version '9', so if you see an instruction:
Extract krb5-MAJOR.MINOR.tar.gz
it means (if you are using 1.9):
Extract krb5-1.9.tar.gz
2. IMO, there are a lot of references to the word 'tarfiles',
which is kind of slang really.
"Note that the tarfiles will by default all unpack into the..."
"...so that if your current directory is /u1 when you unpack the
tarfiles..."
I'd recommend just using "tar files" or "tar file" as necessary.
Just like "PDF file" refers to a PDF file and "pdffile" is weird.
[ Just trying to help! ]
Show quoted text
> The first step in each of these build procedures is to
> unpack the source distribution. The Kerberos V5 distribution
> comes in a tar file, generally named krb5-1.9.tar (for
> version 1.9. We will assume that version is 1.9. Please,
> adjust this number accordingly), which contains a compressed
> tar file consisting of the sources for all of Kerberos (generally
> krb5-1.9.tar.gz) and a PGP signature for this source tree
> (generally krb5-1.9.tar.gz.asc).
> unpack the source distribution. The Kerberos V5 distribution
> comes in a tar file, generally named krb5-1.9.tar (for
> version 1.9. We will assume that version is 1.9. Please,
> adjust this number accordingly), which contains a compressed
> tar file consisting of the sources for all of Kerberos (generally
> krb5-1.9.tar.gz) and a PGP signature for this source tree
> (generally krb5-1.9.tar.gz.asc).
Aside from the structure of it, I think it is always best not to
mention any specific version numbers in documentation unless it
directly applies to a version-specific piece of information.
Perhaps just say something like,
"For these instructions, we will refer to the Kerberos
source code packages and the extracted tree of files via the
form 'krb5-MAJOR.MINOR', where MAJOR is a placeholder for the
major version of Kerberos and MINOR is a placeholder for the
minor version of Kerberos.
For example, MIT Kerberos 1.9 has major version '1' and minor
version '9', so if you see an instruction:
Extract krb5-MAJOR.MINOR.tar.gz
it means (if you are using 1.9):
Extract krb5-1.9.tar.gz
2. IMO, there are a lot of references to the word 'tarfiles',
which is kind of slang really.
"Note that the tarfiles will by default all unpack into the..."
"...so that if your current directory is /u1 when you unpack the
tarfiles..."
I'd recommend just using "tar files" or "tar file" as necessary.
Just like "PDF file" refers to a PDF file and "pdffile" is weird.
[ Just trying to help! ]