[OpenAFS] Re: [OpenAFS-Doc] Forwarded documentation rant

[Russ Allbery]

"Chas Williams (CONTRACTOR)" <chas@cmf.nrl.navy.mil> writes:

> it is still there.  btw, you cant reference by page numbers.  this is
> a very strange idea.   different media is going to have different page
> numbers.  references inside the admin reference manual were lost though.
> however, that documents has changed enough that it probably wasnt very
> correct.

POD is capable of including enough information that you could get them
back, and most of the high-level references are still there.  The
low-level references (to specific sections of particular pieces of
documentation) would need additional annotations.

Some work on the generation scripts to get more of the references to
hyperlink properly would be good, as would some investigation of currently
available POD formatters to see which ones would give the best
cross-referenced printable output.

On the other hand, I'm not sure how large the audience is for that work
any more.  Printing things like this out has I think become a lot less
common over the years.  That's one of the reasons why our original focus
was on turning the reference guide into man pages; on our UNIX-like
platforms, that's a far more common documentation access method than
printed or printable manuals.

-- 
Russ Allbery (rra@stanford.edu)             <http://www.eyrie.org/~eagle/>