Re: Making GNOME documentation suitable for different distros.

[Malcolm Tredinnick <malcolm commsecure com au>]

Trimming replies to just gnome-doc-list, since it is silly to have this
on so many lists when it is just documentation focused.

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.

OK, so maybe I need to explain what I was proposing in a different way,
because you have just made the argument for XInlclude as a general
technology, rather than as it applies in this situation. Apologies if my
original explanation was not clear enough.

To avoid having to change the master document in order to alter the
value of the relevant entities, you can put all of the entities into a
single file, that file only consists of

<!ENTITY filemenuitem "<menuitem>File</menuitem>">

lines (lots of them, named appropriately). Pretend this file is called
paths.ent. (By the way, note how simple creating this file format is
from something like a whitespace-delimited list.)

Then the major file has

<!DOCTYPE article PUBLIC ..... http://..... [
<!ENTITY % paths SYSTEM "paths.ent">
%paths;
]>

and so only the paths.ent file ever needs changing to accomodate the
variations we are talking about here.

This has nothing to with using entities as a means of including other
files into the main document. I agree that that is a case where XInclude
is the better technology. This is a case where simply adding something
into the internal subset solves the problem -- much like putting common
constants into a C header file and using #include to pull them in
wherever needed.

James' argument has some merit, but I cannot think of a case in GNOME
documentation where it applies. I have also never stumbled across it in
practice, but that is probably just a limited experience issue. It
applies more to the "including whole files via entities" situation,
which *is* a case where I think XInclude should be used.

> 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.

No, I (respectfully) disagree. Having written the guts of such a tool,
it was not too hard to work with parsed-entity files -- at least, no
harder than working intelligently with XIncluded files or files that are
include via entities, which are the other two main ways that external
files are accessed. You just need to pay attention to the differences
between reading the internal and external subsets during parsing. Any
tool that is meant to handle XML <--> PO for translation purposes
absolutely has to be able to handle this (it kind of comes with the
promise to "be able to handle XML documents"). Writing something that
forces the written XML to be restricted in some fashion is unfair to
authors. That is one of the problems with the KDE tool.

Also, things like menu items and file paths need to be extracted out in
a good XML <-> PO tool in any case -- they are common elements that
should only be translated once and then markers put in there place when
they appear inline (and implementing this bit is *hard* compared to the
previous paragraph).

> 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.

This is indeed one of the problems. That is why I was saying that the
XInclude methods end up being inappropriate in this situation. There's a
lot of overhead for something that can be done in a straightforward
fashion.

In the method I am discussing, the correctness of the entity file
(paths.ent) is determined in the context of the file(s) you are
including it into. Standalone validation doesn't really work for a bunch
of little strings like this.

> 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.

*shrug* Your experiences do not seem that limited, as evidenced by your
other work. :-)

My limited opinion is that XInclude methods scale pretty well. I'm sure
it's possible to use XInclude in some evil fashion, but why would
somebody do that? I write a lot of documentation at work (almost
everybody here ends up wearing multiple hats which includes writing
client documentation as well as programming). We have found that the
above method works well for documents that need small pieces to be
customised. XIncludes work very well for document fragments or entire
sub-documents that need including into larger collections.

OK, my contribution is done now. I just thought I would offer up an
approach that I know works in practice for large and fairly complicated
documents.

Cheers,
Malcolm