Need explanations for edits to docs

[Adrian Custer <acuster gnome org>]

Hey all, with Ray and Jody in particular,

Over the past years there have been a bunch of minor edits to the docs,
some of which need explanation for me to understand their intent which
is what this email is about.


Ray, 

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:
        Did you confirm with the upstream doc project that GNOME has
        officially moved to version 4.3? 
        If not, have you added documentation somewhere that gnumeric is
        using a non-standard version of the DTD? 
        Are we sure that builds will not break if someone does not have
        this particular version of the DTD?
        Is this bump required for a particular section or merely because
        newer is generally preferable?
I had been jumping back and forth from 4.1.2 (gnome standard) to 4.2 and
4.3 in the hope that GNOME would eventually evolve. I'm not sure how we
decide what version to use.

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. Now all the paragraphs you changed
are wacky. Leaving as is for now but we should reach some consensus on
this.

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? Can it generate pdf's reliably? Do those get posted somewhere?

Jody,

You added some entity definitions like for &mdash; which is defined
already by docbook. Why did you do this? Are you using tools that are
not picking up the docbook defined entities? What validation tool is
failing? For reference, I use:
  xmllint --noout --noent --valid gnumeric.xml
which doesn't complain.


Thanks all, hopefully more questions will follow,
--adrian