Re: General GNOME User docs

[Dan Mueth <d-mueth uchicago edu>]

On Thu, 31 Aug 2000, Telsa Gwynne wrote:

> On Wed, Aug 30, 2000 at 07:05:57PM -0700 or thereabouts, Gregory Leblanc wrote:
> > > On Wed, Aug 30, 2000 at 09:02:52PM -0400, Alexander Kirillov wrote:
> > 
> > > > Finally: I'd like to include my pet project,  "If you are new to
> > > > Linux.." doc (which was an appendix to UG in 1.2) in the new
> > > > documentation package as well - if people think it is worth it. My
> > > > wife seems to appreciate this kind of "newbies" documentation. 
> [snip response]
> > 
> > I have some political objections to this.  Linux is NOT the only OS that
> > GNOME runs on.  Right this instant, it's probably bigger than all of the
> > others combined, but shipping GNOME with Solaris et al has the potential to
> > change that.  I doubt that anything else will weight in as heavily as Linux,
> > but they can certainly make it so that Linux has less than 50% of the GNOME
> > desktops.  I think we should leave this up to the people who actually
> > distribute GNOME, so that they can include one that's specific for their
> > operating environment.  SGI can include one for IRIX, Sun one for Solaris,
> > Debian one for Debian, RedHat one for RedHat.  Comments?
> 
> Greg has a very good point here. And commands work differently enough
> that a Linux-only document could do bad things if, say, you describe
> 'killall' in Linux terms and a Solaris user sees it and tries it :)
> 
> There are ways to include it in a tarball but not to include it in
> the building unless it's specifically asked for, aren't there? Isn't
> that the kind of thing ./configure can check for?

I think everybody agrees that we want to have some general documents which
appear at the top of the Contents List in the help browser(Nautilus).  This 
list will contain things like:
  Introduction to GNOME
  The GNOME User's Guide (possibly)
  The [insert Linux distro name] Linux User's Guide
	(or The Solaris User's Guide, or ...HPUX... or ....)
  (others?)

This is a rough list, but the idea is that general docs will appear at the
top of the Contents List, and which docs appear will depend upon the
GNOME distribution and Linux/Unix distribution.  There are two issues:
1) Which docs go in which packages?
2) How do we choose which ones go at the top of the Contents List

#2 should be easy - We will have a configuration file in Nautilus which
will allow whoever distributes it (eg. Linux/Unix dist. vendor or Helix or
Eazel) to set the default docs which appear at the top.  The sys admin can
go in and change this of course.  Thus, we should not have a problem with
showing the wrong docs at the top of the Contents List.

For #1: Suppose we write a "Linux Basics" doc and include it
in gnome-user-docs. I believe we can use autoconf magic as Telsa suggests
to guarantee that it is only installed for Linux systems.  The only
problem with this is that the tarball could potentially contain docs which
don't get installed, leading to larger tarballs then necessary.  I don't
know if this is really a big problem at this time.  People getting
binaries won't have any penalty at all, and a slightly larger tarball
won't kill anybody.  If it gets too large, we can always do something like
gnome-user-docs-extra-linux and gnome-user-docs-extra-solaris.

BTW - I think one or two people have mentioned to me in the past that they
were considering writing introductory Linux docs. (Sasha and Kevin?) Who
is planning on working on this? Has anybody started? Are these docs listed
in the DocTable?  It sounds like lots of people think this is important
but people have somewhat different ideas how it should be done. It might
be helpful to post an outline to the mailing list for feedback.

Dan