[gentoo-doc] Handbook includes proposal

[Josh Saddler]

Hey guys. I thought of something a couple of days ago. More of an
evolutionary idea than a revolutionary one. So much so that I'm not sure
if anyone's thought of it before -- perhaps there was some discussion a
year or two ago when conditionals were first implemented, I don't recall.

The idea is this: <include/>s.

Simple, eh? We already do something vaguely related to this in the
handbook-$arch.xml files. It's a sort of opposite and complementary
approach to what we're already doing. Thing is, even in arch-specific
handbook pages, there's a lot of identical stuff. However, there's also
just enough different arch-specific stuff that we can't necessarily just
lump them all into one common doc with keyval tests, at least, not
without getting really muddy.

So, step around the issue. Take partitioning and filesystems, for
example. A lot of the explanatory text, paragraph after paragraph, is
identical, or at least should be in all the docs. So, we use an
<include/> to link that stuff in from another separate doc that holds
that stuff. This way we don't have all the eggs in one basket. It gets
easier to keep track of stuff.

Easier to find the critical stuff that changes from release to release.
I can see this also helping in post-release maintenance, as well; it's
quicker to change code stuff, or add new explanatory <notes> or whatever
that are good for all arches in the common external <include/> doc.

We could even still use the existing conditional keyvals, too; nothing
says those have to go away.

It's too bad I didn't think of this sooner, as I would have liked to
roll this out for this release. Also, it sounds like it might be rather
complicated on the backend side, and that's another concern -- I don't
think I have time for it, unless by some miracle I get all this stuff
done in a week. Then I could spend a bit restructuring and figuring out
common areas for the <include/>s -- if this happens at all, maybe we can
do it to the handbooks *after* the release is out the door.

So, thoughts? Comments? Concerns? Does it suck or has it been discussed
and vetoed previously? Is it too complicated to implement, period?

I think it's a good idea, and when I bounced it off JoseJX, he
agreed...so that's two so far. Anyone else?