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

[Coy Hile]

I for one find for some things like the sorts of docs that are the admin gu=
ide/admin ref/etc, that having printable copies works well.   Maybe I'm jus=
t a curmudgeon, though. (No need for comments from the peanut gallery on th=
at one :))

________________________________________
From: openafs-info-admin@openafs.org [openafs-info-admin@openafs.org] on be=
half of Russ Allbery [rra@stanford.edu]
Sent: Monday, April 19, 2010 3:08 PM
To: openafs-info@openafs.org
Subject: Re: [OpenAFS] Re: [OpenAFS-Doc] Forwarded documentation rant

"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/>
_______________________________________________
OpenAFS-info mailing list
OpenAFS-info@openafs.org
https://lists.openafs.org/mailman/listinfo/openafs-info=