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

[Malcolm Tredinnick <malcolm commsecure com au>]

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.

Cheers,
Malcolm