Publican Issues for RNs

[Jeff Fearn]

Paul W. Frields wrote:
> On Thu, Mar 12, 2009 at 08:57:52AM -0400, John J. McDonough wrote:
>> Let me preface this by mentioning that I haven't got a clue about packaging,
>> so assuming I am a complete idiot wouldn't be inappropriate.
>>
>> Eric discovered back in January that there are a couple of show stoppers to
>> using Publican for Docs.  He thought he was going to get the issues fixed in
>> a short time, but that hasn't happened, and it doesn't look like it will
>> happen.  Eric developed a workaround by hacking Publican.  Unfortunately,
>> using this approach would require everyone participating in Docs to have a
>> hacked Publican, and the hack breaks Publican for other uses.  A switch
>> would be nice, and acceptable to the Publican developers, but apparently it
>> would take a lot of effort and there is only one maintainer.
> 
> Can Jeff Fearn or some other knowledgeable person explain here what's
> needed for that switch?  We probably can find some resources for
> writing that switch, but to do that we need to know what's required.

I haven't looked to deeply in to it. The tar/package name structure is 
use in many of the templates in the common Makefiles and testing having 
two naming methods would require some pretty robust analysis.

>> Publican does almost everything we need to do between the wiki and the RPM,
>> so we would really like to use it rather than the mish-mash of tools we
>> currently have.
>>
>> There are two problems:
>> 1) Publican names the package incorrectly

For values of incorrectly that are not in the published fedora package 
naming guidelines AND for values of incorrectly that fail miserably to 
understand the value-add that having access to multiple versions of 
product documentation on your desktop offers.

Being able to review the fedora 11 release notes on fedora 10 while you 
are off line is a valuable feature.

Having access to the admin guides for multiple versions of fedora on 
your desktop is a valuable feature, particularly if you have to support 
multiple versions of fedora. Like say a system administrator.

It only takes a little imagination to see how this benefits being able 
to syndicate content to the desktop. I'm surprised the fedora docs team 
aren't screaming for this feature.

>> 2) The .desktop file is handled differently than the reviewers would like

For values of like that ignore compatibility with other distros.

>> Now it seems to me, worst case we could run Publican and then package the
>> HTMLs manually.  But since Publican already does most of the heavy lifting,
>> why not simply patch Publican's work after the fact.
>>
>> To this end, I made an attempt to do the following:
>> 1) Unpack the SRPM produced by Publican, The SRPM has 2 files, a tarball and
>> a specfile
>> 2) Rename the tarball, which involves untarring and retarring it
>> 3) Edit the specfile
>> 4) rpmbuild
> 
> Publican also has a 'make tar-<LANG>' target for making just the tarball.

If you run make spec-<LANG> it will make the spec and the tar.

BTW fedora packaging requires you to check TAR files in to CVS to get 
them built in koji, the srpm is just used for package review, after that 
you have to check the spec and tar file in to CVS, tag it and build it 
in koji. Much of the benefit of getting a source rpm is lost at that 
point. If you can't get a number in a package name I seriously doubt you 
will be allowed to push source rpms in to koji.

>> I wrote down the details of what I did at
>> https://fedoraproject.org/wiki/User:Jjmcd/Drafts/Converting_Publican_RPM_for_Fedora

I thought this was pretty neat, but it's probably easier just to run 
make spec and use the sources in tmp/rpm.

>> When I do this, the resulting RPM passes rpmlint, installs correctly, and
>> seems to meet the guidelines.  What am I missing?  Well, appears to install
>> correctly.  A menu entry appears and when I click on it I see release notes.
>> Maybe there are less obvious things going on.
>>
>> As far as the .desktop file, I don't fully understand the issue here.  The
>> code produced by Publican appears to be almost identical to that in the
>> packaging guidelines on the wiki and very similar to what it is in the
>> current release notes.  David Nally tells me of an entirely different way to
>> deal with the .desktop file but I don't know enough to understand why it is
>> better.
>>
>> So what I'm asking is:
>> 1) Is this totally wrong-headed and we should be looking up another avenue
>> 2) How can this approach be made better
>> 3) Is there some other way
> 
> It might be helpful to have David or someone to describe the exact
> issue with the .desktop file here, or just point us to a bug where we
> can read about it.  I'm looking at Publican to see whether we could
> add the needed stuff to /usr/share/publican/make/Makefile.fedora,
> which would keep it in the Fedora brand package and away from where it
> breaks other things that Red Hat might use internally.

It would mean other brands being used on fedora wouldn't be usable for 
fedora packages.

> If that ends up being a bad place to put things -- because the
> Makefile.templates haven't been included yet at that point, perhaps --
> then it would seem relatively easy to also have the Makefile.common
> provide:
> 
>   ifeq "$(BRAND_MAKE)" "1"
>   include $(COMMON_CONFIG)/make/Makefile.$(BRAND).post
>   endif
> 
> After the global templates, and we can craft those targets as needed.
> I'm not completely Makefile-ignorant, fortunately, after having spent
> some time working on our FDP toolchain.  I'll try to help where I
> can.  If Jeff's willing to take a patch like that, or if he can help
> me understand where's a better place to put these sorts of
> customizations, I'm up for writing them.  We really do not want to
> have to punt this again for lack of elbow grease.
> 

We use the double colon for targets, e.g. foo::, so you can't over ride 
them, you can only add pre/post processing to them. You could add new 
targets that depend on old targets or just cut, paste and rename 
existing templates,  then change the behaviour.

Really though, by doing this you are removing what is, IMHO, the biggest 
value-add of packaging the docs in the first place, the ability to have 
a library of content at your fingertips. Huge price to pay just to get 
rid of a number.

Cheers, Jeff.