You are viewing a plain text version of this content. The canonical link for it is here.
Posted to c-users@xalan.apache.org by Roger Leigh <rl...@codelibre.net> on 2020/05/09 23:21:36 UTC
Rewritten documentation for 1.12 release -- feedback requested
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
Re: Rewritten documentation for 1.12 release -- feedback requested
Posted by Roger Leigh <rl...@codelibre.net>.
On 27/05/2020 15:19, Bill Blough wrote:
> On Sat, May 23, 2020 at 06:32:54PM +0100, Roger Leigh wrote:
>> Please could anyone interested take a look over it and identify any
>> potential issues. The only one I'm aware of is that the "Licensing" page
>> linked to from https://apache.github.io/xalan-c/ links to
>> https://apache.github.io/xalan-c/license.md rather than
>> https://apache.github.io/xalan-c/license.html (that is to say, for that
>> single page, the markdown was not converted to HTML). Anyone familiar with
>> GitHub pages know why the conversion failed for that page. It views fine on
>> https://github.com/apache/xalan-c/blob/master/docs/license.md Did the
>> previous use of ".." links cause it to be blacklisted for security reasons
>> or something (https://raw.githubusercontent.com/apache/xalan-c/babd58ee5d14e0f9d1ed3cdaade6ba1f189a4ffa/license.md)?
> I've seen cases in the past where the markdown gets served initially, but
> eventually the html gets served as expected. Maybe due to some sort of
> processing delay or caching issue? At any rate, that seems to be the
> case here, as it's showing the html as expected when I view it.
It didn't seem to be a delay--the rest of the site was updated and
generated correctly! And it behaved this way across multiple pushes and
regeneration of the content. It was explicitly named ".md" while the
rest of the generated pages were ".html", and renaming license.md to
licensing.md immediately solved it
(https://apache.github.io/xalan-c/licensing.html). So I'm none the
wiser, but every page is now generated as expected! The old website has
a redirect from license.html to the new page (try
xalan.staged.apache.org/xalan-c/license.html).
Regards,
Roger
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@xalan.apache.org
For additional commands, e-mail: dev-help@xalan.apache.org
Re: Rewritten documentation for 1.12 release -- feedback requested
Posted by Bill Blough <bi...@apache.org>.
On Sat, May 23, 2020 at 06:32:54PM +0100, Roger Leigh wrote:
>
> Please could anyone interested take a look over it and identify any
> potential issues. The only one I'm aware of is that the "Licensing" page
> linked to from https://apache.github.io/xalan-c/ links to
> https://apache.github.io/xalan-c/license.md rather than
> https://apache.github.io/xalan-c/license.html (that is to say, for that
> single page, the markdown was not converted to HTML). Anyone familiar with
> GitHub pages know why the conversion failed for that page. It views fine on
> https://github.com/apache/xalan-c/blob/master/docs/license.md Did the
> previous use of ".." links cause it to be blacklisted for security reasons
> or something (https://raw.githubusercontent.com/apache/xalan-c/babd58ee5d14e0f9d1ed3cdaade6ba1f189a4ffa/license.md)?
I've seen cases in the past where the markdown gets served initially, but
eventually the html gets served as expected. Maybe due to some sort of
processing delay or caching issue? At any rate, that seems to be the
case here, as it's showing the html as expected when I view it.
--
GPG: 5CDD 0C9C F446 BC1B 2509 8791 1762 E022 7034 CF84
Re: Rewritten documentation for 1.12 release -- feedback requested
Posted by Bill Blough <bi...@apache.org>.
On Sat, May 23, 2020 at 06:32:54PM +0100, Roger Leigh wrote:
>
> Please could anyone interested take a look over it and identify any
> potential issues. The only one I'm aware of is that the "Licensing" page
> linked to from https://apache.github.io/xalan-c/ links to
> https://apache.github.io/xalan-c/license.md rather than
> https://apache.github.io/xalan-c/license.html (that is to say, for that
> single page, the markdown was not converted to HTML). Anyone familiar with
> GitHub pages know why the conversion failed for that page. It views fine on
> https://github.com/apache/xalan-c/blob/master/docs/license.md Did the
> previous use of ".." links cause it to be blacklisted for security reasons
> or something (https://raw.githubusercontent.com/apache/xalan-c/babd58ee5d14e0f9d1ed3cdaade6ba1f189a4ffa/license.md)?
I've seen cases in the past where the markdown gets served initially, but
eventually the html gets served as expected. Maybe due to some sort of
processing delay or caching issue? At any rate, that seems to be the
case here, as it's showing the html as expected when I view it.
--
GPG: 5CDD 0C9C F446 BC1B 2509 8791 1762 E022 7034 CF84
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@xalan.apache.org
For additional commands, e-mail: dev-help@xalan.apache.org
Re: Rewritten documentation for 1.12 release -- feedback requested
Posted by Roger Leigh <rl...@codelibre.net>.
Dear all,
The updated website is staged here:
https://xalan.staged.apache.org
All URLs under https://xalan.staged.apache.org/xalan-c will redirect to
https://apache.github.io/xalan-c/ using the redirects here:
https://github.com/apache/xalan-site/blob/stage/.htaccess
If this is generally acceptable, I'll push this to the main master
branch when we make the 1.12 release.
Please could anyone interested take a look over it and identify any
potential issues. The only one I'm aware of is that the "Licensing"
page linked to from https://apache.github.io/xalan-c/ links to
https://apache.github.io/xalan-c/license.md rather than
https://apache.github.io/xalan-c/license.html (that is to say, for that
single page, the markdown was not converted to HTML). Anyone familiar
with GitHub pages know why the conversion failed for that page. It
views fine on
https://github.com/apache/xalan-c/blob/master/docs/license.md Did the
previous use of ".." links cause it to be blacklisted for security
reasons or something
(https://raw.githubusercontent.com/apache/xalan-c/babd58ee5d14e0f9d1ed3cdaade6ba1f189a4ffa/license.md)?
Thanks,
Roger
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@xalan.apache.org
For additional commands, e-mail: dev-help@xalan.apache.org
Re: Rewritten documentation for 1.12 release -- feedback requested
Posted by Bill Blough <bi...@apache.org>.
On Sun, May 10, 2020 at 01:22:33PM +0100, Roger Leigh wrote:
>
> Overall, I'm pretty happy with the documentation and API reference, and I
> hope that this is generally acceptable.
Hi Roger,
This looks great. Thanks for all of your work on it.
Best regards,
Bill
--
GPG: 5CDD 0C9C F446 BC1B 2509 8791 1762 E022 7034 CF84
Re: Rewritten documentation for 1.12 release -- feedback requested
Posted by Jay Sprenkle <js...@gmail.com>.
Thank you for all your hard work! Too few bother with documenting anything
On Sun, May 10, 2020 at 7:22 AM Roger Leigh <rl...@codelibre.net> wrote:
> On 10/05/2020 00:21, Roger Leigh wrote:
>
> *
> 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
>
> This branch has been updated with a number of markdown syntax errors
> fixed, where the GitHub kramdown processor was not liking the variant the
> docs were written with, as well as correcting several syntax errors and
> remaining stylebook fragments that got missed.
>
> 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)
>
> Those URIs are now https://rleigh-codelibre.github.io/xalan-c/ and
> https://rleigh-codelibre.github.io/xalan-c/api/index.html for the API
> reference (top-level README dropped)
>
> I also pushed the same to the "gh-pages" branch in the main repository.
> This means that these official URIs now work:
>
> * https://apache.github.io/xalan-c/
>
> * https://apache.github.io/xalan-c/api
>
>
> Overall, I'm pretty happy with the documentation and API reference, and I
> hope that this is generally acceptable.
>
>
> Regards,
>
> Roger
>
--
“Don’t follow the masses. Sometimes the ‘m’ is silent.”
--
“There are three rules for writing a novel. Unfortunately, no one knows
what they are.” ― W. Somerset Maugham
--
If I'm going to write science fiction I should know SCIENCE!
Technology trends and prognostications about the future science:
Facebook <https://www.facebook.com/JaySprenkle> | Twitter
<https://twitter.com/jsprenkle1>
My personal technology blog <https://jaysprenkle.wordpress.com/>
Re: Rewritten documentation for 1.12 release -- feedback requested
Posted by Jay Sprenkle <js...@gmail.com>.
Thank you for all your hard work! Too few bother with documenting anything
On Sun, May 10, 2020 at 7:22 AM Roger Leigh <rl...@codelibre.net> wrote:
> On 10/05/2020 00:21, Roger Leigh wrote:
>
> *
> 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
>
> This branch has been updated with a number of markdown syntax errors
> fixed, where the GitHub kramdown processor was not liking the variant the
> docs were written with, as well as correcting several syntax errors and
> remaining stylebook fragments that got missed.
>
> 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)
>
> Those URIs are now https://rleigh-codelibre.github.io/xalan-c/ and
> https://rleigh-codelibre.github.io/xalan-c/api/index.html for the API
> reference (top-level README dropped)
>
> I also pushed the same to the "gh-pages" branch in the main repository.
> This means that these official URIs now work:
>
> * https://apache.github.io/xalan-c/
>
> * https://apache.github.io/xalan-c/api
>
>
> Overall, I'm pretty happy with the documentation and API reference, and I
> hope that this is generally acceptable.
>
>
> Regards,
>
> Roger
>
--
“Don’t follow the masses. Sometimes the ‘m’ is silent.”
--
“There are three rules for writing a novel. Unfortunately, no one knows
what they are.” ― W. Somerset Maugham
--
If I'm going to write science fiction I should know SCIENCE!
Technology trends and prognostications about the future science:
Facebook <https://www.facebook.com/JaySprenkle> | Twitter
<https://twitter.com/jsprenkle1>
My personal technology blog <https://jaysprenkle.wordpress.com/>
Re: Rewritten documentation for 1.12 release -- feedback requested
Posted by Bill Blough <bi...@apache.org>.
On Sun, May 10, 2020 at 01:22:33PM +0100, Roger Leigh wrote:
>
> Overall, I'm pretty happy with the documentation and API reference, and I
> hope that this is generally acceptable.
Hi Roger,
This looks great. Thanks for all of your work on it.
Best regards,
Bill
--
GPG: 5CDD 0C9C F446 BC1B 2509 8791 1762 E022 7034 CF84
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@xalan.apache.org
For additional commands, e-mail: dev-help@xalan.apache.org
Re: Rewritten documentation for 1.12 release -- feedback requested
Posted by Roger Leigh <rl...@codelibre.net>.
On 10/05/2020 00:21, Roger Leigh wrote:
> *
> 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
>
This branch has been updated with a number of markdown syntax errors
fixed, where the GitHub kramdown processor was not liking the variant
the docs were written with, as well as correcting several syntax errors
and remaining stylebook fragments that got missed.
> 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)
>
>
Those URIs are now https://rleigh-codelibre.github.io/xalan-c/ and
https://rleigh-codelibre.github.io/xalan-c/api/index.html for the API
reference (top-level README dropped)
I also pushed the same to the "gh-pages" branch in the main repository.
This means that these official URIs now work:
* https://apache.github.io/xalan-c/
* https://apache.github.io/xalan-c/api
Overall, I'm pretty happy with the documentation and API reference, and
I hope that this is generally acceptable.
Regards,
Roger
Re: Rewritten documentation for 1.12 release -- feedback requested
Posted by Roger Leigh <rl...@codelibre.net>.
On 10/05/2020 00:21, Roger Leigh wrote:
> *
> 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
>
This branch has been updated with a number of markdown syntax errors
fixed, where the GitHub kramdown processor was not liking the variant
the docs were written with, as well as correcting several syntax errors
and remaining stylebook fragments that got missed.
> 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)
>
>
Those URIs are now https://rleigh-codelibre.github.io/xalan-c/ and
https://rleigh-codelibre.github.io/xalan-c/api/index.html for the API
reference (top-level README dropped)
I also pushed the same to the "gh-pages" branch in the main repository.
This means that these official URIs now work:
* https://apache.github.io/xalan-c/
* https://apache.github.io/xalan-c/api
Overall, I'm pretty happy with the documentation and API reference, and
I hope that this is generally acceptable.
Regards,
Roger
Re: Rewritten documentation for 1.12 release -- feedback requested
Posted by Roger Leigh <rl...@codelibre.net>.
Dear all,
The updated website is staged here:
https://xalan.staged.apache.org
All URLs under https://xalan.staged.apache.org/xalan-c will redirect to
https://apache.github.io/xalan-c/ using the redirects here:
https://github.com/apache/xalan-site/blob/stage/.htaccess
If this is generally acceptable, I'll push this to the main master
branch when we make the 1.12 release.
Please could anyone interested take a look over it and identify any
potential issues. The only one I'm aware of is that the "Licensing"
page linked to from https://apache.github.io/xalan-c/ links to
https://apache.github.io/xalan-c/license.md rather than
https://apache.github.io/xalan-c/license.html (that is to say, for that
single page, the markdown was not converted to HTML). Anyone familiar
with GitHub pages know why the conversion failed for that page. It
views fine on
https://github.com/apache/xalan-c/blob/master/docs/license.md Did the
previous use of ".." links cause it to be blacklisted for security
reasons or something
(https://raw.githubusercontent.com/apache/xalan-c/babd58ee5d14e0f9d1ed3cdaade6ba1f189a4ffa/license.md)?
Thanks,
Roger