Gentoo Logo
Gentoo Spaceship




Note: Due to technical difficulties, the Archives are currently not up to date. GMANE provides an alternative service for most mailing lists.
c.f. bug 424647
List Archive: gentoo-doc
Navigation:
Lists: gentoo-doc: < Prev By Thread Next > < Prev By Date Next >
Headers:
To: gentoo-doc@g.o
From: Josh Saddler <nightmorph@g.o>
Subject: Handbook restructuring proposal
Date: Fri, 02 May 2008 13:01:14 -0700
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:
handbook/2008.1-net/
handbook/2008.1-nonet/
handbook/2009.0-net/
handbook/2009.0-nonet/
etc.

Thoughts? :)

Attachment:
signature.asc (OpenPGP digital signature)
Replies:
Re: Handbook restructuring proposal
-- Sven Vermeulen
Re: Handbook restructuring proposal
-- Duncan
Navigation:
Lists: gentoo-doc: < Prev By Thread Next > < Prev By Date Next >
Previous by thread:
Improving organization during beta release
Next by thread:
Re: Handbook restructuring proposal
Previous by date:
Re: Improving organization during beta release
Next by date:
Re: Handbook restructuring proposal


Updated Jun 17, 2009

Summary: Archive of the gentoo-doc mailing list.

Donate to support our development efforts.

Copyright 2001-2013 Gentoo Foundation, Inc. Questions, Comments? Contact us.