Dear all,
I mentioned in an email a few weeks back that I was intending to make a
1.12 release in the near future. One of the tasks which required
completing in order to be able to do this was to make the documentation
usable. XALANC-792 is tracking this. The main problem is that the
documentation is written in stylebook, which is a thoroughly obsolete
and long unsupported format. The tooling to compile the documentation
works only with Java 6, and the libraries are no longer maintained, and
Java 6 doesn't work well on current platforms, if you can still obtain a
copy. Given the severe lack of maintenance activity, I've tried to go
with the least-effort, largest benefit route, to get us working
documentation that won't be much work to maintain, and doesn't require
expert skills to work on.
As a result, I have spent a not insignificant amount of time hand
converting the entire documentation set to markdown, at least 1.5 man
weeks all in all if not more. It's not quite as elegant as stylebook,
but it's good enough. I've also updated the doxygen documentation
configuration. One thing you might notice is that it's using SVG logos,
and the doxygen documentation is also using SVG graphs. The
documentation content is pretty much the same as before, except for
removing outright obsolete stuff like Windows 95/98 FAQs, screenshots
from old Visual Studio versions, no longer provided binary downloads,
and consolidating information when it was repeated on several pages,
such as the build/install instructions. The build instructions have
been converted to document the new CMake build system. And I've added
how to install Xerces-C++ binary packages from third-party distributors
which are likely the best route for most users to obtain the library.
I would love some feedback on this, so I have pushed the changes here:
*
https://github.com/rleigh-codelibre/xalan-c/tree/XALANC-792_replace_stylebook_documentation
(see README at bottom of page for example; links through to docs but
not API reference); docs can be generated with "doc-api" target if
doxygen and graphviz are installed
And the published documentation is staged here (branch gh-pages):
* https://rleigh-codelibre.github.io/xalan-c/
* https://rleigh-codelibre.github.io/xalan-c/docs/
* https://rleigh-codelibre.github.io/xalan-c/docs/api/index.html
(this would become apache.github.io/xalan-c if adopted)
I hope this is generally acceptable, but I'd love to hear any feedback
positive or negative so that it can be further refined. I'm sure
there's room for further improvement in the organisation of the
documentation; this is just the first pass completed to get the main
conversion done. We could, for example, consolidate the top-level
README.md with the ToC at docs/index.md.
There are a few followup items:
- restoring doc to API reference links; needs this work merging and
gh-pages activating for the main xerces-c repository to give us stable
links to reference
- automating generation of the gh-pages branch content, i.e. combining
generated doxygen with the markdown; the above was done manually as an
example of what the main site could look like
- redirecting links from the old website to the new pages
- there's no "documentation" release artefact with the HTML manual and
Doxygen API reference; is that necessary to have, or can users and/or
distributors just build it themselves if we add the necessary build
targets and/or instructions?
Once this is finalised, other than updating the release history and
doing a final proofread of the documentation, I think we'll be in a good
position to make a 1.12 release. In the interim, if anyone would like
to do any testing of the current git "master" branch with their own
codebases, that would certainly be very much appreciated. It's been
nearly eight years since a release was last made, and I'd like some
extra confidence that it's working nicely with contemporary platforms,
and that there's no bitrot to fix that hasn't already been addressed.
If there are any other important issues which need addressing before
making a release, I'd like to hear ASAP.
Kind regards,
Roger
