Re: [gentoo-doc] Handbook includes proposal

[Josh Saddler]

Josh Saddler wrote:
> 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?
>

It's been 6 months and a whole release has gone by, and I'm now starting
to get email from releng on the early work for 2007.1. So, who's
interested? I'm all in favor of decreasing the workload for future
handbook maintenance.

Xavier, can we get some XSL-fu from you to make it happen?