Discussion:
[OpenAFS-Doc] Final (from Latex) pdf's and html's available
ted creedon
2005-06-27 19:39:21 UTC
Permalink
The final versions of the documentation project are viewable from
http://creedon.biz.

The docs can be viewed on line however the DSL line is fairly slow and it is
suggested that the link to ftp://creedon.biz be used to download sources or
just the pdf's and html's.

The README.TXT file has directions. Both the html and pdf's were created
from the same Latex source files. Separate directories for html and pdf are
no longer necessary.

Perhaps someone could review the finals and put into cvs?

tedc
Jeffrey Altman
2005-06-27 19:47:20 UTC
Permalink
Post by ted creedon
The final versions of the documentation project are viewable from
_http://creedon.biz_.
The docs can be viewed on line however the DSL line is fairly slow and
it is suggested that the link to _ftp://creedon.biz_ be used to download
sources or just the pdf's and html's.
The README.TXT file has directionsÂ… Both the html and pdf's were created
from the same Latex source files. Separate directories for html and pdf
are no longer necessary.
Perhaps someone could review the finals and put into cvs?
tedc
As project owner for documentation, Moose will be the one to review and
determine if they should be committed to cvs.

Jeffrey Altman
Jeffrey Altman
2005-06-27 21:13:38 UTC
Permalink
If not I'll set up a CVS server here.
This project needs documentation that can be updated.
tedc
Ted:

we all agree that it does. however, the documentation
needs to be updatable by people other than yourself.
one of the requirements is that the tools used to produce
and maintain the documentation must be deemed usable by
those responsible for the project. Moose is the person
responsible for documentation.

While I am a strong believer that those who do the work
get significant points, there has been a significant lack
of consensus on the tools you selected to perform this work.
There have been complaints that the tools are too hard to use
and that they cannot be used to produce one of the required
outputs: man pages.

There have been suggestions made that other tools are
better suited for this effort including:

* POD files

* DocBook

* HTML

Of these my preference is either POD or DocBook. I prefer DocBook
because it has been used extensively by other open source projects to
generate both man pages and online documentation.

I like DocBook because it can be used to produce Windows HtmlHelp files
as well as HTML and PDF.

The benefits of the use of any of these formats over Tex are ease of
use. Tex is most definitely the best tool to use for generating precise
formatting for technical output. However, that is not a requirement for
this effort. For this effort, we need simplicity, the ability for all
contributors to understand the format, and the ability to to produce the
requisite outputs (preferably as part of the build system.)

POD files are nice in this respect since anyone that has Perl on their
system is able to generate man pages and html from POD files.

I require simplicity because I want to make it a requirement that all
source code contributions to the project are accompanied by
documentation updates. I can't make that requirement if the
documentation language is too complex.

Regardless, the final decision belong's to Moose.

Jeffrey Altman

P.S. - Private discussions on this topic are inappropriate. Please keep
all discussions on the subject of openafs documentation on the mailing list.
Russ Allbery
2005-06-27 21:17:03 UTC
Permalink
While I am a strong believer that those who do the work get significant
points, there has been a significant lack of consensus on the tools you
selected to perform this work. There have been complaints that the
tools are too hard to use and that they cannot be used to produce one of
the required outputs: man pages.
There have been suggestions made that other tools are better suited for
* POD files
* DocBook
* HTML
Of these my preference is either POD or DocBook. I prefer DocBook
because it has been used extensively by other open source projects to
generate both man pages and online documentation.
I like DocBook because it can be used to produce Windows HtmlHelp files
as well as HTML and PDF.
I think it's worth separating the format discussion somewhat between the
man pages (aka the Administrators Reference Manual, since that's pretty
much what that manual could be turned into and since it's already in a
man-like format) and the other documentation such as the install and
user's guide.

POD is inappropriate for the install and user's guide and I would never
suggest its use for that sort of a manual.

DocBook could do all of these, certainly. I will argue for POD over
DocBook *only* for the man pages, solely on the grounds of ease of editing
the raw source. DocBook, being XML-based, suffers from the standard XML
editing problems, and while those problems can be dealt with, I know that
I personally can proofread and edit POD several times faster than DocBook
and it's more amenable to simple tools like vi. I think this is a fairly
compelling argument, although I do understand why people might want to use
DocBook.

Another nice argument in favor of POD is that most of the work is already
done, although I expect the conversion script could be adapted to DocBook.

Speaking from a somewhat biased position as the maintainer of the POD to
man conversion tools, I also believe that POD produces noticably better
nroff than DocBook, resulting in nicer formatting in the final man page.

I only have a strong preference for the man page format; for the regular
manual format, I'm happy to help with whatever format people find the most
appealing. I know TeX, I know DocBook somewhat, I know HTML, and I know
texinfo, and I'm willing to help edit documents in any of those formats.
Going from straight TeX or LaTeX to man pages is not something I'd like to
attempt, though.
--
Russ Allbery (***@stanford.edu) <http://www.eyrie.org/~eagle/>
ted creedon
2005-06-27 21:52:18 UTC
Permalink
I didn't select the format - the users did after a mailing list discussion.

Anyway, I have documentation that suits my needs and others in the afs
community. Sounds like there will be 2 or 3 source formats to keep in sync.

Feel free to produce what you will. I have something I can edit and will
share it with the community either on SourceForge or elsewhere if not on the
afs site.

Keep me posted about content changes.

tedc

-----Original Message-----
From: openafs-doc-***@openafs.org [mailto:openafs-doc-***@openafs.org]
On Behalf Of Russ Allbery
Sent: Monday, June 27, 2005 2:17 PM
To: openafs-***@openafs.org
Subject: Re: [OpenAFS-Doc] Final (from Latex) pdf's and html's available
While I am a strong believer that those who do the work get
significant points, there has been a significant lack of consensus on
the tools you selected to perform this work. There have been
complaints that the tools are too hard to use and that they cannot be
used to produce one of the required outputs: man pages.
There have been suggestions made that other tools are better suited
* POD files
* DocBook
* HTML
Of these my preference is either POD or DocBook. I prefer DocBook
because it has been used extensively by other open source projects to
generate both man pages and online documentation.
I like DocBook because it can be used to produce Windows HtmlHelp
files as well as HTML and PDF.
I think it's worth separating the format discussion somewhat between the man
pages (aka the Administrators Reference Manual, since that's pretty much
what that manual could be turned into and since it's already in a man-like
format) and the other documentation such as the install and user's guide.

POD is inappropriate for the install and user's guide and I would never
suggest its use for that sort of a manual.

DocBook could do all of these, certainly. I will argue for POD over DocBook
*only* for the man pages, solely on the grounds of ease of editing the raw
source. DocBook, being XML-based, suffers from the standard XML editing
problems, and while those problems can be dealt with, I know that I
personally can proofread and edit POD several times faster than DocBook and
it's more amenable to simple tools like vi. I think this is a fairly
compelling argument, although I do understand why people might want to use
DocBook.

Another nice argument in favor of POD is that most of the work is already
done, although I expect the conversion script could be adapted to DocBook.

Speaking from a somewhat biased position as the maintainer of the POD to man
conversion tools, I also believe that POD produces noticably better nroff
than DocBook, resulting in nicer formatting in the final man page.

I only have a strong preference for the man page format; for the regular
manual format, I'm happy to help with whatever format people find the most
appealing. I know TeX, I know DocBook somewhat, I know HTML, and I know
texinfo, and I'm willing to help edit documents in any of those formats.
Going from straight TeX or LaTeX to man pages is not something I'd like to
attempt, though.
--
Russ Allbery (***@stanford.edu) <http://www.eyrie.org/~eagle/>
Jeffrey Altman
2005-06-27 22:58:55 UTC
Permalink
Post by ted creedon
I didn't select the format - the users did after a mailing list discussion.
Anyway, I have documentation that suits my needs and others in the afs
community. Sounds like there will be 2 or 3 source formats to keep in sync.
Feel free to produce what you will. I have something I can edit and will
share it with the community either on SourceForge or elsewhere if not on the
afs site.
Keep me posted about content changes.
tedc
Ted:

Can you please point me at the mailing list discussion that resulted in
the consensus to use laTex?

Jeffrey Altman
ted creedon
2005-06-27 23:24:38 UTC
Permalink
See the Sept 2004 mailing list and the enclosed e-mails with the previous
afs doc manager Renato Arruda.

Renato had a Latex version of all the docs partially done and in cvs. There
were several problems with Renato's sed scripts so html2latex was used
instead...

I suppose I could create diffs and update the Latex cvs archive, if its
still there...

<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
Relevant off-line e-mail:

Ted,

I agree that TeX is a lot better for most situations, but when it comes
down to man pages we can either do nroff or go with the info format from
gnu. and i think nroff does the job well. Maybe i should work on getting
them to LaTeX and then write a script to generate the nroff man pages.

I guess i'll just try to finish up this script and familiarize myself
with nroff and then convert the data from html to LaTeX.

What part of the manual you are working on again?

AFS Administrator's Guide
AFS Administration Reference
AFS Quick Start Guide for UNIX
AFS Quick Start Guide for Windows NT/2000 AFS User's Guide

I know i had a couple of those done in CVS, i'm pretty sure about AFS
User's Guide though. I think i had some work on AFS Administrator's Guide,
but I don't really know the status of the AFS Administration Guide.

If you feel it's better to toss out some of that work and start fresh,
i'm ok with that. Most of what's there was built using scripts i wrote
myself which i lost when i lost my $HOME volume.

I've been thinking actually that we could do some research on DocBook.
Maybe we could use it to then generate LaTeX, HTML, PDF, nroff and all sorts
of other file formats. The PHP Project uses it for their documentation and
the result is pretty slick. More info on
http://www.php.net/manual/howto/chapter-docbook.html . I'm not sure we want
to move to it or not, since it could make things overly complex, but it's
something worth looking at.

-Renato
Let me send you what I have Wed or thurs.
I think LaTex is a better bet than nroff.
1. can emit pdf and html
2. self indexing
3. variables can be used to set up standard transarc/linux paths 4.
variables can be used to emit OS specific documents
ted
-----Original Message-----
Sent: Sunday, May 23, 2004 4:16 PM
To: ted creedon
Subject: Re: AFS Documentation
Hi Ted,
I fired off my new public ssh key to Derrick today. What i had done in
http://openafs.org/cgi-bin/cvsweb.cgi/openafs-doc/
(But it sure needs improvement, it's just a copy of what's in the HTML
pages/pdf files, it definetly could use some updating).
Once i get access back i can commit your tex sources too if you wish,
or you can ask Derrick to get an account to do it yourself.
Which files are you working on? I'd really rather that we don't start
stepping in each other's toes. Right now i am working on a php script
to convert the old man pages into a format that linux understands
(nroff/troff? i forget the exact name). I'm getting the data from
http://www.openafs.org/pages/doc/AdminReference/auarf002.htm#ToC_54 .
-Renato
It sure wouldn't hurt.
I had a 740 page pdf file choke with Adobe and haven't had time to get
back to it. The smaller documents work OK though. I'll be back in
Portland wed-sun of this week after which I'm in Alaska for a month or 2.
Fortunately
I have AFS...
The intro worked out swell using a variable to include only the Linux
sections. You can change the variable to get SUN, AIX or
whatever..Printed it 4 pages per sheet double sided. Neat little handbook.
Ted
-----Original Message-----
Sent: Friday, May 21, 2004 4:16 PM
Subject: Re: AFS Documentation
Ted,
Should i talk to Derrick about trying to get the docs in cvs at
openafs.org's server ?
-Renato
I can set up subversion but I'd rather have an institution do it
Lyx is Latex++ - but I can llive with Latex
I did insers variables to allow printout of platform specific
manuals, the IBM docs are too bulky to use
ted
-----------------
Date: Sat, 17 Apr 2004 18:13:11 -0300
Subject: Re: AFS Documentation
Hi Ted,
Does lyx create good LaTeX, human readable code ? I think we should
definetly use AFS with cvs or something like subversion for the
versioning system (or use a stand-alone cvs or subversion server).
I'll wait to start until we all figure out what parts of the
documentation to convert and what metodologies we should use.
-Renato
-----Original Message-----
From: openafs-doc-***@openafs.org [mailto:openafs-doc-***@openafs.org]
On Behalf Of Jeffrey Altman
Sent: Monday, June 27, 2005 3:59 PM
To: ted creedon
Cc: 'Russ Allbery'; openafs-***@openafs.org
Subject: Re: [OpenAFS-Doc] Final (from Latex) pdf's and html's available
I didn't select the format - the users did after a mailing list
discussion.
Anyway, I have documentation that suits my needs and others in the afs
community. Sounds like there will be 2 or 3 source formats to keep in
sync.
Feel free to produce what you will. I have something I can edit and
will share it with the community either on SourceForge or elsewhere if
not on the afs site.
Keep me posted about content changes.
tedc
Ted:

Can you please point me at the mailing list discussion that resulted in the
consensus to use laTex?

Jeffrey Altman
Jeffrey Altman
2005-06-28 00:29:48 UTC
Permalink
Ted:

The quoted e-mails were not part of an online discussion. The only
posts that I see from Renato on any of the openafs mailing lists
(openafs-info) was a reply to you on 1/1/2004 responding to your
query for printable documentation.

The discussion on the openafs-info list starting from your posting of
9/12/2004 did not produce a consensus. It was primarily a discussion
between you and Tommie Gannert who was working on the Windows HTMLHelp
documentation. Tommie wanted to use DocBook because of its ability to
generate usable help files for Windows in addition to other output
usable on non-Windows platforms.

Tommie produced a set of output that allowed for autogeneration of
the Windows help files in the Wiki as proof of concept as well as a
HTMLHelp file. Unfortunately, Tommie has disappeared so I don't know
whether the work he did will end up being usable.

In any case, after the discussion which ended on 9/17/2004, you went
and began a PDF to Tex conversion and requested volunteers to help. No
one replied to the request on the list.

The next posting on the subject came from you on 1/12/2005 indicating
that you were predominately finished with the work. Esther at that time
requested copies. There is no further traffic on the mailing lists.
I assume that there was further traffic between the two of you that
occurred privately. In fact I know there was because I was cc'd on
some of it.

I wish that last week when all of us were in Pittsburgh that we could
have sat down for ten minutes. It was something I wanted to do.
Unfortunately, my schedule last week was insane with meetings taking
place during every break and meal.

My concern is that you and Esther need to work together on this. It
is my understanding that Esther is not satisfied with the choice of
Latex as a source format. However, I can find no such objection made
by her to any of the mailing lists. On the other hand, I can find no
clear consensus on the mailing lists that the choice of Latex as the
canonical source format is the right one.

I know that you sent some of the PDF -> Latex -> HTML output to Esther
and at one point she commented it was a good start. What I would like
to see here is an agreement be reached on what the canonical format for
the documentation should be. I don't want to see documentation be
maintained by separate groups. In the long run that is a sure fire way
of only making things worse than they are now.

Jeffrey Altman
Post by ted creedon
See the Sept 2004 mailing list and the enclosed e-mails with the previous
afs doc manager Renato Arruda.
ted creedon
2005-06-28 01:28:25 UTC
Permalink
Renato, not Esther, was listed on the afs website the official afs person
responsible for the documentation and he had started along the current route
having already reproduced all the docs in Latex.

Perhaps you should talk to him.

You have what you have from me, plus Russ' POD stuff. That's more than a
wish list that may never be done due to lack of skills&interest.

There are already 2 incompatible versions waiting for cvs. If you want a
third that's OK with me. Russ and I can keep our versions in sync..

There will be a current Latex version kept somewhere, there was enough
positive input from some users at the conference to support that.

tedc



-----Original Message-----
From: openafs-doc-***@openafs.org [mailto:openafs-doc-***@openafs.org]
On Behalf Of Jeffrey Altman
Sent: Monday, June 27, 2005 5:30 PM
To: ted creedon
Cc: openafs-***@openafs.org
Subject: Re: [OpenAFS-Doc] Final (from Latex) pdf's and html's available

Ted:

The quoted e-mails were not part of an online discussion. The only posts
that I see from Renato on any of the openafs mailing lists
(openafs-info) was a reply to you on 1/1/2004 responding to your query for
printable documentation.

The discussion on the openafs-info list starting from your posting of
9/12/2004 did not produce a consensus. It was primarily a discussion
between you and Tommie Gannert who was working on the Windows HTMLHelp
documentation. Tommie wanted to use DocBook because of its ability to
generate usable help files for Windows in addition to other output usable on
non-Windows platforms.

Tommie produced a set of output that allowed for autogeneration of the
Windows help files in the Wiki as proof of concept as well as a HTMLHelp
file. Unfortunately, Tommie has disappeared so I don't know whether the
work he did will end up being usable.

In any case, after the discussion which ended on 9/17/2004, you went and
began a PDF to Tex conversion and requested volunteers to help. No one
replied to the request on the list.

The next posting on the subject came from you on 1/12/2005 indicating that
you were predominately finished with the work. Esther at that time
requested copies. There is no further traffic on the mailing lists.
I assume that there was further traffic between the two of you that occurred
privately. In fact I know there was because I was cc'd on some of it.

I wish that last week when all of us were in Pittsburgh that we could have
sat down for ten minutes. It was something I wanted to do.
Unfortunately, my schedule last week was insane with meetings taking place
during every break and meal.

My concern is that you and Esther need to work together on this. It
is my understanding that Esther is not satisfied with the choice of Latex as
a source format. However, I can find no such objection made by her to any
of the mailing lists. On the other hand, I can find no clear consensus on
the mailing lists that the choice of Latex as the canonical source format is
the right one.

I know that you sent some of the PDF -> Latex -> HTML output to Esther and
at one point she commented it was a good start. What I would like to see
here is an agreement be reached on what the canonical format for
the documentation should be. I don't want to see documentation be
maintained by separate groups. In the long run that is a sure fire way
of only making things worse than they are now.

Jeffrey Altman
Post by ted creedon
See the Sept 2004 mailing list and the enclosed e-mails with the
previous afs doc manager Renato Arruda.
Derrick J Brashear
2005-06-28 01:55:04 UTC
Permalink
[]
Post by ted creedon
There are already 2 incompatible versions waiting for cvs. If you want a
third that's OK with me. Russ and I can keep our versions in sync..
Because lord knows what an understaffed project is many people doing the
same work repeatedly.
Post by ted creedon
There will be a current Latex version kept somewhere, there was enough
positive input from some users at the conference to support that.
All I'll say is it would be nice if there could be one master version all
the others could be generated from, which could be updated when
contributions of new functionality came in at the same time and in the
same place. Hand maintenance of many versions sucks, and will inevitably
lead to skew. Skew sucks more.
Esther Filderman
2005-06-28 02:55:48 UTC
Permalink
Ok, look. There are certain requirements here:

1) We should be using one system.

2) It should be simple enough for a non-programmer to use. [Like, say,
ME.] It should not require "special instructions" to update files.

3) It *MUST* generate, at the minimum, both some sort of "printable
format" and html. HTML is a *must* for the website.


I would rather try to preserve the conversion that Ted has done but I
am not convinced that LaTex is the right format to be using for
everything, mostly because generating solid HTML seems to be such a
problem.

There are tools to convert LaTex to DocBook [amusingly, there are
tools to convert POD *to* LaTex but not the other way, that I can
find]. Perhaps that's the way we should go.


I'm still researching DocBook & POD. I've also still got pneumonia
and am not up to speed on life.


e.
ted creedon
2005-06-28 03:37:52 UTC
Permalink
The many steps are only to convert the IBM.htm into editable Latex. IBM uses
quite a variety of special characters in their text.

This is a one time conversion.

Kerberos V and continuing maintenance scripts are not covered well in the
documents so a combination of text and commands cut and pasted into a \begin
{alltt} .... \end{alltt} can be done without worrying about the formatting.
I'll probably add Russ's tools in as needed. I'll probably replace the IBM
convention of <machine name> with a shell variable $S so commands can be cut
and directly pasted into an xterm.

Currently I am editing the Latex documents directly and incorporating other
materials into my documents.

Piece of cake.

I'm using html and pdf generated from these Latex source documents.

I prefer to:
"acroread auarf003.pdf auagd003.pdf auqbg003.pdf auusg003.pdf&"

All 4 Unix manuals are in one window and for once I have readable, linked,
searchable, uptodate documentation. (The html is not as visually correct as
the pdf but it does browse).

When something better arrives....

tedc

-----Original Message-----
From: openafs-doc-***@openafs.org [mailto:openafs-doc-***@openafs.org]
On Behalf Of Esther Filderman
Sent: Monday, June 27, 2005 7:56 PM
To: openafs-***@openafs.org
Subject: Re: [OpenAFS-Doc] Final (from Latex) pdf's and html's available


Ok, look. There are certain requirements here:

1) We should be using one system.

2) It should be simple enough for a non-programmer to use. [Like, say,
ME.] It should not require "special instructions" to update files.

3) It *MUST* generate, at the minimum, both some sort of "printable
format" and html. HTML is a *must* for the website.


I would rather try to preserve the conversion that Ted has done but I am not
convinced that LaTex is the right format to be using for everything, mostly
because generating solid HTML seems to be such a problem.

There are tools to convert LaTex to DocBook [amusingly, there are tools to
convert POD *to* LaTex but not the other way, that I can find]. Perhaps
that's the way we should go.


I'm still researching DocBook & POD. I've also still got pneumonia and am
not up to speed on life.


e.
Esther Filderman
2005-06-28 18:06:07 UTC
Permalink
First of all, please keep all documentation discussions on the mailing
list. Do not mail me privately.

The HTML files are big huge masses. These need to be broken down
further. HTML is the most common way people will read the
documentation [after man pages, but that's another ball of wax].
People will do as they do now, take quick looks on the online HTML documentation.

We also need to be able to generate indexes for each documentation
collection [ie admin guide, windows guide, etc].

e.



Turns out that the html is now generated from the same .tex files as pdf

Run tth au*003.tex instead of pdflatex au003.tex; No changes to the .tex
files are required.

The reason for doing the html first was to verify the correctness of the
conversion using diff on the source and final files.

tth is copyrighted and licensed for free use by non profits so I deleted it
from the current.

tedc

-----Original Message-----
From: openafs-doc-***@openafs.org [mailto:openafs-doc-***@openafs.org]
On Behalf Of Esther Filderman
Sent: Monday, June 27, 2005 7:56 PM
To: openafs-***@openafs.org
Subject: Re: [OpenAFS-Doc] Final (from Latex) pdf's and html's available


Ok, look. There are certain requirements here:

1) We should be using one system.

2) It should be simple enough for a non-programmer to use. [Like, say,
ME.] It should not require "special instructions" to update files.

3) It *MUST* generate, at the minimum, both some sort of "printable
format" and html. HTML is a *must* for the website.


I would rather try to preserve the conversion that Ted has done but I am not
convinced that LaTex is the right format to be using for everything, mostly
because generating solid HTML seems to be such a problem.

There are tools to convert LaTex to DocBook [amusingly, there are tools to
convert POD *to* LaTex but not the other way, that I can find]. Perhaps
that's the way we should go.


I'm still researching DocBook & POD. I've also still got pneumonia and am
not up to speed on life.


e.

_______________________________________________
OpenAFS-doc mailing list
OpenAFS-***@openafs.org
https://lists.openafs.org/mailman/listinfo/openafs-doc
ted creedon
2005-06-28 19:12:37 UTC
Permalink
Then you'll have to go to the html directory, they're set up that way there
and do link from file to file. (There are several hundred small files).

In the pdf directory the files are included.

The untarred html's are about 4mb, tarred 800K.

If indexing is needed that will have to be added by hand \index{foo} or if
\shortindexingon is used _{foo}.

The current index is 3 levels deep which latex supports but there's no way
to replicate that level of detail unless done by hand. Normally a
professional indexer does that.

As I've said, the IBM documentation is very well done.

tedc

-----Original Message-----
From: openafs-doc-***@openafs.org [mailto:openafs-doc-***@openafs.org]
On Behalf Of Esther Filderman
Sent: Tuesday, June 28, 2005 11:06 AM
To: openafs-***@openafs.org
Subject: Re: [OpenAFS-Doc] Final (from Latex) pdf's and html's available


First of all, please keep all documentation discussions on the mailing list.
Do not mail me privately.

The HTML files are big huge masses. These need to be broken down further.
HTML is the most common way people will read the documentation [after man
pages, but that's another ball of wax].
People will do as they do now, take quick looks on the online HTML
documentation.

We also need to be able to generate indexes for each documentation
collection [ie admin guide, windows guide, etc].

e.



Turns out that the html is now generated from the same .tex files as pdf

Run tth au*003.tex instead of pdflatex au003.tex; No changes to the .tex
files are required.

The reason for doing the html first was to verify the correctness of the
conversion using diff on the source and final files.

tth is copyrighted and licensed for free use by non profits so I deleted
it
from the current.

tedc

-----Original Message-----
From: openafs-doc-***@openafs.org
[mailto:openafs-doc-***@openafs.org]
On Behalf Of Esther Filderman
Sent: Monday, June 27, 2005 7:56 PM
To: openafs-***@openafs.org
Subject: Re: [OpenAFS-Doc] Final (from Latex) pdf's and html's available


Ok, look. There are certain requirements here:

1) We should be using one system.

2) It should be simple enough for a non-programmer to use. [Like, say,
ME.] It should not require "special instructions" to update files.

3) It *MUST* generate, at the minimum, both some sort of "printable
format" and html. HTML is a *must* for the website.


I would rather try to preserve the conversion that Ted has done but I am
not
convinced that LaTex is the right format to be using for everything,
mostly
because generating solid HTML seems to be such a problem.

There are tools to convert LaTex to DocBook [amusingly, there are tools
to
convert POD *to* LaTex but not the other way, that I can find]. Perhaps
that's the way we should go.


I'm still researching DocBook & POD. I've also still got pneumonia and
am
not up to speed on life.


e.

_______________________________________________
OpenAFS-doc mailing list
OpenAFS-***@openafs.org
https://lists.openafs.org/mailman/listinfo/openafs-doc

Loading...