On Sat, Apr 11, 2009 at 09:54:41AM -0400, John J. McDonough wrote:
This is really about questions for Paul, but there were a few
surprises
for me so I thought I would post this to the list just to share the
knowledge.
In F10, we built the release notes from the xml, then copied the xml and
resulting html into the RPM. There were also a handful of associated
documents which sort of caught me by surprise.
My plan in F11 Preview is to pretty much follow the .spec file for F10,
with the exception that for the release notes proper I will do the
Publican part of the build inside the srpm. Given the timeline I don't
think we are quite ready to face the whole subpackage thing, although I'm
not writing that off for GA.
Some outstanding questions, mostly around gnome-help:
- What is up with the .omf files? Are they simply prepared manually and
included? What do they do? With my test document I can read the doc fine
with yelp and no omf files, in each of my 3 test languages
The OMF files are required to make menu entries in the Help main
screen. If you go to System > Help in F10, you'll see the Release
Notes represented there. Without an OMF that can't happen.
- What on earth is scrollkeeper and what does it do and why do we
care?
Scrollkeeper (now rarian, which has backward-compat entries in
/usr/bin/) is a documentation meta-librarian. It allows the GNOME
Help system to refer to man pages, info pages, and other documentation
in a unified system.
- In gnome-help there are a handful of topics, one of which is
release
notes. How did that get there? Hardcoded?
The OMF makes this happen. The OMFs are stored in
/usr/share/omf/${name}/${name}-${lang}.omf and the 'scrollkeeper-*'
utilities enter them in the database.
- You created symlinks for some images to avoid duplication. We have
a
similar Publican issue, worth a little over 100K per language. Should we
do the same for F11?
Good question. If Publican could use subpackaging sanely, it would
provide a common RPM that all the languages would require, so that the
common content would only be installed once. Linking is generally
frowned on for something like this, I think -- and even with 20
languages, we're only looking at ~2 MB of additional content. I don't
think it's worth the trouble to figure out the linking aspect.
- The whole copying business in the old .spec I found particularly
hard to
follow. Although I kept the basic steps, I hacked up the appearance quite
a bit to make it more readable (to me). Here is a little snippet of the
relevant parts. Do you see any issues with this approach? (This is a test
document to make it run through Publican quicker)
# Loop through the languages
#
for LANG in tmp/* ; do
It would make more sense to do this instead:
for LANGDIR in tmp/* ; do
LANG=${LANGDIR#tmp/}
Then proceed as before, using ${LANG} everywhere instead of repetitive
${LANG#tmp/}. Improves readability and also makes it easier to make
changes without missing things later.
#
# First, the html in /usr/share/doc/HTML
#
# Place where html files are
SRCBASE=tmp/${LANG#tmp/}/html-desktop
# Target for release notes html
NOTETARG=$RPM_BUILD_ROOT%{_defaultdocdir}/HTML/%{name}/${LANG#tmp/}
mkdir -p ${NOTETARG}
install -m 644 ${SRCBASE}/index.html ${NOTETARG}/%{name}-${LANG#tmp/}.html
mkdir -p ${NOTETARG}/Common_Content
mkdir -p ${NOTETARG}/Common_Content/css
mkdir -p ${NOTETARG}/Common_Content/images
mkdir -p ${NOTETARG}/images
install -m 644 ${SRCBASE}/Common_Content/css/*
${NOTETARG}/Common_Content/css
install -m 644 ${SRCBASE}/Common_Content/images/*
${NOTETARG}/Common_Content/images
install -m 644 ${SRCBASE}/images/* ${NOTETARG}/images
#
# Now the gnome_help files
#
# Place where xml files are
SRCBASE=tmp/${LANG#tmp/}/xml
# gnome-help target for xml files
HELPTARG=$RPM_BUILD_ROOT%{_datadir}/gnome/help/%{name}/${LANG#tmp/}
mkdir -p ${HELPTARG}
mkdir -p ${HELPTARG}/Common_Content
mkdir -p ${HELPTARG}/images
install -m 644 ${SRCBASE}/images/* ${HELPTARG}/images
for F in ${SRCBASE}/Common_Content/*.xml ; do
install -m 644 ${F} ${HELPTARG}/Common_Content
done
mkdir -p ${HELPTARG}/Common_Content/css
install -m 644 ${SRCBASE}/Common_Content/css/*
${HELPTARG}/Common_Content/css
mkdir -p ${HELPTARG}/Common_Content/images
install -m 644 ${SRCBASE}/Common_Content/images/*
${HELPTARG}/Common_Content/images
for F in ${SRCBASE}/*.xml ; do
install -m 644 ${F} ${HELPTARG}/
done
done
--McD
If it works and doesn't violate any packaging guidelines, go for it.
As Tommy Reynolds always said to me, you break it, you own it! :-)
But more seriously, how the script is written is really not as
important as people knowing how it works. You may want to add
comments liberally if you fear looking at it later and not recalling
how things worked.
--
Paul W. Frields
http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
http://redhat.com/ - - - -
http://pfrields.fedorapeople.org/
irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug