On Wed, 2005-06-08 at 12:03 -0500, Tommy Reynolds wrote:
Possible solutions are:
A) Document, document, document the proper (nonstandard)
procedure for importing a document and ask newbies to follow
it unerringly; or
B) Provide a shell script that will do the cleanup and importing
for them and ask that they use the script instead of doing the
CVS import themselves. We'll still have to clean up the
mess when they ignore the script and try to learn about CVS
by doing the import manually; or
C) Write a PGP(?) / Wiki(?) / HTML(?) / Java(?) page that will do
the selective importing if the newbie just identifies the
top-level directory in a form. Very similar to attaching a
file to a Yahoo mail message. or
D) Keep the "docs-common" as a peer directory that needs be
updated only when the CVS structure changes or when a document
fails to build because of a missing entity.
Ah, I see.
Having docs-common as a peer directory seems to be the least
mainentance, hassle, and chance of breaking in a bad way.
We can easily have a list of common errors in the Documentation Guide
that mean you need to look for an update to docs-common.
Options A, B, and C require too much for the value they bring.
Option D only risks minor problems for the user that teaches them better
how to fish when it happens.
My point is the current setup has a painless, no-error-possible
document import. I don't really care if a stylesheet changes an
indent from 0.5in to 0.56in because the document rendering on the
local system isn't critical. Anyone wanting "proper" documents can
just update the "docs-common" before sending the PDF to the printers.
I agree with this except that the current setup does need a tweak, which
is why we have this thread. Elliott pointed out the messiness of all
the little directories that docs-setup brings down, and he was echoing
something that I thought. Already we have four directories that need to
be brought down to peer level and updated separately.
Reading between the lines in your post, I *think* you agree with this
reason for moving everything into a single module, docs-common.
- Karsten
--
Karsten Wade, RHCE * Sr. Tech Writer *
http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41
Red Hat SELinux Guide
http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/