Do we need a documentation application?

[John J. McDonough]

On Sun, 2011-04-03 at 12:40 -0400, Eric H. Christensen wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA256
> 
> On Sun, Apr 03, 2011 at 11:09:29AM -0400, John J. McDonough wrote:
> > In GNOME 3 the whole concept of menus is gone.  This means, among other
> > things, that there is no Documentation menu.  There are a number of
> > categories:
> > 
> >   Accessories
> >   Games
> >   Graphics
> >   Internet
> >   Office
> >   Others
> >   Sound & Video
> >   System Tools
> 
> Are these coming from the standards from the opendesktop group?

It is my understanding that these come from a new standard, but I
haven't studied it.  These are the same categories we used to have on
the Applications menu.
> 
> > 
> > There is also an 'All' category, but this only includes applications
> > that are in one of the other categories.  An application must be
> > specifically placed in the 'Other' category to appear there.
> 
> That doesn't seem to be extremely helpful...
> 
> > 
> > I could see putting the Release Notes in "System Tools", but it doesn't
> > seem to me that documentation in general belongs there.  Yelp is in
> > "Accessories", but that category is already cluttered, and I can see
> > "System Tools" getting pretty cluttered, too.
> 
> I'd create a Documentation category before putting the RNs (and other docs) in with programs.

I don't know what is involved in creating a Documentation category.  I
got the impression from Shaun that it wasn't going to happen upstream,
but that the Fedora maintainer might be able to do that for us.  But
given the ergonomics, I suspect you need to be pretty stingy with new
categories, so what about Education, Electronics, Astronomy, other
categories that have shown up from time to time?

I'm guessing that since Chitlesh has gone over to the dark side that
this spells the end of the Fedora Electronic Lab.

> 
> > 
> > To further complicate the matter, previously GNOME, XFCE and LXDE could
> > all share a .desktop file.  It looks as if now a unique file will be
> > required for GNOME.
> 
> This seems less than useful.  Why the break in the standard .desktop file?

The old .desktop files still work for XFCE and LXDE.  It is only on
GNOME where it is a problem.

> 
> > 
> > Were we to have some sort of Documentation application we could then
> > have something like update-desktop-database that would run on install.
> > This would allow us to have single-language RPMs and still maintain
> > consistent Fedora-like language behavior.  I can't say I'm really
> > thrilled with this, but it is an alternative.
> > 
> > Another alternative would be to go back to installing a separate set of
> > documentation for Yelp, and let it deal with all the GNOME weirdness.
> > Or, perhaps we can press shaunm to get Yelp working smoothly for html
> > documentation.  I have to admit I haven't played much with Yelp on
> > Fedora 15, and I know there has been substantial work done.
> 
> Oh boy...  An application and going back to the way we used to do it seems to be not the way forward, IMO.  I feel as if Docs won't have much of a presence on F15 with all the changes forthcoming.  Perhaps we'll have our act together by F16.

Well, yeah.  But if you think about it, in a perfect world we would have
basically docs.fp.o locally.  With some app that could incrementally
update Publican's database on install, we could have all that we have
now, and most of what we were wishing for.  Seems like most of the
required logic is already in Publican, it just needs to be packaged in a
smaller bite for install.

As far as the Yelp choice, well, that used to be a pretty nice way to
deliver docs.  The problem is that it doesn't play well with KDE, and
since the source isn't html, it meant shipping double content.

KDE agreed with GNOME on a documentation standard, but development
hasn't gotten there yet.  khelpcenter is a kind of a cool thing, and if
we could get our docs in to yelp and khelpcenter without shipping double
files that would be an ideal situation.

Of course, talking about this makes me wonder whether we might not ship
separate KDE and GNOME RPMs.  That isn't perfect, but it might be a
decent approach.  And I don't see me getting the RNs into khelpcenter
for F15.  Yelp is less of a problem because we have some history.
> 
> What work is required for building, and pushing, a Documentation category?  How will the documentation be rendered?

I assumed the rendering would be the same as today.  It is the category
that I have no idea what causes it and whether it could be either
shipped with Fedora by default or added incrementally.

--McD