Docs packaging

[Paul W. Frields]

I want to take a stab at packaging at least a few of the biggie Fedora
docs for FC5.  Some of these thoughts below:

* Since docs are not absolutely necessary to run a system, Extras seems
like the right place to me.  Putting Fedora on a diet was discussed
endlessly before and after FC4, so I'm not sure we can make a great case
for getting docs into Core.  Nor should we really bother -- Extras is
not a second-class citizen or a myth, it's a living, breathing, vital
repository where we can be proud to have our documentation.  Plus,
putting it in Extras means it can stay fresh, which is absolutely
important to this project.  (I have Extras membership, as do some of our
other contributors, and can easily find someone to review the package
for inclusion.  In fact, any of you could do it, and probably should, to
speed the process up.)

* Packages will consist of HTML.  The XML will be in the .src.rpm as
expected.  Building to be done via the buildsys/plague per normal
routine, unless someone has a better idea that doesn't require a lot of
manual intervention.  We don't really need our own buildsys, since the
docs packages would live in Extras anyway.

* As far as the process goes, I see it as snapshotting the CVS for
SOURCES stuff, updating Extras CVS with the results, and do a build
request on normal channels.  Package versioning is done from the CVS
date, per Fedora Extras guidelines.  The resulting packages can be
linked from the f.r.c/docs/* pages alongside any tarballs.

* I am not keen on a single docs package, because updates should be
available on a rolling schedule in very small pieces.  Some documents
require large files bundled in the package; an example is the
Installation Guide, which has a few MB worth of screen shots.  Users
should not be required to download that amount of material just to get a
new release of foo-tutorial.  A better organization would be:

  * fedora-docs-common: Anything used by all the docs, such as CSS;
probably to be installed in %{_docdir}/fedora-docs/
  * fedora-install-guide: self-explanatory, sits in
%{_docdir}/fedora-docs/install-guide/
  * fedora-documentation-guide: ...and so forth...

Note that these are not subpackages, so that their version information
can move independently and track the revision history in each doc if
need be.  This is especially important with the canonical guides,
although I could see using CVS dating (i.e. M.m-R.YYYYMMDDcvs) as well.
My preference would be to keep it simple if possible.

* I would like the /usr/share/doc/HTML/index.html file (which is part of
fedora-release, and comes up when people launch Firefox) to show a SHORT
and informative menu on how to:

  * Read the release notes
  * Install and update software, in particular Fedora docs
    (i.e. "yum install fedora-docs\*" plus link to Stuart's yum doc)
  * Access fedoraproject.org, especially the Wiki
  * Get involved in Fedora (probably also through fp.org)

This menu should simply be incorporated at the top of the release notes
to minimize clicking around for new users as well as the work required
to get it in under deadline.


I'm sure everyone can come up with additional thoughts -- I am trying to
jot all this down quickly, so I've likely forgotten important things.
Have at it, please!

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/

[Rahul Sundaram]

Hi

> I'm sure everyone can come up with additional thoughts -- I am
> trying to
> jot all this down quickly, so I've likely forgotten important things.
> Have at it, please!
>   
>  
Yum uses package groups instead of dummy packages extensively to take 
care of users who want to install all the relevant documentation in a 
single step . So while contributing new packages to the Extras 
repository, make sure that we have a group called say "Fedora  Docs", so 
I can do

#yum groupinstall "Fedora Docs"



regards
Rahul

[Paul W. Frields]

On Wed, 2005-08-24 at 03:38 +0530, Rahul Sundaram wrote:
>  Hi
>  
>  >I'm sure everyone can come up with additional thoughts -- I am trying to
>  >jot all this down quickly, so I've likely forgotten important things.
>  >Have at it, please!
>  >  
>  >
>  Yum uses package groups instead of dummy packages extensively to take 
>  care of users who want to install all the relevant documentation in a 
>  single step . So while contributing new packages to the Extras 
>  repository, make sure that we have a group called say "Fedora  Docs", so 
>  I can do
>  
>  #yum groupinstall "Fedora Docs" 
Excellent point! Can groups be defined in Extras and not Core?

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/

[Rahul Sundaram]

Paul W. Frields wrote:

> On Wed, 2005-08-24 at 03:38 +0530, Rahul Sundaram wrote:
>   
>
> >Hi
> >
> >    
> >
> >>I'm sure everyone can come up with additional thoughts -- I am trying to
> >>jot all this down quickly, so I've likely forgotten important things.
> >>Have at it, please!
> >> 
> >>
> >>      
> >>
> >Yum uses package groups instead of dummy packages extensively to take 
> >care of users who want to install all the relevant documentation in a 
> >single step . So while contributing new packages to the Extras 
> >repository, make sure that we have a group called say "Fedora  Docs", so 
> >I can do
> >
> >#yum groupinstall "Fedora Docs"
> >    
> >
>
> Excellent point! Can groups be defined in Extras and not Core?
>
>   
>  
Yes.  It can be. Defining package groups for extras is even part of the 
agenda.

http://fedoraproject.org/wiki/FC5Future

regards
Rahul

[Karsten Wade]

On Wed, 2005-08-24 at 03:38 +0530, Rahul Sundaram wrote:
>  Hi
>  
>  >I'm sure everyone can come up with additional thoughts -- I am trying to
>  >jot all this down quickly, so I've likely forgotten important things.
>  >Have at it, please!
>  >  
>  >
>  Yum uses package groups instead of dummy packages extensively to take 
>  care of users who want to install all the relevant documentation in a 
>  single step . So while contributing new packages to the Extras 
>  repository, make sure that we have a group called say "Fedora  Docs", so 
>  I can do
>  
>  #yum groupinstall "Fedora Docs" 
Please make it the "Fedora Documentation" group instead.

-- 
Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/
gpg fingerprint:  2680 DBFD D968 3141 0115    5F1B D992 0E06 AD0E 0C41   
                       Red Hat SELinux Guide
http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/

[David Malcolm]

On Tue, 2005-08-23 at 17:56 -0400, Paul W. Frields wrote:
>  I want to take a stab at packaging at least a few of the biggie
> Fedora
>  docs for FC5.  Some of these thoughts below: 
[snip]

>  
>  * Packages will consist of HTML.  The XML will be in the .src.rpm as
>  expected.  Building to be done via the buildsys/plague per normal
>  routine, unless someone has a better idea that doesn't require a lot of
>  manual intervention.  We don't really need our own buildsys, since the
>  docs packages would live in Extras anyway. 
Can we ship the XML (perhaps as well) and have the documentation
readable in Yelp?  It would be great to have the installed Fedora docs
appear when clicking on the desktop's "Help" menu item.

[snip]

[Stuart Ellis]

On Tue, 2005-08-23 at 18:15 -0400, David Malcolm wrote:
>  On Tue, 2005-08-23 at 17:56 -0400, Paul W. Frields wrote:
>  > I want to take a stab at packaging at least a few of the biggie Fedora
>  > docs for FC5.  Some of these thoughts below:
>  
>  [snip]
>  
>  > 
>  > * Packages will consist of HTML.  The XML will be in the .src.rpm as
>  > expected.  Building to be done via the buildsys/plague per normal
>  > routine, unless someone has a better idea that doesn't require a lot of
>  > manual intervention.  We don't really need our own buildsys, since the
>  > docs packages would live in Extras anyway.
>  
>  Can we ship the XML (perhaps as well) and have the documentation
>  readable in Yelp?  It would be great to have the installed Fedora docs
>  appear when clicking on the desktop's "Help" menu item. 
The XML files for the existing documents are actually pretty small:

Installation Guide: 114k
Yum tutorial: 58k

So if each document is in a separate package I don't think that it would
add much to the size.

The IG ends up being large, but that's just all the PNG files.

-- 

Stuart Ellis

stuart(a)elsn.org

Fedora Documentation Project: http://fedora.redhat.com/projects/docs/

GPG key ID: 7098ABEA
GPG key fingerprint: 68B0 E291 FB19 C845 E60E  9569 292E E365 7098 ABEA

[Rahul Sundaram]

Hi

> >Can we ship the XML (perhaps as well) and have the documentation
> >readable in Yelp?  It would be great to have the installed Fedora docs
> >appear when clicking on the desktop's "Help" menu item.
> >    
> > 
How about KDE users. I wouldnt be pleased if I was one and wanted to 
install documentation and end up installing yelp etc as dependencies

regards
Rahul

[Peter Boy]

Am Dienstag, den 23.08.2005, 18:15 -0400 schrieb David Malcolm:
>  Can we ship the XML (perhaps as well) and have the documentation
>  readable in Yelp?  It would be great to have the installed Fedora docs
>  appear when clicking on the desktop's "Help" menu item. 
This feature should become a central goal. Currently the help button is
of quite limited use if you want to learn something about Fedora
specific topics. It is in it's current incarnation even of very limited
use as a starting point and quick access help to reach the available
information most installed programs deliver in /usr/share/docs.

But this intention may conflict with the intention to meet the upstream
work as much as possible?


Peter

[Rahul Sundaram]

Peter Boy wrote:

> Am Dienstag, den 23.08.2005, 18:15 -0400 schrieb David Malcolm:
>   
>
> >Can we ship the XML (perhaps as well) and have the documentation
> >readable in Yelp?  It would be great to have the installed Fedora docs
> >appear when clicking on the desktop's "Help" menu item.
> >    
> >
>
> This feature should become a central goal. Currently the help button is
> of quite limited use if you want to learn something about Fedora
> specific topics. It is in it's current incarnation even of very limited
> use as a starting point and quick access help to reach the available
> information most installed programs deliver in /usr/share/docs.
>
> But this intention may conflict with the intention to meet the upstream
> work as much as possible?
>
>
> Peter
>   
>  
If there are good reasons to deviate from upstream in a preferably non 
intrusive fashion, we can request that. The idea to stick close to 
upstream is not a iron clad rule. Its a general guideline. Since Fedora 
releases are not in sync with all of the several different upstream 
projects, many of the packages would end up carrying bug fixes that 
havent been upstreamed yet. So we should carefully evaluate the cost of 
maintaining a patch vs the advantage of doing so everytime we deviate 
from upstream packages

In this if the underlying help system itself is DE neutral in such a way 
that the same documents show up in any DE/WM that we ship in core, its 
reasonable to provide a patch for that system to show the Fedora 
documentation too but as long core includes both GNOME and KDE, adding a 
dependency to yelp for the documentation packages looks unreasonable to me

regards
Rahul

[David Malcolm]

On Wed, 2005-08-24 at 04:49 +0530, Rahul Sundaram wrote:
>  Peter Boy wrote:
>  
>  >Am Dienstag, den 23.08.2005, 18:15 -0400 schrieb David Malcolm:
>  >  
>  >
>  >>Can we ship the XML (perhaps as well) and have the documentation
>  >>readable in Yelp?  It would be great to have the installed Fedora docs
>  >>appear when clicking on the desktop's "Help" menu item.
>  >>    
>  >>
>  >
>  >This feature should become a central goal. Currently the help button is
>  >of quite limited use if you want to learn something about Fedora
>  >specific topics. It is in it's current incarnation even of very limited
>  >use as a starting point and quick access help to reach the available
>  >information most installed programs deliver in /usr/share/docs.
>  >
>  >But this intention may conflict with the intention to meet the upstream
>  >work as much as possible?
>  >
>  >
>  >Peter
>  >  
>  >
>  If there are good reasons to deviate from upstream in a preferably non 
>  intrusive fashion, we can request that. The idea to stick close to 
>  upstream is not a iron clad rule. Its a general guideline. Since Fedora 
>  releases are not in sync with all of the several different upstream 
>  projects, many of the packages would end up carrying bug fixes that 
>  havent been upstreamed yet. So we should carefully evaluate the cost of 
>  maintaining a patch vs the advantage of doing so everytime we deviate 
>  from upstream packages
>  
>  In this if the underlying help system itself is DE neutral in such a way 
>  that the same documents show up in any DE/WM that we ship in core, its 
>  reasonable to provide a patch for that system to show the Fedora 
>  documentation too but as long core includes both GNOME and KDE, adding a 
>  dependency to yelp for the documentation packages looks unreasonable to me 
I wasn't proposing adding a yelp dependency to the documentation, I was
proposing shipping the DocBook XML source of the documentation, and
whatever metadata is required (if any) to get both GNOME and KDE's help
viewers to be aware of the files.

[Rahul Sundaram]

Hi

> I wasn't proposing adding a yelp dependency to the documentation,
> I was
> proposing shipping the DocBook XML source of the documentation, and
> whatever metadata is required (if any) to get both GNOME and KDE's help
> viewers to be aware of the files.
>   
>  
Apologies for reading it incorrectly. Having it show up in both of the 
help viewers is a good enhancement.

regards
Rahul

[Karsten Wade]

On Tue, 2005-08-23 at 18:15 -0400, David Malcolm wrote:

>  Can we ship the XML (perhaps as well) and have the documentation
>  readable in Yelp?  It would be great to have the installed Fedora docs
>  appear when clicking on the desktop's "Help" menu item. 
We still want a .src.rpm, so we can include the Makefile et al.  I.e.,
the build environment and stuff is different.

Paul, can we add a designation to the package to show 'html' and 'xml',
or should we just go ahead and package the XML with the HTML?  No XSL,
naturally.

I think I like the idea of XML and HTML living in the same package, and
metadata to get help systems to find *both*.

- Karsten
-- 
Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/
gpg fingerprint:  2680 DBFD D968 3141 0115    5F1B D992 0E06 AD0E 0C41   
                       Red Hat SELinux Guide
http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/

[Paul W. Frields]

On Tue, 2005-08-23 at 16:34 -0700, Karsten Wade wrote:
>  On Tue, 2005-08-23 at 18:15 -0400, David Malcolm wrote:
>  
>  > Can we ship the XML (perhaps as well) and have the documentation
>  > readable in Yelp?  It would be great to have the installed Fedora docs
>  > appear when clicking on the desktop's "Help" menu item.
>  
>  We still want a .src.rpm, so we can include the Makefile et al.  I.e.,
>  the build environment and stuff is different.
>  
>  Paul, can we add a designation to the package to show 'html' and 'xml',
>  or should we just go ahead and package the XML with the HTML?  No XSL,
>  naturally.
>  
>  I think I like the idea of XML and HTML living in the same package, and
>  metadata to get help systems to find *both*. 
I think the yelp stuff is a GREAT idea.  I don't see any reason why it
shouldn't just all live in the same binary package for each doc, and
will address this in the package.  Install it once, get it wherever you
tend to look, whether that be %{_docdir}/HTML/*, yelp, or something else
in the future.  XML is small, compressed XML is *really* small. :-)

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/

[Peter Boy]

Am Dienstag, den 23.08.2005, 17:56 -0400 schrieb Paul W. Frields:
>  * Since docs are not absolutely necessary to run a system, Extras
> seems
>  like the right place to me.   
Hm, if there is a lack of documentation you can't use a lot of systems.
Obviously many people can use Fedora despite of a current lack of
documentation (as we see from FC1 to FC4  :-) ), nevertheless I would
vote to have the documentation in the core package (at least in the long
run).

Perhaps it is possibly to differ between several documents.

- User guide (if we would have it), yum guide, release notes, etc. 
  part of core
- program related guides bundled with the program (e.g. Samba 
  guide in the Samba devision), either in core of extra, depends
  on the programs location
- guides about broader, but special themes in extras (e.g. 
  rpm packaging guide)


>  Putting Fedora on a diet was discussed
>  endlessly before and after FC4, so I'm not sure we can make a great case
>  for getting docs into Core. 
As long as we don't have localized docs the documentation doesn't need
so much space, I suppose.

>    Nor should we really bother -- Extras is
>  not a second-class citizen or a myth,  
It isn't indeed. But may be you need some kind of documentation before
you can use it (e.g. yum guide) or even know about it.

>  * I would like the /usr/share/doc/HTML/index.html file (which is part
> of
>  fedora-release, and comes up when people launch Firefox) to show a SHORT
>  and informative menu on how to:
>  
>    * Read the release notes
>    * Install and update software, in particular Fedora docs
>      (i.e. "yum install fedora-docs\*" plus link to Stuart's yum doc)
>    * Access fedoraproject.org, especially the Wiki
>    * Get involved in Fedora (probably also through fp.org) 
Very good idea in my opinion!



Peter

[Rahul Sundaram]

Peter Boy wrote:

> Am Dienstag, den 23.08.2005, 17:56 -0400 schrieb Paul W. Frields:
>   
>
> >* Since docs are not absolutely necessary to run a system, Extras seems
> >like the right place to me.  
> >    
> >
>
> Hm, if there is a lack of documentation you can't use a lot of systems.
> Obviously many people can use Fedora despite of a current lack of
> documentation (as we see from FC1 to FC4  :-) ), nevertheless I would
> vote to have the documentation in the core package (at least in the long
> run).
>
>   
>  
Dont forget that packaging them in extras is a good first step and in 
many cases, the logical step before requesting that they be added in core

> Perhaps it is possibly to differ between several documents.
>
> - User guide (if we would have it), yum guide, release notes, etc. 
>   part of core
>   
>  
Release notes is already part of core, packaged with fedora-release rpm

> It isn't indeed. But may be you need some kind of documentation
> before
> you can use it (e.g. yum guide) or even know about it.
>   
>  
Not really. Fedora installer is getting the ability to use other 
repositories including extras soon. I presume that detail will be in the 
installation guide and users can choose to install the package along 
with anything else in core. If it gets a honourable mention in the 
release notes we are all set

regards
Rahul

[Stuart Ellis]

On Wed, 2005-08-24 at 01:03 +0200, Peter Boy wrote:

>  > Putting Fedora on a diet was discussed
>  > endlessly before and after FC4, so I'm not sure we can make a great case
>  > for getting docs into Core.
>  
>  As long as we don't have localized docs the documentation doesn't need
>  so much space, I suppose.
>  
>  >   Nor should we really bother -- Extras is
>  > not a second-class citizen or a myth, 
>  
>  It isn't indeed. But may be you need some kind of documentation before
>  you can use it (e.g. yum guide) or even know about it. 
AIUI, part of the plan for integrating yum into anaconda is that the
Extras repository will be available during the installation process.
Which also means that we will have to cover it in the next IG, I
guess :).

But this raises a interesting point - if no packages from Extras are
installed by default, then we may have to try to have packages in Core,
or the default installation for new users will have no docs.

-- 

Stuart Ellis

stuart(a)elsn.org

Fedora Documentation Project: http://fedora.redhat.com/projects/docs/

GPG key ID: 7098ABEA
GPG key fingerprint: 68B0 E291 FB19 C845 E60E  9569 292E E365 7098 ABEA

[Karsten Wade]

On Wed, 2005-08-24 at 01:03 +0200, Peter Boy wrote:
>  Am Dienstag, den 23.08.2005, 17:56 -0400 schrieb Paul W. Frields:
>  > * Since docs are not absolutely necessary to run a system, Extras seems
>  > like the right place to me.  
>  
>  Hm, if there is a lack of documentation you can't use a lot of systems.
>  Obviously many people can use Fedora despite of a current lack of
>  documentation (as we see from FC1 to FC4  :-) ), nevertheless I would
>  vote to have the documentation in the core package (at least in the long
>  run). 
Viscerally, I agree.  However, size is a problem we have to deal with,
and end-user docs with lots of screenshots are big.  And we do hope to
have translations of most of the important ones, so then everyone wants
those included.

For the record, application documentation that comes in the package and
usually ends up in /usr/share/doc/ is not part of this discussion.  We
don't own or affect that content, at least, not directly.

>  Perhaps it is possibly to differ between several documents.
>  
>  - User guide (if we would have it), yum guide, release notes, etc. 
>    part of core 
I could see rallying for this, if the package was small.  The relnotes
exist, and have grown with a screenshot and more text recently, and a
general Fedora Desktop User Guide that had many good bits within would
be quite useful.

Unfortunately, those who need such docs are usually the ones who need
more screenshots than CLI usage, and thus the size of the docs grows
hugely.

>  - program related guides bundled with the program (e.g. Samba 
>    guide in the Samba devision), either in core of extra, depends
>    on the programs location 
We would have a harder time arguing for Samba docs to be available in
Core just because Samba was.  I think these are perfect for Extras.

>  - guides about broader, but special themes in extras (e.g. 
>    rpm packaging guide) 
Yes, et al.

>  >   Nor should we really bother -- Extras is
>  > not a second-class citizen or a myth, 
>  
>  It isn't indeed. But may be you need some kind of documentation before
>  you can use it (e.g. yum guide) or even know about it. 
Aside from inclusion in Anaconda, there is definitely value in a Desktop
User Guide.  Maybe it has few screenshots and is just a master guide
that sends you to more online documentation, call it a Desktop Quick
Start Guide.  One thing it does is get you into using yum/pup.

>  > * I would like the /usr/share/doc/HTML/index.html file (which is
> part of
>  > fedora-release, and comes up when people launch Firefox) to show a SHORT
>  > and informative menu on how to:
>  > 
>  >   * Read the release notes
>  >   * Install and update software, in particular Fedora docs
>  >     (i.e. "yum install fedora-docs\*" plus link to Stuart's yum doc)
>  >   * Access fedoraproject.org, especially the Wiki
>  >   * Get involved in Fedora (probably also through fp.org)
>  
>  Very good idea in my opinion! 
Note that this content, owned by the fedora-release package, is actually
drawn from the release notes that we write.  So, we are in direct
control of this content.

Now, getting stuff about the Table of Contents is XSL-fu work that we
need to consider.

- Karsten
-- 
Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/
gpg fingerprint:  2680 DBFD D968 3141 0115    5F1B D992 0E06 AD0E 0C41   
                       Red Hat SELinux Guide
http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/

[Mark Johnson]

Karsten Wade wrote:
>  On Wed, 2005-08-24 at 01:03 +0200, Peter Boy wrote:
>  
> >Am Dienstag, den 23.08.2005, 17:56 -0400 schrieb Paul W. Frields:
> >
> >>* Since docs are not absolutely necessary to run a system, Extras seems
> >>like the right place to me.  
> >
> >Hm, if there is a lack of documentation you can't use a lot of systems.
> >Obviously many people can use Fedora despite of a current lack of
> >documentation (as we see from FC1 to FC4  :-) ), nevertheless I would
> >vote to have the documentation in the core package (at least in the long
> >run).
>  
>  
>  Viscerally, I agree.  However, size is a problem we have to deal with,
>  and end-user docs with lots of screenshots are big.  And we do hope to
>  have translations of most of the important ones, so then everyone wants
>  those included.
>  
>  For the record, application documentation that comes in the package and
>  usually ends up in /usr/share/doc/ is not part of this discussion.  We
>  don't own or affect that content, at least, not directly.
>  
>  
> >Perhaps it is possibly to differ between several documents.
> >
> >- User guide (if we would have it), yum guide, release notes, etc. 
> >  part of core
>  
>  
>  I could see rallying for this, if the package was small.  The relnotes
>  exist, and have grown with a screenshot and more text recently, and a
>  general Fedora Desktop User Guide that had many good bits within would
>  be quite useful.
>  
>  Unfortunately, those who need such docs are usually the ones who need
>  more screenshots than CLI usage, and thus the size of the docs grows
>  hugely.
>  
>  
> >- program related guides bundled with the program (e.g. Samba 
> >  guide in the Samba devision), either in core of extra, depends
> >  on the programs location
>  
>  
>  We would have a harder time arguing for Samba docs to be available in
>  Core just because Samba was.  I think these are perfect for Extras. 
Despite where they live, the docs packages could simply follow the 
debian docs package naming policy:

   Documentation for package foo is in the package foo-doc

Doing it this way eliminates the need for coordination with upstream.

> >>* I would like the /usr/share/doc/HTML/index.html file (which
> is part of
> >>fedora-release, and comes up when people launch Firefox) to show a SHORT
> >>and informative menu on how to:
> >>
> >>  * Read the release notes
> >>  * Install and update software, in particular Fedora docs
> >>    (i.e. "yum install fedora-docs\*" plus link to Stuart's yum
> doc)
> >>  * Access fedoraproject.org, especially the Wiki
> >>  * Get involved in Fedora (probably also through fp.org) 
Debian systems have a very nice setup for the /usr/share/doc/index.html 
(produced by the dhelp package and which shows up via apache as 
http://localhost/doc/HTML/index.html) as well as a number of cgi-based 
packages that allow access to all the docs that are registered (via 
packager tools) in the doc system.

The dhelp system looks like this (on some random machines):

  http://www.sosst.sk/doc/HTML
  http://nestor.wlu.ca/doc/HTML

DHelp Homepage: http://www.fifi.org/doc/HTML/


There's also the cgi-based "dwww" package (more random servers):

   http://darbujan.fzu.cz/dwww/
   http://borg.cs.bilkent.edu.tr/dwww/

Which is much more powerful - check out the links (my apologies to the 
server admins:-)


And finally, the "doc-central" package (more apologies):

   http://epoxy.mrs.umn.edu/dc/
   http://gregscomputerservice.com/dc/

which is also cgi-based and quite nice.


I dunno if such developer & user tools exist for fedora system, but 
they'd be very nice additions. (wishful thinking here)

I'd also like to second Dave Malcolm's suggestion about packaging the 
xml sources so they register in both gnome & kde help systems. (Caveat, 
I know how the yelp system works in this regard, but am completely 
ignorant of the kde doc/help registration.) I do know that it's not at 
all difficult to package xml source files so that they show up in yelp.

My $0.02...

Cheers,
Mark

-- 
----------------------------------------------------------
Mark Johnson                     <mjohnson(a)redhat.com&gt;
OS Product Documentation
Engineering, Red Hat, Inc.       <http://www.redhat.com>
Tel: [phone]                Fax: [phone]
GPG fp: DBEA FA3C C46A 70B5 F120  568B 89D5 4F61 C07D E242

[Thomas Jones]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Wednesday 24 August 2005 19:29, Mark Johnson wrote:
>  I'd also like to second Dave Malcolm's suggestion about
> packaging the
>  xml sources so they register in both gnome & kde help systems. (Caveat,
>  I know how the yelp system works in this regard, but am completely
>  ignorant of the kde doc/help registration.) I do know that it's not at
>  all difficult to package xml source files so that they show up in yelp.
>  
Introduction of content into the kde help center application is awkward at 
best.

The entire kde docbook sources are all located in ${kdedir}/share/doc/HTML/en. 
Within the root folder of each application are the docbook source, a cache of 
the generated presentation files and a symbolic link to the global files for 
all kde documentation --- aptly named "common". This is the default location 
for the content presented by the khelpcenter application.

The only difficulty I had in the whole process is generating the cache file. 
Admittedly, I had a heck of a time figuring this one out --- even with the 
help of google. HINT-HINT: Utilize the meinproc binary with the --cache 
<file> option.
;)

Introduction of the content(naming scheme, icon, etc..) into the tree view of 
the khelpcenter application is performed via a .desktop file located in the 
proper directory.  If you do not choose to place the documentation in the 
${kdedir}/share/doc/HTML/en; then a .desktop configuration file must be used 
to tell the application where the actual content is housed 
- --- /usr/share/doc/packages maybe.

Then at any time a user can access the new content from the khelpcenter 
application, through either the konqueror web browser, or via the konqueror 
file management interface. All three avenues can be quickly navigated via the 
"help" kioslave.

That's kde --- gnome --- you got me! ;)
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.2.4 (GNU/Linux)
>
> iD8DBQFDDR4UoR5cE1e/kEIRAsGFAJ4xYelK7I39LYWJ1Zys81FlgWH3CgCeKUqA
> g3DtPBa0UJ+ibzAyVF40wfs=
> =vxSx
> -----END PGP SIGNATURE-----

[Paul W. Frields]

On Wed, 2005-08-24 at 20:29 -0400, Mark Johnson wrote:
>  >>- program related guides bundled with the program (e.g. Samba
>
>  >>  guide in the Samba devision), either in core of extra, depends
>  >>  on the programs location
>  > 
>  > We would have a harder time arguing for Samba docs to be available in
>  > Core just because Samba was.  I think these are perfect for Extras.
>  
>  Despite where they live, the docs packages could simply follow the 
>  debian docs package naming policy:
>  
>     Documentation for package foo is in the package foo-doc
>  
>  Doing it this way eliminates the need for coordination with upstream. 
Unfortunately it would create conflicts in the RPM database namespace,
since some packages have their own -doc subpackages.  I think sticking
with fedora-docs-foo is probably a better idea for that reason alone.
The "foo-doc" name would also create the illusion (given RPM namespace
conventions) that the documentation was part of the original source and
not a graft by FDP.

>  >>>* I would like the /usr/share/doc/HTML/index.html file
> (which is part of
>  >>>fedora-release, and comes up when people launch Firefox) to show a SHORT
>  >>>and informative menu on how to:
>  >>>
>  >>>  * Read the release notes
>  >>>  * Install and update software, in particular Fedora docs
>  >>>    (i.e. "yum install fedora-docs\*" plus link to Stuart's yum
> doc)
>  >>>  * Access fedoraproject.org, especially the Wiki
>  >>>  * Get involved in Fedora (probably also through fp.org)
>  
>  Debian systems have a very nice setup for the /usr/share/doc/index.html 
>  (produced by the dhelp package and which shows up via apache as 
>  http://localhost/doc/HTML/index.html) as well as a number of cgi-based 
>  packages that allow access to all the docs that are registered (via 
>  packager tools) in the doc system. 
We should be able to handle this in packaging as well, between
manipulating the existing /usr/share/doc/HTML/index.html (default
browser page), scrollkeeper, and yelp.

>  I'd also like to second Dave Malcolm's suggestion about
> packaging the 
>  xml sources so they register in both gnome & kde help systems. (Caveat, 
>  I know how the yelp system works in this regard, but am completely 
>  ignorant of the kde doc/help registration.) I do know that it's not at 
>  all difficult to package xml source files so that they show up in yelp.
>  
>  My $0.02... 
I think that scrollkeeper is very much the same way; there should be a
way to more or less wrap the existing XML sources in a OMF file for
scrollkeeper.  Then GNOME help will also register the files.

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/

[Tommy Reynolds]

Uttered "Paul W. Frields" <stickster(a)gmail.com&gt;, spake thus:

>  Unfortunately it would create conflicts in the RPM database
> namespace,
>  since some packages have their own -doc subpackages.  I think sticking
>  with fedora-docs-foo is probably a better idea for that reason alone. 
To avoid filename bloat, I'd suggest just "fdp-foo.src.rpm" and so on.
Surely FDP is enough of a namespace qualifier.

[Paul W. Frields]

On Thu, 2005-08-25 at 12:05 -0500, Tommy Reynolds wrote:
>  Uttered "Paul W. Frields" <stickster(a)gmail.com&gt;,
> spake thus:
>  
>  > Unfortunately it would create conflicts in the RPM database namespace,
>  > since some packages have their own -doc subpackages.  I think sticking
>  > with fedora-docs-foo is probably a better idea for that reason alone.
>  
>  To avoid filename bloat, I'd suggest just "fdp-foo.src.rpm" and so on.
>  Surely FDP is enough of a namespace qualifier. 
The only reason I suggest the longer name is that existing
Fedora-specific packages springing directly from the Project start with
"fedora."  Sticking with that convention, unless there's a good reason
to deviate, would be helpful to some people who are tracking packages
that spring directly from the project.  Examples include fedora-release,
fedora-rpmdevtools, and fedora-logos.

Other than that, the name is pretty trivial, since most people will
probably end up installing this through Anaconda, "yum group install,"
or some such tool that otherwise obscures the name.

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/