Hi everybody,
I just finished the migration of our long-form documentation from
http://citationstyles.org/downloads/ to http://docs.citationstyles.org/.
http://docs.citationstyles.org/ had existed for a while, but was populated
from https://github.com/rmzelle/writing. I now updated
https://github.com/citation-style-language/documentation/ to be compatible
with Sphinx and Read the Docs, and hooked it up to
http://docs.citationstyles.org/. We now have:
http://docs.citationstyles.org/en/stable/
http://docs.citationstyles.org/en/1.0.1/
http://docs.citationstyles.org/en/1.0/
http://docs.citationstyles.org/en/1.0-20100321/
http://docs.citationstyles.org/en/master/
"stable" always equals the latest version ("1.0.1"). We have git branches
for each CSL version ("1.0" and "1.0.1"), and there is a git tag for the
original 1.0 specification ("1.0-20100321") (I might hide the latter
because it might be confusing for users). Each version only contains the
release notes for that version. Dan set up redirects for the original
http://citationstyles.org/downloads/pages (e.g.,
http://citationstyles.org/downloads/specification.html redirects to
http://docs.citationstyles.org/en/stable/specification.html).
Since Read the Docs automatically builds documentation when a commit is
pushed to GitHub, it's now much easier for me to make corrections and to
keep the specification up to date. The HTML is now responsive as well.
Rintze
On Mon, Oct 27, 2014 at 9:26 PM, Rintze Zelle <[email protected]>
wrote:
> So, any opinions on how to best organize our CSL documentation?
> http://docs.citationstyles.org/en/latest/ currently has the following
> documents:
>
> Primer — An Introduction to CSL
> Guide to Translating CSL Locale Files
> CSL 1.0.1 Specification (2012-09-03)
> CSL 1.0.1 Release Notes
> CSL 1.0 Specification (2010-05-30)
> CSL 1.0 Specification (2010-03-21)
> CSL 1.0 Release Notes
>
> This mirrors the current setup in
> https://github.com/citation-style-language/documentation, where we
> only use the "master" branch and copy files when we have a release.
>
> The alternative is to adopt a proper Git branch model for
> https://github.com/citation-style-language/documentation, so we end up
> with something like:
>
> http://docs.citationstyles.org/en/stable/ (default for users visiting
> http://docs.citationstyles.org/; mirrors content of latest release)
> http://docs.citationstyles.org/en/master/ (for development)
> http://docs.citationstyles.org/en/1.0.1/ (for CSL 1.0.1)
> http://docs.citationstyles.org/en/1.0/ (for CSL 1.0.1)
>
> I'm leaning towards adopting the latter. However, Read the Docs
> recommends the use of Semantic Versioning (see
> http://read-the-docs.readthedocs.org/en/latest/versions.html and
> http://semver.org/). According to these rules CSL 1.0.1 should
> probably have been CSL 1.1. While we probably can get away with that
> discrepancy, I'm not entirely sure how to best deal with
> specification-only updates, like the 2010-05-30 update we had for CSL
> 1.0. We could just create a single branch for CSL 1.0, but that would
> mean that we couldn't offer rendered versions of both the 2010-03-21
> and 2010-05-30 CSL 1.0 specification releases (but just the latter).
> That might be an acceptable loss, though.
>
> Rintze
>
------------------------------------------------------------------------------
Dive into the World of Parallel Programming The Go Parallel Website, sponsored
by Intel and developed in partnership with Slashdot Media, is your hub for all
things parallel software development, from weekly thought leadership blogs to
news, videos, case studies, tutorials and more. Take a look and join the
conversation now. http://goparallel.sourceforge.net/
_______________________________________________
xbiblio-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/xbiblio-devel
