[Usability] Re: Making GNOME documentation suitable for different distros.

[Shaun McCance <shaunm gnome org>]

On Wed, 2003-10-15 at 17:10, Malcolm Tredinnick wrote:
> On Thu, 2003-10-16 at 07:51, Shaun McCance wrote:
> > On Wed, 2003-10-15 at 11:50, Danilo Segan wrote:
> > > Дана среда, 15. октобар 2003. 18:30:12 CEST, Pat Costello написа:
> > > > The way we are planning to handle this scenario for the
> > > > manuals that the Sun team is looking after, is by putting all menu
> > > > path information in one place only. That way, the information can be
> > > > easily updated for use by different distros. In other words, you only
> > > > need to update one Help document, rather than dozens, if you want to  
> > > > make menu changes in your distro. The place where we will put the  
> > > > menu path information is in the GNOME Desktop User Guide, in a new  
> > > > section. We will replace the menu path information in the individual  
> > > > Help manuals with a reference to the User Guide.
> > > 
> > > How about using SGML/XML entities for this? I believe they're just the  
> > > right thing, and it should work for you without adding a new section,  
> > > and it would work for every document in Gnome help system, if it  
> > > includes eg. "&filerollermenupath;" or "&eogmenupath;".
> > > 
> > > I belive this is far superior for users from using a simple "see  
> > > there".
> > 
> > I think XInclude would be a cleaner and more flexible way of doing this.
> > That way all the definitions could be in a single DocBook file, and all
> > other files could use something like
> > 
> > <xi:include href="uidefs.xml#eogmenupath"/>
> 
> Why do you think this? Can you give an example of how you see this
> working when somebody just wants to replace a menu path or something? It
> seems like a lot of overhead to me when compared to the solution I
> outline below (at least, every XInclude solution I have attemped to come
> up with to this problem has been more awkward than the below for small
> replacable portions....)
> 
> I am not sure what the full range of things that need to be changed are
> (Patrick, have you guys worked out a roughly complete list?), but this
> is a problem where I think entities work better than XIncludes.
> 
> In my day job, we have exactly the same problem: user guides and
> (particularly) testing documents for various of our products are
> customised on a per-client basis; the documents themselves are in
> DocBook. We have a file for each client containing entity definitions --
> each entity must have a value appropriate for that client. Then the main
> document includes the entity file as a parameter-entity reference in the
> DOCTYPE declaration and never needs to be changed. Filling in the entity
> file for a new client is tedious but not brain surgery -- in fact, we
> generate it from a slightly more readable format using a line of sed in
> the Makefile.
> 
> Note, also, that the parameter-entity method works transparently if you
> are XIncluding other documents (i.e. it is not an either/or choice): you
> need to include the PE reference in each document's DOCTYPE, but there
> are no double-definition problems or anything.

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.

Also, with the big push for PO-based documentation translation, using
XInclude means that everything is still in simple, straight-forward XML.
With entities, we'd have to write yet another tool to use PO files with
a list of entity declarations.

A potential problem with XInclude just has to be a list of DocBook
elements, wrapped in some arbitrary parent.  This obviously isn't valid
DocBook.  If we wanted to reference the elements with a simple fragment
identifier (which I think is better than a big XPointer in this case),
then clearly we'd have to have a way to specify which attributes are of
type ID.  I suppose a simple DTD could be made that just includes the
DocBook DTD, defines the element foo, and states that foo may have any
number of anything.

Maybe I'm missing some catch.  With a lot of these technologies, you
only begin to see the problems when you start pushing them to their
limits.  I'll admit I haven't used XInclude in anything really taxing,
so if it starts to break down somewhere, I wouldn't know.

--
Shaun