Re: Need explanations for edits to docs

["J.H.M. Dassen (Ray)" <fsmla xinara org>]

On Sat, Nov 10, 2007 at 12:27:58 +0100, Adrian Custer wrote:
> I see you have once again bumped the DTD version to 4.3 and removed the
> commented blocks with the other versions. I had reverted this change way
> back in revision 12948 so I'm puzzled to see your change re-appear with
> no explanatory comment:

I'm afraid I don't follow. Looking at
        http://svn.gnome.org/viewvc/gnumeric/trunk/doc/C/gnumeric.xml?annotate=15953
the change to 4.3 is from revision 12641 (over three years ago). Perhaps
it's not so much a re-appearance than a reversal which wasn't actually
committed?

>         Are we sure that builds will not break if someone does not have
>         this particular version of the DTD?

I've seen no reports of problems resulting from this version change. I'm a
bit hazy on the details, but IIRC, most builds nowadays don't process the
xml files in any way; they're just installed and yelp/gnome-help reads
directly.

>         Is this bump required for a particular section or merely because
>         newer is generally preferable?

Digging in the changelog:
2004-10-04  J.H.M. Dassen (Ray) <jdassen debian org>

        * gnumeric.xml: Upgrade to DocBook XML V4.3 which is the first version
        to support the "uri" element we use in bugs.xml and morehelp.xml .

> You did a lot of replacing <application>Gnumeric</application> by &gnum;
> but I had come to the opposite conclusion, that &gnum; should be
> deprecated in favour of readability.

I preferred the element as it would make it easier to implement a consistent
rendering, should we want to use a particular font or font effect (say,
small caps) for "Gnumeric". From the readability point of view, perhaps it
would be better to have &gnumeric; instead?

> Now all the paragraphs you changed are wacky.

True; this way, diffs would remain small and readable.

> Leaving as is for now but we should reach some consensus on this.

Once we have, we can reformat and take care of the wackiness in one big
fixup.

> You changed some file names since they caused problems for your pdf
> generation tool chain. Where did you put the instructions for that tool
> chain?

I patched configure.in so that configure now has a "--enable-pdfdocs" switch
and provides a pointer to the tools when they are not found; the build
process will try to build PDF's once the switch is given and the tools are
found. If this is not sufficient documentation, please let me know what is
required.

> Can it generate pdf's reliably?

Currently, two tools are supported (sharing an upstream source:
http://dblatex.sourceforge.net/):
* dbcontext: Works reliably in my experience so far, but does not appear to
  be packaged for most platforms.
* dblatex: Is available in packaged form (at least on Debian), but exits
  with a non-zero exit code due to some errors/warnings about boxes. The
  resulting PDF is quite OK though. The non-zero exit code makes it
  difficult to distinguish between a genuine failure to build the PDF and a
  successful build which offends LaTeX's sensibilities.

I've looked at a third way (pdfjadetex) but was not able to get that to work
in a reliable/automated fashion.

> Do those get posted somewhere?

Not on a structural basis currently. They're not included in the tarball due
to their size, but we may at some point decide to make them available on a
structural basis as PDF is the preferred documentation format on some
platforms (AFAIK, Mac-OS X).

An example of the PDF rendering (using dbcontext) is available at
        http://www.xinara.org/~ray/tmp/gnumeric.pdf

HTH,
Ray
-- 
What is this talk of software 'releases'? Klingons do not 'release'
software; our software ESCAPES, leaving a bloody trail of designers and
quality assurance people in its wake!