Gentoo Archives: gentoo-doc

From: Josh Saddler <nightmorph@g.o>
To: gentoo-doc@l.g.o
Subject: [gentoo-doc] Handbook restructuring proposal
Date: Fri, 02 May 2008 20:01:22
Hey guys. I've got some more movin' and shakin' ideas to improve how we 
do the handbooks. This stems from a recent conversation I had with 
robbat2 on how git could be used instead of CVS. No, I'm not proposing 
that. That's another topic altogether. :)

As you know, we maintain two handbooks:
networked: /doc/$LANG/handbook/
networkless: /doc/$LANG/handbook/$RELEASE/

None of us are entirely happy about the counterintuitive naming, so I 
have a suggestion that will:
1. give our handbooks better names
2. improve the archives
3. *greatly* ease the development of new handbooks at release time

My proposal is this:
networked: /doc/$LANG/handbook/$RELEASE-net/
networkless: /doc/$LANG/handbook/$RELEASE-nonet/

How does this help?
1. It's obvious which handbook is for what, and it retains the release name.
2. Now we can archive the networked handbook, which is appropriate as 
the old media is still available.
3. No more copying stuff back and forth from draft/ to any other 
directory. When it's time for a new release, copy the stuff to the new 
$RELEASE-net/ or -nonet/ directory. Add a single draft disclaimer to the 
appropriate TOC, and you're done. At release time remove the disclaimer 
and add one to the previous handbooks, making sure to now link the 
$RELEASE-foo/ in the index.

Speaking of index, right now index.xml is in handbook/ . With the 
proposed new structure, we still keep it in that TLD. It just points to 
various directories anyway.

Included files are another matter. Right now, files in 
handbook/$RELEASE/ point one level up, to handbook/included.xml. We 
would probably have to put the included content in each dir, one for 
$RELEASE-net/ and one for $RELEASE-nonet/. This is because old archived 
handbooks need static content; if we were to keep them pointing to 
handbook/included.xml, this could be bad.

Plus, it's conceivable that the networked or networkless handbooks might 
need different includes, so it makes sense to keep them all in their 
same dir. Again, this will help when it comes time to archive them.

To sum up:

Thoughts? :)


File name MIME type
signature.asc application/pgp-signature


Subject Author
[gentoo-doc] Re: Handbook restructuring proposal Duncan <1i5t5.duncan@×××.net>
Re: [gentoo-doc] Handbook restructuring proposal Sven Vermeulen <swift@g.o>