On Wed, 2005-06-08 at 12:03 -0500, Tommy Reynolds wrote:
Uttered "Paul W. Frields" <stickster(a)gmail.com>,
spake thus:
As FDP's CVS admin, let me get the ball rolling:
> Elliot suggested simply subordinating these to a separate folder, which
> we could name appropriately. Some suggestions included docs-setup/ and
> docs-common/. This would mean there would now be docs-setup/xsl/, and
> so forth. The Makefile we use would have to be patched appropriately,
> of course.
I think this is a shrug to most folks, but I'm in favor of it.
> In light of the pace of these changes, and the fact that there are more
> on the horizon, I think we should re-examine requiring people do
> separate checkouts of a docs-setup module.
I raise objection to this on two points:
1) Duplicate copies if folk check out multiple documents; this is
really a minor nit.
Not that minor, wrt Karsten's previous post... could cause problems down
the line.
2) My real objection was the complication of importing a new
document
into CVS.
Consider: to start a new document, perhaps the easiest way is to
check out the "example-tutorial" document, recursively delete all
the CVS directories and then import it back as the new document.
There are other ways of creating the initial directory tree, so
don't get hung up on this point. The key idea is that a new
contributor will start with a virgin doc tree that has the
"docs-common" stuff as a subdirectory.
Now, the author is ready to import the document for the first
time. Any existing CVS directories must be deleted as well as the
"docs-common" tree before the import is done.
I think asking a newbie to be sure to do _any_ preparatory surgery
before an import is asking for trouble. It *is* possible to
import a "CVS/" directory although CVS is supposed to create that
necessary structure and now you've got trouble in River City.
You're on track here. Ease of use is Goal #1 AFAIC.
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.
I like B because it's magically delicious. No, really, it would be a
cool and helpful thing; saves a bunch of steps for everyone, new or not.
Not subject to Internet connectivity (very minor nit), plus less work to
get it up and running (less minor) :-).
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.
CVS can handle either model, so there is no technological reason to
prefer one method over the other. Let the list decide, but let the
list make an informed decision; either way works for me.
Hope this clarifies the problem for ya'll
Excellent, thanks.
--
Paul W. Frields, RHCE
http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
Fedora Documentation Project:
http://fedora.redhat.com/projects/docs/