F11 release notes spec

[Paul W. Frields]

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20090411/2bc77c61/attachment.sig>