Re: Making GNOME documentation suitable for different distros.

[Pat Costello <Patrick Costello Sun COM>]

Thanks all for your thoughts about how to include distro-variable information in GNOME documentation. The concept of a common file is certainly appealing, and I would definitely be interested in seeing this idea in practise. There are other common files, such as the legal.xml file that currently accompanies every manual, that could benefit from such an approach. 

Getting back to the topic of starting applications, there are other considerations for the location of the application startup information. We in the Sun team still think that the best thing to do is to put that information into the user guide. That is not to say that we shouldn't use the common file approach as well, however, only that putting the startup information in the user guide has user benefits, and provides at least a short-term fix to the distro-variability issue. 

Reasons for the application startup information to go in the user guide: 

- Starting an application is a Desktop-level activity, not an application-level activity. Users need to find information about how to start applications independently of the applications. The user guide is the best place for Desktop level actions.

- Providing the startup information within the application, as we do now, does not achieve the objective of Help. By the time users find the information, within the application, they have already discovered how to start the application.

- Providing users with a comprehensive list of all application startups means that they have a quick way of finding out how to open all applications. 

Pat

Malcolm Tredinnick wrote:
> 
> On Sat, 2003-10-18 at 02:43, Shaun McCance wrote:
> > On Thu, 2003-10-16 at 22:54, Malcolm Tredinnick wrote:
> > > On Thu, 2003-10-16 at 20:12, Shaun McCance wrote:
> > > [...]
> > > > I don't see any awkwardness with using XInclude.  XIncluded files can
> > > > XInclude other files.  Files included with a SYSTEM entity can't contain
> > > > an XML declaration or a DOCTYPE declaration, because it's a just a text
> > > > slurp.  Since all of the GNOME docs currently use entites to split the
> > > > docs into smaller files, each file would have to rely on being included
> > > > in the master file to have the entity declarations.  This makes it hard
> > > > to work with each file on its own.
> > >
> > > In case it looked like I missed a point: you already have include the
> > > sub-document into the master to do any validation or processing unless
> > > you are writing very simplistic documents that do not use any entities
> > > at all. So no quotation marks (“ and ”), no em- or
> > > en-dashes, etc. I'm not adding to the ridiculousness of the situation in
> > > any way -- it's already awkward at that point. That is exactly why
> > > XInclude is a good idea for document fragments.
> >
> > Right.  And I'd like to get away from this.  Actually, I would have far
> > less of an objection to the use of entities for simple substitutions if
> > we were using XInclude for the document inclusions.  If that were the
> > case, each XML file could define the entities itself (or, of course,
> > pull them from a common entities file), and could be processed alone.
> 
> I agree completely. :-)
> 
> Malcolm
> 
> _______________________________________________
> gnome-doc-list mailing list
> gnome-doc-list gnome org
> http://mail.gnome.org/mailman/listinfo/gnome-doc-list

-- 
*************************************
Patrick Costello, GNOME Documentation
Phone: 		01 819 9077 [ext 19077]
*************************************