Permalink
Browse files

Remove "link" icons, now controlled via CSS: citation-style-language/…

  • Loading branch information...
1 parent 3a90107 commit 0ad791b504d14b13da99f4a2926714c7ecfc2d19 @rmzelle rmzelle committed Jun 16, 2012
Showing with 42 additions and 49 deletions.
  1. +8 −10 primer.txt
  2. +13 −15 specification.txt
  3. +21 −24 upgrade-notes.txt
View
@@ -22,8 +22,6 @@ __ http://citationstyles.org/
Author
* Rintze M. Zelle
-.. |link| image:: link.png
-
========
.. contents:: Table of Contents
@@ -41,7 +39,7 @@ This primer is meant as a first introduction to the Citation Style Language
(CSL), and is primarily aimed towards those wishing to create or modify CSL
styles. Some knowledge about the structure of XML or HTML will come in handy. If
you are completely unfamiliar with either markup language, check out one of the
-many online introductions to XML, e.g. W3Schools' |link| `XML Tutorial
+many online introductions to XML, e.g. W3Schools' `XML Tutorial
<http://www.w3schools.com/xml/>`_.
What is CSL?
@@ -67,7 +65,7 @@ localization support: with a single CSL style, you can format citations and
bibliographies in any of several dozen different languages, using localized
terms, date formats, and punctuation.
-.. [#] Over 1500 CSL styles are available at |link| http://www.zotero.org/styles
+.. [#] Over 1500 CSL styles are available at http://www.zotero.org/styles
Different Classes of Citation Styles
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -157,7 +155,7 @@ A) **"in-text"** styles: when a work is cited, a *citation* is added to the
.. [#] The illustrating sentence is from Gidijala L, Kiel JAKW, Douma RD,
Seifar RM, van Gulik WM, et al. 2009 An Engineered Yeast Efficiently
- Secreting Penicillin. PLoS ONE 4(12): e8317. |link|
+ Secreting Penicillin. PLoS ONE 4(12): e8317.
`doi:10.1371/journal.pone.0008317
<http://dx.doi.org/10.1371/journal.pone.0008317>`_
@@ -177,7 +175,7 @@ B) **"note"** styles: when a work is cited, a *marker* is added to the sentence.
.. [*] Sir J. E. Tennent, 'Ceylon,' vol. ii. 1859, p. 107.
.. [#] Example taken from Darwin 1882 The descent of man, and selection in
- relation to sex. London: John Murray. 2nd ed., 15th thousand, |link|
+ relation to sex. London: John Murray. 2nd ed., 15th thousand,
http://darwin-online.org.uk/content/frameset?itemID=F955&viewtype=image&pageseq=1.
In-text citations or foot and endnotes can reference multiple works. In CSL
@@ -462,7 +460,7 @@ After making changes to a CSL style, it is always a good idea to check whether
the style still *validates*. Correct processing of CSL styles requires that CSL
styles are both written in correct XML and conform to the CSL schema. Both these
checks can be performed with an XML validator. Here we will use the
-online validator |link| `Validator.nu <http://validator.nu/>`_:
+online validator `Validator.nu <http://validator.nu/>`_:
1. Select the style you want to validate. When using "Address" option, provide
the URL to the style and check the "Be lax about HTTP Content-Type"
@@ -483,7 +481,7 @@ When we perform these steps, we get an error:
.. |return| unicode:: U+21a9
-Oops! It seems that "doi" is an invalid variable name. After checking the |link|
+Oops! It seems that "doi" is an invalid variable name. After checking the
`CSL 1.0 specification`_, we discover that the variable name should be
capitalized ("DOI"). When we make this correction (``<text variable="DOI"
prefix=", "/>``) and run the validation again, we get the message:
@@ -499,7 +497,7 @@ Learning More
-------------
You now know the purpose of the Citation Style Language and the basic structure
-of CSL 1.0 styles. To learn more, browse the documentation at |link|
+of CSL 1.0 styles. To learn more, browse the documentation at
`CitationStyles.org <http://citationstyles.org>`_. In addition to reading the
-|link| `CSL 1.0 specification`_, it can be very useful to take a look at other
+`CSL 1.0 specification`_, it can be very useful to take a look at other
CSL 1.0 styles.
View
@@ -43,8 +43,6 @@ __ http://citationstyles.org/
.. |CCBYSA| image:: http://i.creativecommons.org/l/by-sa/3.0/80x15.png
.. _CCBYSA: http://creativecommons.org/licenses/by-sa/3.0/
-.. |link| image:: link.png
-
.. |--| unicode:: U+2013
:trim:
@@ -69,19 +67,19 @@ formatting of citations, notes and bibliographies, offering:
- Already over 2000 freely available styles (Creative Commons BY-SA licensed)
For additional documentation, the CSL schema, styles, and locales, visit the CSL
-project home, |link| `citationstyles.org <http://citationstyles.org>`_.
+project home, `citationstyles.org <http://citationstyles.org>`_.
Terminology
~~~~~~~~~~~
The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT,
-RECOMMENDED, MAY, and OPTIONAL, are to be interpreted as described in |link|
+RECOMMENDED, MAY, and OPTIONAL, are to be interpreted as described in
`IETF RFC 2119 <http://tools.ietf.org/html/rfc2119>`_.
Namespacing
-----------
-The CSL |link| `XML namespace URI <http://en.wikipedia.org/wiki/XML_Namespace>`_
+The CSL `XML namespace URI <http://en.wikipedia.org/wiki/XML_Namespace>`_
is "http://purl.org/net/xbiblio/csl". The namespace prefix ``cs:`` is used
throughout this specification when referring to CSL elements, but is generally
omitted in favor of a default namespace declaration (set with
@@ -142,7 +140,7 @@ carries the following attributes:
notes ("note").
``default-locale`` (optional)
- Sets a default locale for style localization. Value must be a |link| `locale
+ Sets a default locale for style localization. Value must be a `locale
code <http://books.xmlschemata.org/relaxng/ch19-77191.html>`_.
``version``
@@ -192,7 +190,7 @@ Info
^^^^
The ``cs:info`` element contains the style's metadata. Its structure is based on
-the |link| `Atom Syndication Format <http://tools.ietf.org/html/rfc4287>`_. In
+the `Atom Syndication Format <http://tools.ietf.org/html/rfc4287>`_. In
independent styles, ``cs:info`` has the following child elements:
``cs:author`` and ``cs:contributor`` (optional)
@@ -226,7 +224,7 @@ independent styles, ``cs:info`` has the following child elements:
The ``cs:issn`` element may be used multiple times to indicate the ISSN
identifier(s) of the journal for which the style was written. The
``cs:eissn`` and ``cs:issnl`` elements may each be used once for the eISSN
- and |link| `ISSN-L <http://www.issn.org/2-22637-What-is-an-ISSN-L.php>`_
+ and `ISSN-L <http://www.issn.org/2-22637-What-is-an-ISSN-L.php>`_
identifiers, respectively.
``cs:link`` (optional)
@@ -241,7 +239,7 @@ independent styles, ``cs:info`` has the following child elements:
The ``cs:link`` element may contain content describing the link.
``cs:published`` (optional)
- May appear once. The contents of ``cs:published`` must be a |link|
+ May appear once. The contents of ``cs:published`` must be a
`timestamp <http://books.xmlschemata.org/relaxng/ch19-77049.html>`_,
indicating when the style was initially created or made available.
@@ -263,13 +261,13 @@ independent styles, ``cs:info`` has the following child elements:
style name (e.g. "APA").
``cs:updated``
- Must appear once. The contents of ``cs:updated`` must be a |link| `timestamp
+ Must appear once. The contents of ``cs:updated`` must be a `timestamp
<http://books.xmlschemata.org/relaxng/ch19-77049.html>`_ that shows when the
style was last updated.
The ``cs:link``, ``cs:rights``, ``cs:summary``, ``cs:title`` and
``cs:title-short`` elements may carry a ``xml:lang`` attribute to specify the
-language of the element's content (the value must be an |link| `xsd:language
+language of the element's content (the value must be an `xsd:language
locale code <http://books.xmlschemata.org/relaxng/ch19-77191.html>`_). For
``cs:link``, the attribute can also be used to indicate the language of the link
target.
@@ -406,7 +404,7 @@ may be redefined or supplemented with ``cs:locale`` elements, which should be
placed directly after the ``cs:info`` element.
The value of the optional ``xml:lang`` attribute on ``cs:locale``, which must be
-set to an |link| `xsd:language locale code
+set to an `xsd:language locale code
<http://books.xmlschemata.org/relaxng/ch19-77191.html>`_, determines which
languages or language dialects are affected (see `Locale Fallback`_).
@@ -544,12 +542,12 @@ the following child elements:
May appear once. The contents of ``cs:rights`` specifies the license under
which the locale file is released. The element may carry a ``license``
attribute to specify the URI of the license, and a ``xml:lang`` attribute to
- specify the language of the element's content (the value must be an |link|
+ specify the language of the element's content (the value must be an
`xsd:language locale code
<http://books.xmlschemata.org/relaxng/ch19-77191.html>`_).
``cs:updated`` (optional)
- May appear once. The contents of ``cs:updated`` must be a |link| `timestamp
+ May appear once. The contents of ``cs:updated`` must be a `timestamp
<http://books.xmlschemata.org/relaxng/ch19-77049.html>`_ that shows when the
locale file was last updated.
@@ -2772,7 +2770,7 @@ The page abbreviation rules for the different values of the
``page-range-format`` attribute on ``cs:style`` are:
"chicago"
- Page ranges are abbreviated according to the |link|
+ Page ranges are abbreviated according to the
`Chicago Manual of Style-rules <http://www.aahn.org/guidelines.html>`_:
+------------------------+--------------------------+--------------------------+
View
@@ -26,9 +26,6 @@ __ http://citationstyles.org/
* Frank G. Bennett, Jr.
* Bruce D'Arcus
-.. |link| image:: link.png
-
-
========
.. contents:: Table of Contents
@@ -38,7 +35,7 @@ __ http://citationstyles.org/
Citation Style Language 1.0 - What's New?
=========================================
-The release of |link| `Citation Style Language 1.0
+The release of `Citation Style Language 1.0
<http://citationstyles.org/citation-style-language/schema/>`_ represents a
significant update of the Citation Style Language (CSL), an open XML language to
describe citation styles. This document describes the changes compared to CSL
@@ -56,29 +53,29 @@ the need to include this namespace for each element.
Project Home(s)
+++++++++++++++
-The first change is that |link| `CitationStyles.org
+The first change is that `CitationStyles.org
<http://citationstyles.org/>`_ is the new home of the CSL project (the old home
-was located at |link| `<http://xbiblio.sourceforge.net/csl/>`_). The new website
+was located at `<http://xbiblio.sourceforge.net/csl/>`_). The new website
will be the central location to find CSL schemas, documentation and styles.
-For CSL development the |link| `SourceForge xbiblio mailing list
+For CSL development the `SourceForge xbiblio mailing list
<http://sourceforge.net/mailarchive/forum.php?forum_name=xbiblio-devel>`_ will
be kept in use. Code hosting has moved around a bit. A switch from
-SourceForge.net to |link| `Bitbucket <https://bitbucket.org/bdarcus/>`_ in 2010
+SourceForge.net to `Bitbucket <https://bitbucket.org/bdarcus/>`_ in 2010
has been followed by a move to `GitHub
<https://github.com/citation-style-language/>`_ in 2011.
Documentation
+++++++++++++
Prior to the release of CSL 1.0, CSL documentation was rather scarce. Most of
-what was available was hosted on the |link| `Zotero wiki
+what was available was hosted on the `Zotero wiki
<http://www.zotero.org/support/>`_. With CSL 1.0, we improved on this situation.
-In addition to these upgrade notes, a full |link| specification_ has been made
-available. As before, the |link| `schema
+In addition to these upgrade notes, a full specification_ has been made
+available. As before, the `schema
<http://citationstyles.org/citation-style-language/schema/>`_ itself is also a
source of information, although reading the schema requires some understanding
-of |link| `RELAX NG Compact <http://www.relaxng.org/>`_, the XML schema language
+of `RELAX NG Compact <http://www.relaxng.org/>`_, the XML schema language
in which the CSL schema is written.
.. _specification: http://citationstyles.org/downloads/specification.html
@@ -109,9 +106,9 @@ Validation
The CSL 1.0 schema has been extended with two Schematron rules to make sure
styles don't use ``cs:text`` and ``cs:key`` elements that call non-existing
``cs:macro`` elements. Note that not all validators support embedded Schematron
-code (e.g. |link| `Jing <http://www.thaiopensource.com/relaxng/jing.html>`_ just
+code (e.g. `Jing <http://www.thaiopensource.com/relaxng/jing.html>`_ just
ignores the rules). In addition, the CSL 1.0 schema can now be used to validate
-the |link| `locales files`_ (e.g. "locales-en-US.xml"), which contain
+the `locales files`_ (e.g. "locales-en-US.xml"), which contain
localizations of terms, date formats and style options.
.. _locales files: https://github.com/citation-style-language/locales
@@ -124,39 +121,39 @@ Updating CSL 0.8 Styles
CSL 1.0 is backward incompatible with CSL 0.8, which means that CSL 0.8 styles
don't work with CSL 1.0 processors. Fortunately, it is possible to
-(automatically) update CSL 0.8 styles to the CSL 1.0 format using the |link|
+(automatically) update CSL 0.8 styles to the CSL 1.0 format using the
`upgrade.xsl
<https://github.com/citation-style-language/utilities/raw/master/update.xsl>`_
XSLT stylesheet. This conversion has been performed for all the styles in the
-|link| `Zotero Style Repository <http://www.zotero.org/styles>`_. However, if
+`Zotero Style Repository <http://www.zotero.org/styles>`_. However, if
you use (custom) CSL styles that aren't included in this style repository, you
might need to do this yourself.
Using upgrade.xsl
~~~~~~~~~~~~~~~~~
First, check whether the styles that you wish to update validate against the
-|link| `CSL 0.8.1 schema
+`CSL 0.8.1 schema
<http://citationstyles.org/citation-style-language/schema/>`_.
Then use an XSLT processor to update the styles. Available options are the
-command-line tools |link| `Saxon <http://saxon.sourceforge.net/>`_ and |link|
+command-line tools `Saxon <http://saxon.sourceforge.net/>`_ and
`xsltproc <http://xmlsoft.org/XSLT/xsltproc2.html>`_. Alternatively, one of the
-(more user-friendly) online converters, such as the one offered by |link|
+(more user-friendly) online converters, such as the one offered by
`www.shell-tools.net <http://www.shell-tools.net/index.php?op=xslt>`_ can be
used. For the latter tool, the instructions are:
-1. Paste the contents of |link| `upgrade.xsl
+1. Paste the contents of `upgrade.xsl
<https://github.com/citation-style-language/utilities/raw/master/update.xsl>`_
- into the "xslt" text box at |link|
+ into the "xslt" text box at
`<http://www.shell-tools.net/index.php?op=xslt>`_
2. Paste the contents of the CSL 0.8 style into the "xml" text box
3. Click the "Submit Query"-button
4. Copy the text from the "output" text box to a suitable text editor (e.g.
Notepad on Windows) and save the file with a .csl-extension.
Finally, after the conversion, it is recommended to validate the converted
-style, this time against the |link| `CSL 1.0 schema`_.
+style, this time against the `CSL 1.0 schema`_.
.. _CSL 1.0 schema: http://citationstyles.org/citation-style-language/schema/
@@ -235,7 +232,7 @@ ISSN and ISSN-L
ISSN-identifiers unambiguously identify journals. While CSL 0.8 allowed only a
single ISSN identifier to be included in the style metadata section, CSL 1.0 now
supports multiple ISSNs (e.g. the ISSNs of the print and online editions of a
-journal), as well as the relatively new |link| `ISSN-L
+journal), as well as the relatively new `ISSN-L
<http://www.issn.org/2-22637-What-is-an-ISSN-L.php>`_ identifier. For example:
.. sourcecode:: xml
@@ -1092,6 +1089,6 @@ CSL 1.0 also introduces a number of new terms:
summer, fall and winter. See `Seasons`_.
.. [1]
- A hat tip to user |link| `komrade <http://www.zotero.org/komrade>`_ of
+ A hat tip to user `komrade <http://www.zotero.org/komrade>`_ of
the Zotero forums, whose review of the major style guides led to
this array of rule-sets.

0 comments on commit 0ad791b

Please sign in to comment.