Test of Docs Packaging

[James Laska]

I sent this earlier but was experiencing mail issues this morning ...
resending ...

>>>>>

Greetings,

So I have some local changes to the Makefile.common that will add
support for archiving and packaging (rpm) documentation.  The changes
will not require individual doc writers to modify their Makefile as all
the wholesome goodness is placed into the Makefile.common.  While doing
this I did run into some issues that I'm sure you folks have already
addressed/discussed.  I thought perhaps it would be better to raise the
issues for discussion before submitting patches.

The first issue was how to handle CVS versus packaging.  By that I mean
when working out of CVS, you are expected to have a path
"../docs-common/" that resolves.  That isn't necessarily true when
working out of the archive (tarball) or the rpm.  So, when using the
tarball or rpm I took the assumption that you must have the
fedora-doc-common.rpm installed (or the tarball installed).  That seemed
to me like a sane transition since you are leaving the CVS realm at that
point.  This then provides for package work and building of your docs
outside of CVS.  

To complete this transition, I have a rule in Makefile.common that
changes a variable FDC_PREFIX from "../docs-common/" to
"/usr/share/fedora/doc/docs-common/".  This change works it's way into
the documents Makefile and xml.  Thoughts/concerns?


An alternative is to drop the dependency on the CVS module docs-common
completely.  This change would involve requiring doc writers to install
the fedora-doc-common-*.rpm in order to have the required
css,stylesheet-images,xsl.  If we adopt this, all doc references to
"../docs-common" will need to be changed.

There are a few other nits that I've encountered while making some
changes.  But overall, it was much easier than I anticipated.  The
current Makefile.common is well structured and easy to follow for this
type of work.


Another future concern is that every document includes it's own css and
stylesheet-images.  While there isn't much there in terms of file size,
it does some like we should be able to share these items.  Does anyone
have thoughts/preference as to whether it might be better to change file
paths for "{admon,callout}.graphics.path" in the html-common.xsl to
point to a system-wide location?  Including these files does offer the
benefit of portable documents since they include their own images and
css.


The more I think about it the more it seems like removing
the ../docs-common/ CVS paths is the way to go.  In favor of having
doc-writers install the fedora-doc-common rpm.  I could be missing
something, but it seems like there are fewer prickly thorns down that
path.

Thoughts/comments/concerns?

Many thanks!
James Laska

On Thu, 2005-10-13 at 09:27 -0500, Tommy Reynolds wrote:
> Uttered "Paul W. Frields" <stickster at gmail.com>, spake thus:
> 
> > Right.  If you update your docs-common module again, you'll get the
new
> > stuff to package fedora-doc-common.
> 
> Paul,
> 
> Two issues have slowly emerged from the recesses of my mind (which is
> always in recess, if you get my drift). Forgive me if they have
> already been discussed:
> 
> 1.  This all looks quite compilated to leave in Makefile.<whatever>.
>     Do you think that packaging this as a shell script would be
>     cleaner and easier to maintain?  Just use the same
>     Makefile.common technology I used for the i18n conversion to
>     generate the per-language targets and pickle off the shell script
>     from there.
> 
> 2.  The "noarch" RPM's actually contain the source; that's more a
>    "src.rpm" or "-devel.noarch.rpm" to me.  Don't we need room in the
>    namespace for a PDF / HTML flavor of the RPM?  Perhaps
>    "foo-html.noarch.rpm"?
> 
> Late to the party, but Cheers
> -- 
> fedora-docs-list mailing list
> fedora-docs-list at redhat.com
> To unsubscribe: 
> https://www.redhat.com/mailman/listinfo/fedora-docs-list
-- 
==========================================
 James Laska         -- jlaska at redhat.com
 Quality Engineering -- Red Hat, Inc.
==========================================