[krbdev.mit.edu #7126] Documentation__Building Kerberos V5

[Tom Yu via RT]

"Jeff Blaine via RT" <rt-comment at krbdev.mit.edu> writes:

> 1. This paragraph is kind of messed up:
>
>  > 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).
>
> 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.

The original source (Texinfo) for this text was paramterized.  We
could put the parameterization back in, which I think is possibly less
confusing.

> 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

On the other hand, can we assume at this point that people who are
considering building krb5 from source code know how to extract gzipped
tar files?

> 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.

That seems reasonable.