Bug 170847 - Add Fedora documentation in yelp
Add Fedora documentation in yelp
Status: CLOSED RAWHIDE
Product: Fedora
Classification: Fedora
Component: fedora-docs (Show other bugs)
rawhide
All Linux
medium Severity medium
: ---
: ---
Assigned To: Ray Strode [halfline]
:
Depends On:
Blocks: FC5Target 170813
  Show dependency treegraph
 
Reported: 2005-10-14 15:09 EDT by Matthias Clasen
Modified: 2013-01-09 22:39 EST (History)
4 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2006-03-08 16:16:31 EST
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)
OMF file used in FDP example package (962 bytes, text/plain)
2005-10-17 15:50 EDT, Paul W. Frields
no flags Details

  None (edit)
Description Matthias Clasen 2005-10-14 15:09:46 EDT
Do it like Ubuntu, have

About Fedora
Fedora User Guide

maybe also release notes, etc, on the first page (provided such documentation
exists...) Also see the related bug 170813
Comment 1 Matthias Clasen 2005-10-17 15:05:22 EDT
Yelp now includes documents on the front page which are registered with
scrollkeeper in the category General|Linux|Distributions|Other

What remains to be done here is to register a suitable set of Fedora
documents in that category.
Comment 2 Paul W. Frields 2005-10-17 15:49:36 EDT
When I use that category, our document (a test) is only entered under "Other
Documentation," not listed on the front page.  (The RPM does call
scrollkeeper-update during %post.)  I am attaching the OMF so wiser eyes can
make sure I'm not doing anything boneheaded.
Comment 3 Paul W. Frields 2005-10-17 15:50:36 EDT
Created attachment 120076 [details]
OMF file used in FDP example package
Comment 4 Paul W. Frields 2005-10-17 15:51:59 EDT
Please excuse comments #2 and #3.  Matthias posted to fedora-docs-list that this
has just been patched, and his post and my comments passed each other over the
wire.  I will try Rawhide and report results. :-)
Comment 5 Matthias Clasen 2005-10-17 15:56:19 EDT
Should work with 2.12.1-3 
Comment 6 Karsten Wade 2005-10-19 20:19:30 EDT
David Malcolm wrote:

> Would it be useful for this mailing list to come up with a scheme for
> what ought to be displayed on the front page of Yelp, and we can take it
> from there?

Heck yes.  Yelp is definitely within FDP's purview.  We've been discussing these
ideas for some months, and are mighty, might glad to have your attention.

How do/can these ideas travel upstream?
Comment 7 Matthias Clasen 2005-10-19 22:51:18 EDT
If you mean yelp upstream, there is not much that needs to travel, unless I
misunderstand what you want to travel. Yelp already comes with an xml file that
defines the toc tree structure (/usr/share/yelp/toc.xml) and another xml file
that defines the mapping from omf categories to the nodes in the toc tree
(/usr/share/yelp/scrollkeeper.xml). The only change I did wrt to upstream was to
map the omf category General|Linux|Distributions|Other to the root node of the 
toc tree (ie to the front page). 

This is the same change Ubuntu does to get its distro-specific documentation in
the yelp frontpage, btw.

Comment 8 Matthias Clasen 2005-11-08 09:01:36 EST
Status update:

We have a small "About Fedora" page now, the release notes are also linked,
other than that, we are just waiting for content from the docs team now,
Comment 9 Paul W. Frields 2006-01-27 13:24:29 EST
The General|Linux|Distributions|Other patch appears to be no longer working in
current Rawhide yelp (2.13.3-1).  Any chance someone could look at this?  We
almost have our package building infrastructure finished and would like to get
*something* out in FE by FC5t3 if possible.
Comment 10 Matthias Clasen 2006-01-27 13:40:54 EST
Hmm, still works for me. What problem are you seeing ?
Comment 11 Paul W. Frields 2006-01-27 13:55:06 EST
Um... A pernicious that I apparently created and just now figured out.  I needed
to make sure the language element was set to "C" in the OMF and not "en".  I
don't know why this changed, probably just an XSL goof when I was editing that
portion of our build process.  Thanks, and sorry for the bother.
Comment 12 Matthias Clasen 2006-01-31 13:01:35 EST
Paul, what is the status of this ? Will the necessary omf files be included in
fedora-release anytime soon ? It would be really sad to see this slip, after I
did the necessary work almost three months ago...
Comment 13 Matthias Clasen 2006-01-31 13:02:17 EST
oh, did not mean for the comment to be private...
Comment 14 Paul W. Frields 2006-02-07 16:23:45 EST
Matthias, here's an update, which may show my ignorance about procedures in Core
packaging.  So be it, I'm a lover, not a... Oh, wait a minute, I mean a writer,
not a programmer.

The FDP packaging process seems to work OK at this point, although not all
documents have been converted to the new build process.  All RPMs live under the
"fedora" namespace.  There is a fedora-doc-common package with build tools,
scripts, XSL, and so forth.  All other docs are fedora-doc-<doctitle>.  Each
plants its own OMF, khelpcenter blob, and desktop menu entries.

I think the idea was to bring these documents into Fedora Extras, because (1) we
don't want to issue new fedora-release packages for every document revision, and
(2) this allows us to push document revisions quickly and efficiently in case of
a rewrite.  I've been testing these RPMs in Rawhide and they look good.  I will
be entering our fedora-doc-common into Fedora Extras review process later this week.

Is there something else we should be doing or providing at this point?
Comment 15 Paul W. Frields 2006-02-07 16:28:27 EST
I forgot to mention... if you want to see it in action, do a CVS checkout of at
least "docs-common" and, say, "translation-quick-start-guide" from the docs CVS;
then "cd t-q-s-g", and "make rpm".
Comment 16 Matthias Clasen 2006-02-07 16:33:32 EST
Hmm, but certainly, some documentation is going to be installed by default from
a core package, no ? 

It would be good if we could at least get the "About Fedora" blurb in
fedora-release in common. 

Comment 17 Paul W. Frields 2006-02-21 18:18:55 EST
I entered "about-fedora.xml" and "about-fedora.omf" into release-notes last week
and am hopeful that the fedora-release maintainers will see fit to include them
in the packge.  I tried to include an appropriate .menu file but had problems
getting the "About Fedora" link to appear next to "About GNOME" where it is wanted.
Comment 18 Jeremy Katz 2006-02-22 15:37:28 EST
If you let me know what files need to be included and where they currently are
in CVS, I can ensure they end up in the fedora-release package.
Comment 19 Matthias Clasen 2006-03-01 09:49:53 EST
any progress here ? Paul, can you answer Jeremys question ?
Comment 20 Paul W. Frields 2006-03-01 10:02:57 EST
Sorry Matthias, I replied via mail to Jeremy about a week ago, and forgot to
post a blurb here, or cc you -- no slight intended, I assure you.  As I told
Jeremy, the release-notes module now contains these files, "about-fedora.xml"
and "about-fedora.omf".  The only thing I have to leave up to him (because of my
lack of menu-fu) is getting a nice link in the "System" menu next to "About GNOME".
Comment 21 Matthias Clasen 2006-03-01 21:59:39 EST
we will take care of the menu thing as soon as about-fedora.xml appears in an rpm
in rawhide.
Comment 22 Paul W. Frields 2006-03-02 07:36:06 EST
I'm bringing Jeremy in on the CC list to remind him to grab those files from
release-notes in Docs CVS, for fedora-release.
Comment 23 Jeremy Katz 2006-03-02 15:15:00 EST
Okay, building a new fedora-release before we're really ready to spin it is
going to be kind of sucky.

Matthias -- where do the files (about-fedora.{xml,omf}) need to land?  I can
give you what's there (or you can check it out yourself) and manually put the
files in the right place and then when we actually have release notes and are
spinning fedora-release, we can do it right.
Comment 24 Paul W. Frields 2006-03-02 19:27:36 EST
If Matthias doesn't mind me pitching in --

/usr/share/omf/fedora-release/about-fedora.omf  -- this is the proper place for
OMF so it's automatically picked up when you add the following to the
fedora-release spec:

--- snip ---
%post
/usr/sbin/scrollkeeper-update || true

%postun
/usr/sbin/scrollkeeper-update || true
--- snip ---

My idea for the XML was /usr/share/doc/fedora-release-5/about/C/about-fedora.xml
-- but whatever location we choose, it MUST appear correctly in the "url"
attribute of the OMF's "identifier" element.
Comment 25 Jeremy Katz 2006-03-08 16:16:31 EST
Okay, have this working for fedora-release-5-1.noarch.rpm

Note You need to log in before you can comment on or make changes to this bug.