| 1 |
Hey guys. I've got some more movin' and shakin' ideas to improve how we |
| 2 |
do the handbooks. This stems from a recent conversation I had with |
| 3 |
robbat2 on how git could be used instead of CVS. No, I'm not proposing |
| 4 |
that. That's another topic altogether. :) |
| 5 |
|
| 6 |
As you know, we maintain two handbooks: |
| 7 |
networked: /doc/$LANG/handbook/ |
| 8 |
networkless: /doc/$LANG/handbook/$RELEASE/ |
| 9 |
|
| 10 |
None of us are entirely happy about the counterintuitive naming, so I |
| 11 |
have a suggestion that will: |
| 12 |
1. give our handbooks better names |
| 13 |
2. improve the archives |
| 14 |
3. *greatly* ease the development of new handbooks at release time |
| 15 |
|
| 16 |
My proposal is this: |
| 17 |
networked: /doc/$LANG/handbook/$RELEASE-net/ |
| 18 |
networkless: /doc/$LANG/handbook/$RELEASE-nonet/ |
| 19 |
|
| 20 |
How does this help? |
| 21 |
1. It's obvious which handbook is for what, and it retains the release name. |
| 22 |
2. Now we can archive the networked handbook, which is appropriate as |
| 23 |
the old media is still available. |
| 24 |
3. No more copying stuff back and forth from draft/ to any other |
| 25 |
directory. When it's time for a new release, copy the stuff to the new |
| 26 |
$RELEASE-net/ or -nonet/ directory. Add a single draft disclaimer to the |
| 27 |
appropriate TOC, and you're done. At release time remove the disclaimer |
| 28 |
and add one to the previous handbooks, making sure to now link the |
| 29 |
$RELEASE-foo/ in the index. |
| 30 |
|
| 31 |
Speaking of index, right now index.xml is in handbook/ . With the |
| 32 |
proposed new structure, we still keep it in that TLD. It just points to |
| 33 |
various directories anyway. |
| 34 |
|
| 35 |
Included files are another matter. Right now, files in |
| 36 |
handbook/$RELEASE/ point one level up, to handbook/included.xml. We |
| 37 |
would probably have to put the included content in each dir, one for |
| 38 |
$RELEASE-net/ and one for $RELEASE-nonet/. This is because old archived |
| 39 |
handbooks need static content; if we were to keep them pointing to |
| 40 |
handbook/included.xml, this could be bad. |
| 41 |
|
| 42 |
Plus, it's conceivable that the networked or networkless handbooks might |
| 43 |
need different includes, so it makes sense to keep them all in their |
| 44 |
same dir. Again, this will help when it comes time to archive them. |
| 45 |
|
| 46 |
To sum up: |
| 47 |
handbook/2008.1-net/ |
| 48 |
handbook/2008.1-nonet/ |
| 49 |
handbook/2009.0-net/ |
| 50 |
handbook/2009.0-nonet/ |
| 51 |
etc. |
| 52 |
|
| 53 |
Thoughts? :) |
Archives