Packaging progress

[Paul W. Frields]

Hi Docs gangstas,

I am steadily making progress toward a packaging solution.  Thanks to
Tommy jumping in with XSLT-based solutions, I learned a lot (although
not nearly enough, of course) about how to solve other problems using
the same building blocks.  I also -- finally! -- figured out how to
package documentation for KDE's khelpcenter, and believe me, it's not
self-evident.  Or rather, the end-state is comprehensible, but the
procedure for getting there cleanly is not.  In any case, that's solved
too.  

Also, the "fedora-doc-common" RPM is just about ready for rollout and
will contain (hopefully) everything required for people not operating
out of CVS to build docs.  Mostly this just involves including our XSL
snippets, entities, custom scripts, and so forth.  This is not to say
that by installing this RPM people will be able to just happily build
away, but it puts that goal within reach.

Since the fedora-doc-* stuff will probably live in Fedora Extras, and
because that is a rolling repository, it is much easier for us to work
on this in phases.  Phase One goals are for our currently available
documents to be installable by an end user using yum, and that those
documents should show up prominently in each of the locations a user
might expect:

  1. Launching "Desktop -> Help" for GNOME or KDE
  2. Launching "Documentation -> [title]"

I don't know yet what Phase Two entails, but some goals might include:

  1. Nice Python scripts for creating new XML document templates
  2.   "    "       "    for building DRAFT-marked documents?

Some items I am still in the process of solving, by which I mean I
should be able to finish them for Phase One:

- The rpm-info.dtd needs some lovin':
  - Packages should not get separate versions, too confusing
  - Docs should not get releases, also confusing
  - Figure out a way to condense generic person entries for use as
authors, editors, translators, and/or packagers?  Alternately, remove
those not needed -- e.g. packagers only need full name and email,
authors, editors and translators need "component" names, and people
performing revisions only need initials.  Some reference to dbpoolx.mod
shows this shouldn't be too hard to do.

- Provide functionality to automatically sort "doc" or "rpm"
revisions.
Because RPM is particular about things like date formats in %changelog
entries, we may need to "encourage" proper formatting using the DTD.  We
already have a *strong* hint there in the attributes Tommy provided, but
I don't think there's anything built in to a DTD to check for ordering;
I believe, however, that XSLT can sort.  Anything we can do to
bulletproof the process is probably good.  If it proves too cumbersome
to complete RSN, I'll push this off until Phase Two.

That's it from my neck of the woods.  Hope everyone is enjoying the
holidays.  The holiday break and the patience of my ever-lovin' wife are
the main reason I've been able to work on this stuff for the last few
days.  Best to all, and here's to a Happy New Year!

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/