Docs packaging

[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 at redhat.com>
OS Product Documentation
Engineering, Red Hat, Inc.       <http://www.redhat.com>
Tel: 919.754.4151                Fax: 919.754.3708
GPG fp: DBEA FA3C C46A 70B5 F120  568B 89D5 4F61 C07D E242