[OpenAFS] Documentation project comments

[ted creedon]

Here's what you won't have in the POD's:

1. Verbatim text - particularly multiline (very useful). The verbatim text
has multiple fonts and boldface to emphasize the point being made in the
text.
2. Hyperlinks
3. Color
4. Indexing and tables of contents
5. Any other feature Latex supports that POD doesn't (quite a few).
6. We will be dealing with POD, xdvi, pdf, html outputs. Long term we need
to figure out how to generate acceptable output from one set of latex files.

You can extract the appropriate text from the IBM.htm files by looking at
the included html2latex.pl and Latex.pm files and modifying accordingly.
Latex.pm builds a parse tree of the IBM.htm and emits from there. (Note: the
.xml setup file has been omitted, using __DATA__ at the end of the file
instead. In particular <ban foo /ban> turns off parsing of undesired <foo
xxxx /foo> fields.

One might also read the POD documentation - I removed it from the sources to
speed up editing - its in the perl release.

Suggest building a test case with the ReleaseNotes-3.6 directory as it the
smallest and has one of everything. If it looks good go with it.

E-mail directly with questions.

tedc

		

-----Original Message-----
From: openafs-info-admin@openafs.org [mailto:openafs-info-admin@openafs.org]
On Behalf Of Russ Allbery
Sent: Friday, June 10, 2005 3:25 PM
To: openafs-info@openafs.org
Subject: Re: [OpenAFS] Documentation project comments

Esther Filderman <mizmoose@gmail.com> writes:
> On 6/10/05, chas williams - CONTRACTOR <chas@cmf.nrl.navy.mil> wrote:

>> is there any hope of someone doing something with the man pages?
>> yes, i am a dinosaur, i still like man pages.

> I think Russ Allbery was working on man pages a while ago. Oh, Russ, 
> whatever happened?

Thanks for the kick; I got off doing other things for a while, but keep
thinking I should get back to this, particularly now that I'm helping with
the OpenAFS packages for Debian.

I'll mail Alf and ask if there's anything newer than the last time I looked,
and start plugging away at this.

So that people know, if I write the man pages I'll write them all in POD,
based initially on the web page reference manual, and then use pod2man to
convert them to man pages.  One of the many pod2html converters can then
also be used to convert them to web pages.  If anyone objects strongly to
that approach, speak up now.

I think I can pretty easily do a few and get them submitted so that we can
get started, and then the work becomes very parallelizable.

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