## For those wondering what is happening in the Documentation Project:
Fedora Documentation Steering Committee (FDSCo) 03-MAY-2005 #fedora-docs on irc.freenode.net
Attendees: ==========
Karsten Wade (chair) Tommy Reynolds Tammy Fox Gavin Henry Paul Frields Stuart Ellis
New Actions: ============
FDSCo: Find ways to get fame to documentors. Name up in lights. Etc.
FDSCo: You can post a link to your own self-intro or similar on your Wiki page.
FDSCo: Take the divided list of writers who have volunteered and contact them directly to see what help they need, or what their status and interest is.
Gavin: To make a Wiki Contributors page that incorporates the Writers and Editors pages somehow, linking to Self-Intros. This is part of the "find the interested writers" sub-project.
Gavin: Hunt fedoraforum.org for doc ideas and writers.
Gavin: To look into getting a FDSCo interview on lugradio.org.
Paul/Karsten: FDL for the new style chapter
Karsten: Assign task of making docs use common files in ./ instead of ../, in order to work for separate modules per document.
Karsten: Deliver minutes that are better organized, using the FESCO minutes as an example. Will start posting to fedora-announce as well as fedora-docs-list.
Karsten: Look into reordering CVS to make all documents in fedora-docs module into separate modules.
Tommy: Convert tasks into a schedule, split out goals, borrowing from Extras template.
Tammy: How to create a new CVS module, for the Doc Guide.
Tammy: Look into ViewCVS. One objective is to get regular reports of activity on documentation, in order to help define abandoned docs.
Tammy: Looking into sponsorship of Doc Days and similar incentives for community participation.
Action Status: ==============
* New writers will find this page very useful in getting started:
http://fedoraproject.org/wiki/DocsProject/NewWriters
* Details on gaining CVS access are available at:
http://fedoraproject.org/wiki/DocsProject/CvsUsage
* Stuart has made signficant progress on tracking the status of all documents ever proposed or in the works, pulling together information from disparate locations.
http://fedoraproject.org/wiki/DocsProject/EditorAssignments
* Paul and Karsten have the first iteration of the style guidelines put into the Doc Guide. These are required reading for writers and editors to be able to work together.
http://fedora.redhat.com/participate/documentation-guide/ch-style.html
* Karsten announced the style changes and noted they are required reading for writers and editors.
* CVS is available at /cvs/docs for all documentation projects.
Discussion Results: ===================
IDEA: A Docs Day, contest/competition with booty/prizes, for example, Bug Bounty.
NOTE: CVS: Separate module for all docs, makes it easier to check out.
NOTE: Wiki is acting as a work-in-progress area to make process and info available immediately. Eventually, all of this will be in the Doc Guide.
NOTE: If ViewCVS doesn't provide the reporting we need to track documentation activity, we can look into scraping fedora-docs-commits into a Wiki. Objective is to use existing tools to capture document status instead of having another Wiki page for everyone to keep updated.
NOTE: A layout/outline using blank XML pages is considered enough to get into CVS with.
NOTE: Snot is considered off-topic.
NOTE: It's nice to have a list of closed and accomplished tasks.
On Thu, 2005-05-05 at 16:45 -0700, Karsten Wade wrote:
Karsten: Assign task of making docs use common files in ./ instead of ../, in order to work for separate modules per document.
I can see the benefits of going both paths (centralized vs decentralized configs). Is there a lot of demand for local xsl customization in the fedora-docs/* documents?
Thanks, James Laska
On Fri, 2005-05-06 at 10:04 -0400, James Laska wrote:
On Thu, 2005-05-05 at 16:45 -0700, Karsten Wade wrote:
Karsten: Assign task of making docs use common files in ./ instead of ../, in order to work for separate modules per document.
I can see the benefits of going both paths (centralized vs decentralized configs). Is there a lot of demand for local xsl customization in the fedora-docs/* documents?
Actually, I don't think there would be that much demand, because it would be a hindrance to consistency. Karsten, there should be a pretty easy way to get modules to automatically "include" a checkout of the common stuff. In the CVSROOT/modules file, simply insert this near the top of the list. (The list itself is a little hinky, and could probably use some trimming, since it has a bunch of entries that don't match existing stuff in the repository.)
base common css scripts xsl
Then, for any directories containing docs (i.e. modules), do:
module module &base
The name "module" would be the name of the directory used for the module, i.e. "translation-guide," "jargon-buster," etc. The other four modules will come down automatically along with the requested module. Look at the Extras CVSROOT/modules for examples -- there are plenty of them! :-)
The nice thing about this scenario is that the CVS maintainer will always be on top of what's added into CVS, since that person will be adding a module definition into CVSROOT/modules for the new document. There's no need to change the way we're doing business, existing Makefiles all stay the same, and the use of "../common/*" doesn't change.
On Fri, 2005-05-06 at 10:48 -0400, Paul W. Frields wrote:
On Fri, 2005-05-06 at 10:04 -0400, James Laska wrote:
On Thu, 2005-05-05 at 16:45 -0700, Karsten Wade wrote:
Karsten: Assign task of making docs use common files in ./ instead of ../, in order to work for separate modules per document.
I can see the benefits of going both paths (centralized vs decentralized configs). Is there a lot of demand for local xsl customization in the fedora-docs/* documents?
Actually, I don't think there would be that much demand, because it would be a hindrance to consistency. Karsten, there should be a pretty easy way to get modules to automatically "include" a checkout of the common stuff. In the CVSROOT/modules file, simply insert this near the top of the list. (The list itself is a little hinky, and could probably use some trimming, since it has a bunch of entries that don't match existing stuff in the repository.)
base common css scripts xsl
Then, for any directories containing docs (i.e. modules), do:
module module &base
Whoops, that should have been:
module module base
Using the "&" ampersand symbol moves the common/, xsl/, etc. *under* the checked-out module, meaning that everyone would have to change existing Makefiles, DTD's, etc.
On Fri, 2005-05-06 at 10:52 -0400, Paul W. Frields wrote:
Whoops, that should have been:
module module base
Using the "&" ampersand symbol moves the common/, xsl/, etc. *under* the checked-out module, meaning that everyone would have to change existing Makefiles, DTD's, etc.
And after I wrote all that, I read this ... sometimes even I forget to read the whole thread thoroughly. :)
So, this would check out the common directories at ../ where they lie currently?
Sounds fine to me, less maintenance headache now and the future. Also keeps people from having to a) go into each module and do 'cvs up' to get the latest changes to the common modules, and b) keeps people from thinking of the common modules as unique and mutable. Then they might (gasp!) customize them. :D
- Karsten
On Fri, 2005-05-06 at 10:48 -0400, Paul W. Frields wrote:
On Fri, 2005-05-06 at 10:04 -0400, James Laska wrote:
On Thu, 2005-05-05 at 16:45 -0700, Karsten Wade wrote:
Karsten: Assign task of making docs use common files in ./ instead of ../, in order to work for separate modules per document.
I can see the benefits of going both paths (centralized vs decentralized configs). Is there a lot of demand for local xsl customization in the fedora-docs/* documents?
Actually, I don't think there would be that much demand, because it would be a hindrance to consistency. Karsten, there should be a pretty easy way to get modules to automatically "include" a checkout of the common stuff.
Yes. What the above task refers to is re-writing the parent XML files to reference ./common instead of ../common, etc. Same for the Makefile. The task is predicated on the idea that we are going to have certain directories included as part of a common checkout, within the body of the module itself.
Another way is to have a massive common module that must be checked out and available at ../. I think I prefer to have it all within ./ and just fix the few docs we have.
Does this make sense?
thx - Karsten
Uttered Karsten Wade kwade@redhat.com, spake thus:
Another way is to have a massive common module that must be checked out and available at ../. I think I prefer to have it all within ./ and just fix the few docs we have.
Does this make sense?
Not to me. Just take the current structure we have and move it up one directory level. Make a separate module out of every top-level directory you see there. Couple of benefits:
1) Directory/module structure makes commonality obvious; which
2) Reduces tempation to fiddle with style sheets, Makefiles, et. al., because they "just aren't yours".
I like the file system layout to mirror our approach and what few policies we have in place.
Of course, this is just my $0.02e+31 worth ;-)
Cheers
On Fri, 2005-05-06 at 18:16 -0500, Tommy Reynolds wrote:
Uttered Karsten Wade kwade@redhat.com, spake thus:
Another way is to have a massive common module that must be checked out and available at ../. I think I prefer to have it all within ./ and just fix the few docs we have.
Does this make sense?
Not to me. Just take the current structure we have and move it up one directory level. Make a separate module out of every top-level directory you see there. Couple of benefits:
Directory/module structure makes commonality obvious; which
Reduces tempation to fiddle with style sheets, Makefiles, et. al., because they "just aren't yours".
I like the file system layout to mirror our approach and what few policies we have in place.
Of course, this is just my $0.02e+31 worth ;-)
Yeah, I reversed myself in another post not one minute later, which you are probably reading right now. I agree with your reasoning, and now that I see how it works, great!
Can you and Paul work on the details for the following, then create a window to do it in to keep from having merge/sync problems?
* Move everything in fedora-docs up one level and make them separate modules * Leave the common files where they are * Make the changes to CVSROOT/modules so that checking out a module makes sure you get the common modules (xsl/, common/, css/, etc.)
Tell me how to grant you two the permissions you need to make this happen. I'd like you both to help with CVS maintenace, s'il vous plait.
cheers - Karsten
Uttered Karsten Wade kwade@redhat.com, spake thus:
Can you and Paul work on the details for the following, then create a window to do it in to keep from having merge/sync problems?
- Move everything in fedora-docs up one level and make them separate
modules
- Leave the common files where they are
- Make the changes to CVSROOT/modules so that checking out a module
makes sure you get the common modules (xsl/, common/, css/, etc.)
Tell me how to grant you two the permissions you need to make this happen. I'd like you both to help with CVS maintenace, s'il vous plait.
Sure, I can do that.
To avoid losing any CVS history, it would be best if Paul or I or both had shell access on the server. Do we have any CVS history worth preserving yet?
Cheers
On Fri, 2005-05-06 at 21:50 -0500, Tommy Reynolds wrote:
Uttered Karsten Wade kwade@redhat.com, spake thus:
Can you and Paul work on the details for the following, then create a window to do it in to keep from having merge/sync problems?
- Move everything in fedora-docs up one level and make them separate
modules
- Leave the common files where they are
- Make the changes to CVSROOT/modules so that checking out a module
makes sure you get the common modules (xsl/, common/, css/, etc.)
Tell me how to grant you two the permissions you need to make this happen. I'd like you both to help with CVS maintenace, s'il vous plait.
Sure, I can do that.
To avoid losing any CVS history, it would be best if Paul or I or both had shell access on the server. Do we have any CVS history worth preserving yet?
Ah, I see. I'd say that we do have CVS history worth saving, presuming that it's still there from before the move.
How about we do all new documents as new modules, and when Elliott is available, we can have him do the change. I'd guess that shell access on cvs.fedora is hard to come by.
- Karsten
Uttered Karsten Wade kwade@redhat.com, spake thus:
Ah, I see. I'd say that we do have CVS history worth saving, presuming that it's still there from before the move.
How about we do all new documents as new modules, and when Elliott is available, we can have him do the change. I'd guess that shell access on cvs.fedora is hard to come by.
I'd think that too. In that case, Elliott can do the whole shebang in about three minutes, while Paul and I watch over his shoulder and joggle his elbow.
Cheers
On Sat, 2005-05-07 at 13:46 -0500, Tommy Reynolds wrote:
Uttered Karsten Wade kwade@redhat.com, spake thus:
Ah, I see. I'd say that we do have CVS history worth saving, presuming that it's still there from before the move.
How about we do all new documents as new modules, and when Elliott is available, we can have him do the change. I'd guess that shell access on cvs.fedora is hard to come by.
I'd think that too. In that case, Elliott can do the whole shebang in about three minutes, while Paul and I watch over his shoulder and joggle his elbow.
Here's a patch that I guess will work for now. Karsten, you have commit perms for CVSROOT/ so you will need to put this one up. I don't think we'll need shell access for anything. If we can get Elliot to simply put us in the CVSROOT/avail file as having rights to write to CVSROOT/modules (and really we only need that file, I think), we can add modules when needed.
On Sun, 2005-05-08 at 19:13 -0400, Paul W. Frields wrote:
On Sat, 2005-05-07 at 13:46 -0500, Tommy Reynolds wrote:
Uttered Karsten Wade kwade@redhat.com, spake thus:
Ah, I see. I'd say that we do have CVS history worth saving, presuming that it's still there from before the move.
How about we do all new documents as new modules, and when Elliott is available, we can have him do the change. I'd guess that shell access on cvs.fedora is hard to come by.
I'd think that too. In that case, Elliott can do the whole shebang in about three minutes, while Paul and I watch over his shoulder and joggle his elbow.
Here's a patch that I guess will work for now. Karsten, you have commit perms for CVSROOT/ so you will need to put this one up. I don't think we'll need shell access for anything. If we can get Elliot to simply put us in the CVSROOT/avail file as having rights to write to CVSROOT/modules (and really we only need that file, I think), we can add modules when needed.
I thought Tommy was saying that we _couldn't_ just write the new modules file this way because we'd lose CVS history for those modules. Or is this patch in preparation for Elliott doing cvs-fu? We can actually find someone else to do that cvs-fu, instead of panting on Elliott's doorstep for his return. Otherwise, I'll apply the patch.
Thanks for doing this!
- Karsten
On Sun, 2005-05-08 at 18:44 -0700, Karsten Wade wrote:
On Sun, 2005-05-08 at 19:13 -0400, Paul W. Frields wrote:
On Sat, 2005-05-07 at 13:46 -0500, Tommy Reynolds wrote:
Uttered Karsten Wade kwade@redhat.com, spake thus:
Ah, I see. I'd say that we do have CVS history worth saving, presuming that it's still there from before the move.
How about we do all new documents as new modules, and when Elliott is available, we can have him do the change. I'd guess that shell access on cvs.fedora is hard to come by.
I'd think that too. In that case, Elliott can do the whole shebang in about three minutes, while Paul and I watch over his shoulder and joggle his elbow.
Here's a patch that I guess will work for now. Karsten, you have commit perms for CVSROOT/ so you will need to put this one up. I don't think we'll need shell access for anything. If we can get Elliot to simply put us in the CVSROOT/avail file as having rights to write to CVSROOT/modules (and really we only need that file, I think), we can add modules when needed.
I thought Tommy was saying that we _couldn't_ just write the new modules file this way because we'd lose CVS history for those modules. Or is this patch in preparation for Elliott doing cvs-fu? We can actually find someone else to do that cvs-fu, instead of panting on Elliott's doorstep for his return. Otherwise, I'll apply the patch.
Thanks for doing this!
I didn't understand the ramifications; ignore my patch. Tommy, maybe you could do some tests on a dummy repository to find out what the right course of action is.
Uttered "Paul W. Frields" stickster@gmail.com, spake thus:
I didn't understand the ramifications; ignore my patch. Tommy, maybe you could do some tests on a dummy repository to find out what the right course of action is.
Whomever is going to be allowed to create modules needs to be added to 'CVSROOT/avail' as indicated earlier.
Trivially simple. On the server do this:
$ cd $CVSROOT/fedora-docs $ mv * ../ $ cd ../ $ echo 'modules CVSROOT modules' >modules $ echo [[:lower:]]* | xargs -n1 >>modules
Anybody who already has the current CVS setup checked out need only run the following script on their local 'fedora-docs/' directory to change the content of their 'CVS/Repository' file from 'fedora-docs/foo' to simply 'foo'.
=== recvs.sh script ===
#!/bin/bash find ${*:-.} -type d -name CVS -print | while read cvsdir do ( cd ${cvsdir} sed -s 's;fedora-docs/;;' Repository >Repository.tmp mv -f Repository Repository-orig mv Repository.tmp Repository rm -f Repository-orig ) done
=== recvs.sh script ===
Of course, clients can simply get the new repositories again.
Cheers