├── .gitignore ├── LICENSE.txt ├── Makefile ├── README.md ├── attic └── specification.rst ├── conf.py ├── index.rst ├── make.bat ├── media ├── cc-by-sa-80x15.png └── csl-infrastructure.png ├── primer.rst ├── specification.rst └── translating-locale-files.rst /.gitignore: -------------------------------------------------------------------------------- 1 | _build/ 2 | _static/ 3 | _templates/ 4 | .vscode/settings.json 5 | -------------------------------------------------------------------------------- /LICENSE.txt: -------------------------------------------------------------------------------- 1 | Attribution-ShareAlike 4.0 International 2 | 3 | ======================================================================= 4 | 5 | Creative Commons Corporation ("Creative Commons") is not a law firm and 6 | does not provide legal services or legal advice. Distribution of 7 | Creative Commons public licenses does not create a lawyer-client or 8 | other relationship. Creative Commons makes its licenses and related 9 | information available on an "as-is" basis. Creative Commons gives no 10 | warranties regarding its licenses, any material licensed under their 11 | terms and conditions, or any related information. Creative Commons 12 | disclaims all liability for damages resulting from their use to the 13 | fullest extent possible. 14 | 15 | Using Creative Commons Public Licenses 16 | 17 | Creative Commons public licenses provide a standard set of terms and 18 | conditions that creators and other rights holders may use to share 19 | original works of authorship and other material subject to copyright 20 | and certain other rights specified in the public license below. The 21 | following considerations are for informational purposes only, are not 22 | exhaustive, and do not form part of our licenses. 23 | 24 | Considerations for licensors: Our public licenses are 25 | intended for use by those authorized to give the public 26 | permission to use material in ways otherwise restricted by 27 | copyright and certain other rights. Our licenses are 28 | irrevocable. Licensors should read and understand the terms 29 | and conditions of the license they choose before applying it. 30 | Licensors should also secure all rights necessary before 31 | applying our licenses so that the public can reuse the 32 | material as expected. Licensors should clearly mark any 33 | material not subject to the license. This includes other CC- 34 | licensed material, or material used under an exception or 35 | limitation to copyright. More considerations for licensors: 36 | wiki.creativecommons.org/Considerations_for_licensors 37 | 38 | Considerations for the public: By using one of our public 39 | licenses, a licensor grants the public permission to use the 40 | licensed material under specified terms and conditions. If 41 | the licensor's permission is not necessary for any reason--for 42 | example, because of any applicable exception or limitation to 43 | copyright--then that use is not regulated by the license. Our 44 | licenses grant only permissions under copyright and certain 45 | other rights that a licensor has authority to grant. Use of 46 | the licensed material may still be restricted for other 47 | reasons, including because others have copyright or other 48 | rights in the material. A licensor may make special requests, 49 | such as asking that all changes be marked or described. 50 | Although not required by our licenses, you are encouraged to 51 | respect those requests where reasonable. More considerations 52 | for the public: 53 | wiki.creativecommons.org/Considerations_for_licensees 54 | 55 | ======================================================================= 56 | 57 | Creative Commons Attribution-ShareAlike 4.0 International Public 58 | License 59 | 60 | By exercising the Licensed Rights (defined below), You accept and agree 61 | to be bound by the terms and conditions of this Creative Commons 62 | Attribution-ShareAlike 4.0 International Public License ("Public 63 | License"). To the extent this Public License may be interpreted as a 64 | contract, You are granted the Licensed Rights in consideration of Your 65 | acceptance of these terms and conditions, and the Licensor grants You 66 | such rights in consideration of benefits the Licensor receives from 67 | making the Licensed Material available under these terms and 68 | conditions. 69 | 70 | 71 | Section 1 -- Definitions. 72 | 73 | a. Adapted Material means material subject to Copyright and Similar 74 | Rights that is derived from or based upon the Licensed Material 75 | and in which the Licensed Material is translated, altered, 76 | arranged, transformed, or otherwise modified in a manner requiring 77 | permission under the Copyright and Similar Rights held by the 78 | Licensor. For purposes of this Public License, where the Licensed 79 | Material is a musical work, performance, or sound recording, 80 | Adapted Material is always produced where the Licensed Material is 81 | synched in timed relation with a moving image. 82 | 83 | b. Adapter's License means the license You apply to Your Copyright 84 | and Similar Rights in Your contributions to Adapted Material in 85 | accordance with the terms and conditions of this Public License. 86 | 87 | c. BY-SA Compatible License means a license listed at 88 | creativecommons.org/compatiblelicenses, approved by Creative 89 | Commons as essentially the equivalent of this Public License. 90 | 91 | d. Copyright and Similar Rights means copyright and/or similar rights 92 | closely related to copyright including, without limitation, 93 | performance, broadcast, sound recording, and Sui Generis Database 94 | Rights, without regard to how the rights are labeled or 95 | categorized. For purposes of this Public License, the rights 96 | specified in Section 2(b)(1)-(2) are not Copyright and Similar 97 | Rights. 98 | 99 | e. Effective Technological Measures means those measures that, in the 100 | absence of proper authority, may not be circumvented under laws 101 | fulfilling obligations under Article 11 of the WIPO Copyright 102 | Treaty adopted on December 20, 1996, and/or similar international 103 | agreements. 104 | 105 | f. Exceptions and Limitations means fair use, fair dealing, and/or 106 | any other exception or limitation to Copyright and Similar Rights 107 | that applies to Your use of the Licensed Material. 108 | 109 | g. License Elements means the license attributes listed in the name 110 | of a Creative Commons Public License. The License Elements of this 111 | Public License are Attribution and ShareAlike. 112 | 113 | h. Licensed Material means the artistic or literary work, database, 114 | or other material to which the Licensor applied this Public 115 | License. 116 | 117 | i. Licensed Rights means the rights granted to You subject to the 118 | terms and conditions of this Public License, which are limited to 119 | all Copyright and Similar Rights that apply to Your use of the 120 | Licensed Material and that the Licensor has authority to license. 121 | 122 | j. Licensor means the individual(s) or entity(ies) granting rights 123 | under this Public License. 124 | 125 | k. Share means to provide material to the public by any means or 126 | process that requires permission under the Licensed Rights, such 127 | as reproduction, public display, public performance, distribution, 128 | dissemination, communication, or importation, and to make material 129 | available to the public including in ways that members of the 130 | public may access the material from a place and at a time 131 | individually chosen by them. 132 | 133 | l. Sui Generis Database Rights means rights other than copyright 134 | resulting from Directive 96/9/EC of the European Parliament and of 135 | the Council of 11 March 1996 on the legal protection of databases, 136 | as amended and/or succeeded, as well as other essentially 137 | equivalent rights anywhere in the world. 138 | 139 | m. You means the individual or entity exercising the Licensed Rights 140 | under this Public License. Your has a corresponding meaning. 141 | 142 | 143 | Section 2 -- Scope. 144 | 145 | a. License grant. 146 | 147 | 1. Subject to the terms and conditions of this Public License, 148 | the Licensor hereby grants You a worldwide, royalty-free, 149 | non-sublicensable, non-exclusive, irrevocable license to 150 | exercise the Licensed Rights in the Licensed Material to: 151 | 152 | a. reproduce and Share the Licensed Material, in whole or 153 | in part; and 154 | 155 | b. produce, reproduce, and Share Adapted Material. 156 | 157 | 2. Exceptions and Limitations. For the avoidance of doubt, where 158 | Exceptions and Limitations apply to Your use, this Public 159 | License does not apply, and You do not need to comply with 160 | its terms and conditions. 161 | 162 | 3. Term. The term of this Public License is specified in Section 163 | 6(a). 164 | 165 | 4. Media and formats; technical modifications allowed. The 166 | Licensor authorizes You to exercise the Licensed Rights in 167 | all media and formats whether now known or hereafter created, 168 | and to make technical modifications necessary to do so. The 169 | Licensor waives and/or agrees not to assert any right or 170 | authority to forbid You from making technical modifications 171 | necessary to exercise the Licensed Rights, including 172 | technical modifications necessary to circumvent Effective 173 | Technological Measures. For purposes of this Public License, 174 | simply making modifications authorized by this Section 2(a) 175 | (4) never produces Adapted Material. 176 | 177 | 5. Downstream recipients. 178 | 179 | a. Offer from the Licensor -- Licensed Material. Every 180 | recipient of the Licensed Material automatically 181 | receives an offer from the Licensor to exercise the 182 | Licensed Rights under the terms and conditions of this 183 | Public License. 184 | 185 | b. Additional offer from the Licensor -- Adapted Material. 186 | Every recipient of Adapted Material from You 187 | automatically receives an offer from the Licensor to 188 | exercise the Licensed Rights in the Adapted Material 189 | under the conditions of the Adapter's License You apply. 190 | 191 | c. No downstream restrictions. You may not offer or impose 192 | any additional or different terms or conditions on, or 193 | apply any Effective Technological Measures to, the 194 | Licensed Material if doing so restricts exercise of the 195 | Licensed Rights by any recipient of the Licensed 196 | Material. 197 | 198 | 6. No endorsement. Nothing in this Public License constitutes or 199 | may be construed as permission to assert or imply that You 200 | are, or that Your use of the Licensed Material is, connected 201 | with, or sponsored, endorsed, or granted official status by, 202 | the Licensor or others designated to receive attribution as 203 | provided in Section 3(a)(1)(A)(i). 204 | 205 | b. Other rights. 206 | 207 | 1. Moral rights, such as the right of integrity, are not 208 | licensed under this Public License, nor are publicity, 209 | privacy, and/or other similar personality rights; however, to 210 | the extent possible, the Licensor waives and/or agrees not to 211 | assert any such rights held by the Licensor to the limited 212 | extent necessary to allow You to exercise the Licensed 213 | Rights, but not otherwise. 214 | 215 | 2. Patent and trademark rights are not licensed under this 216 | Public License. 217 | 218 | 3. To the extent possible, the Licensor waives any right to 219 | collect royalties from You for the exercise of the Licensed 220 | Rights, whether directly or through a collecting society 221 | under any voluntary or waivable statutory or compulsory 222 | licensing scheme. In all other cases the Licensor expressly 223 | reserves any right to collect such royalties. 224 | 225 | 226 | Section 3 -- License Conditions. 227 | 228 | Your exercise of the Licensed Rights is expressly made subject to the 229 | following conditions. 230 | 231 | a. Attribution. 232 | 233 | 1. If You Share the Licensed Material (including in modified 234 | form), You must: 235 | 236 | a. retain the following if it is supplied by the Licensor 237 | with the Licensed Material: 238 | 239 | i. identification of the creator(s) of the Licensed 240 | Material and any others designated to receive 241 | attribution, in any reasonable manner requested by 242 | the Licensor (including by pseudonym if 243 | designated); 244 | 245 | ii. a copyright notice; 246 | 247 | iii. a notice that refers to this Public License; 248 | 249 | iv. a notice that refers to the disclaimer of 250 | warranties; 251 | 252 | v. a URI or hyperlink to the Licensed Material to the 253 | extent reasonably practicable; 254 | 255 | b. indicate if You modified the Licensed Material and 256 | retain an indication of any previous modifications; and 257 | 258 | c. indicate the Licensed Material is licensed under this 259 | Public License, and include the text of, or the URI or 260 | hyperlink to, this Public License. 261 | 262 | 2. You may satisfy the conditions in Section 3(a)(1) in any 263 | reasonable manner based on the medium, means, and context in 264 | which You Share the Licensed Material. For example, it may be 265 | reasonable to satisfy the conditions by providing a URI or 266 | hyperlink to a resource that includes the required 267 | information. 268 | 269 | 3. If requested by the Licensor, You must remove any of the 270 | information required by Section 3(a)(1)(A) to the extent 271 | reasonably practicable. 272 | 273 | b. ShareAlike. 274 | 275 | In addition to the conditions in Section 3(a), if You Share 276 | Adapted Material You produce, the following conditions also apply. 277 | 278 | 1. The Adapter's License You apply must be a Creative Commons 279 | license with the same License Elements, this version or 280 | later, or a BY-SA Compatible License. 281 | 282 | 2. You must include the text of, or the URI or hyperlink to, the 283 | Adapter's License You apply. You may satisfy this condition 284 | in any reasonable manner based on the medium, means, and 285 | context in which You Share Adapted Material. 286 | 287 | 3. You may not offer or impose any additional or different terms 288 | or conditions on, or apply any Effective Technological 289 | Measures to, Adapted Material that restrict exercise of the 290 | rights granted under the Adapter's License You apply. 291 | 292 | 293 | Section 4 -- Sui Generis Database Rights. 294 | 295 | Where the Licensed Rights include Sui Generis Database Rights that 296 | apply to Your use of the Licensed Material: 297 | 298 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right 299 | to extract, reuse, reproduce, and Share all or a substantial 300 | portion of the contents of the database; 301 | 302 | b. if You include all or a substantial portion of the database 303 | contents in a database in which You have Sui Generis Database 304 | Rights, then the database in which You have Sui Generis Database 305 | Rights (but not its individual contents) is Adapted Material, 306 | 307 | including for purposes of Section 3(b); and 308 | c. You must comply with the conditions in Section 3(a) if You Share 309 | all or a substantial portion of the contents of the database. 310 | 311 | For the avoidance of doubt, this Section 4 supplements and does not 312 | replace Your obligations under this Public License where the Licensed 313 | Rights include other Copyright and Similar Rights. 314 | 315 | 316 | Section 5 -- Disclaimer of Warranties and Limitation of Liability. 317 | 318 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE 319 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS 320 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF 321 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, 322 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, 323 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR 324 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, 325 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT 326 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT 327 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. 328 | 329 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE 330 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, 331 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, 332 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, 333 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR 334 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN 335 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR 336 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR 337 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. 338 | 339 | c. The disclaimer of warranties and limitation of liability provided 340 | above shall be interpreted in a manner that, to the extent 341 | possible, most closely approximates an absolute disclaimer and 342 | waiver of all liability. 343 | 344 | 345 | Section 6 -- Term and Termination. 346 | 347 | a. This Public License applies for the term of the Copyright and 348 | Similar Rights licensed here. However, if You fail to comply with 349 | this Public License, then Your rights under this Public License 350 | terminate automatically. 351 | 352 | b. Where Your right to use the Licensed Material has terminated under 353 | Section 6(a), it reinstates: 354 | 355 | 1. automatically as of the date the violation is cured, provided 356 | it is cured within 30 days of Your discovery of the 357 | violation; or 358 | 359 | 2. upon express reinstatement by the Licensor. 360 | 361 | For the avoidance of doubt, this Section 6(b) does not affect any 362 | right the Licensor may have to seek remedies for Your violations 363 | of this Public License. 364 | 365 | c. For the avoidance of doubt, the Licensor may also offer the 366 | Licensed Material under separate terms or conditions or stop 367 | distributing the Licensed Material at any time; however, doing so 368 | will not terminate this Public License. 369 | 370 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public 371 | License. 372 | 373 | 374 | Section 7 -- Other Terms and Conditions. 375 | 376 | a. The Licensor shall not be bound by any additional or different 377 | terms or conditions communicated by You unless expressly agreed. 378 | 379 | b. Any arrangements, understandings, or agreements regarding the 380 | Licensed Material not stated herein are separate from and 381 | independent of the terms and conditions of this Public License. 382 | 383 | 384 | Section 8 -- Interpretation. 385 | 386 | a. For the avoidance of doubt, this Public License does not, and 387 | shall not be interpreted to, reduce, limit, restrict, or impose 388 | conditions on any use of the Licensed Material that could lawfully 389 | be made without permission under this Public License. 390 | 391 | b. To the extent possible, if any provision of this Public License is 392 | deemed unenforceable, it shall be automatically reformed to the 393 | minimum extent necessary to make it enforceable. If the provision 394 | cannot be reformed, it shall be severed from this Public License 395 | without affecting the enforceability of the remaining terms and 396 | conditions. 397 | 398 | c. No term or condition of this Public License will be waived and no 399 | failure to comply consented to unless expressly agreed to by the 400 | Licensor. 401 | 402 | d. Nothing in this Public License constitutes or may be interpreted 403 | as a limitation upon, or waiver of, any privileges and immunities 404 | that apply to the Licensor or You, including from the legal 405 | processes of any jurisdiction or authority. 406 | 407 | 408 | ======================================================================= 409 | 410 | Creative Commons is not a party to its public licenses. 411 | Notwithstanding, Creative Commons may elect to apply one of its public 412 | licenses to material it publishes and in those instances will be 413 | considered the “Licensor.” The text of the Creative Commons public 414 | licenses is dedicated to the public domain under the CC0 Public Domain 415 | Dedication. Except for the limited purpose of indicating that material 416 | is shared under a Creative Commons public license or as otherwise 417 | permitted by the Creative Commons policies published at 418 | creativecommons.org/policies, Creative Commons does not authorize the 419 | use of the trademark "Creative Commons" or any other trademark or logo 420 | of Creative Commons without its prior written consent including, 421 | without limitation, in connection with any unauthorized modifications 422 | to any of its public licenses or any other arrangements, 423 | understandings, or agreements concerning use of licensed material. For 424 | the avoidance of doubt, this paragraph does not form part of the public 425 | licenses. 426 | 427 | Creative Commons may be contacted at creativecommons.org. 428 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line. 5 | SPHINXOPTS = 6 | SPHINXBUILD = sphinx-build 7 | PAPER = 8 | BUILDDIR = _build 9 | 10 | # User-friendly check for sphinx-build 11 | ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) 12 | $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) 13 | endif 14 | 15 | # Internal variables. 16 | PAPEROPT_a4 = -D latex_paper_size=a4 17 | PAPEROPT_letter = -D latex_paper_size=letter 18 | ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . 19 | # the i18n builder cannot share the environment and doctrees with the others 20 | I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . 21 | 22 | .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext 23 | 24 | help: 25 | @echo "Please use \`make ' where is one of" 26 | @echo " html to make standalone HTML files" 27 | @echo " dirhtml to make HTML files named index.html in directories" 28 | @echo " singlehtml to make a single large HTML file" 29 | @echo " pickle to make pickle files" 30 | @echo " json to make JSON files" 31 | @echo " htmlhelp to make HTML files and a HTML help project" 32 | @echo " qthelp to make HTML files and a qthelp project" 33 | @echo " devhelp to make HTML files and a Devhelp project" 34 | @echo " epub to make an epub" 35 | @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" 36 | @echo " latexpdf to make LaTeX files and run them through pdflatex" 37 | @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" 38 | @echo " text to make text files" 39 | @echo " man to make manual pages" 40 | @echo " texinfo to make Texinfo files" 41 | @echo " info to make Texinfo files and run them through makeinfo" 42 | @echo " gettext to make PO message catalogs" 43 | @echo " changes to make an overview of all changed/added/deprecated items" 44 | @echo " xml to make Docutils-native XML files" 45 | @echo " pseudoxml to make pseudoxml-XML files for display purposes" 46 | @echo " linkcheck to check all external links for integrity" 47 | @echo " doctest to run all doctests embedded in the documentation (if enabled)" 48 | 49 | clean: 50 | rm -rf $(BUILDDIR)/* 51 | 52 | html: 53 | $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html 54 | @echo 55 | @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." 56 | 57 | dirhtml: 58 | $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml 59 | @echo 60 | @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." 61 | 62 | singlehtml: 63 | $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml 64 | @echo 65 | @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." 66 | 67 | pickle: 68 | $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle 69 | @echo 70 | @echo "Build finished; now you can process the pickle files." 71 | 72 | json: 73 | $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json 74 | @echo 75 | @echo "Build finished; now you can process the JSON files." 76 | 77 | htmlhelp: 78 | $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp 79 | @echo 80 | @echo "Build finished; now you can run HTML Help Workshop with the" \ 81 | ".hhp project file in $(BUILDDIR)/htmlhelp." 82 | 83 | qthelp: 84 | $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp 85 | @echo 86 | @echo "Build finished; now you can run "qcollectiongenerator" with the" \ 87 | ".qhcp project file in $(BUILDDIR)/qthelp, like this:" 88 | @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/CitationStyleLanguage.qhcp" 89 | @echo "To view the help file:" 90 | @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/CitationStyleLanguage.qhc" 91 | 92 | devhelp: 93 | $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp 94 | @echo 95 | @echo "Build finished." 96 | @echo "To view the help file:" 97 | @echo "# mkdir -p $$HOME/.local/share/devhelp/CitationStyleLanguage" 98 | @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/CitationStyleLanguage" 99 | @echo "# devhelp" 100 | 101 | epub: 102 | $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub 103 | @echo 104 | @echo "Build finished. The epub file is in $(BUILDDIR)/epub." 105 | 106 | latex: 107 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 108 | @echo 109 | @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." 110 | @echo "Run \`make' in that directory to run these through (pdf)latex" \ 111 | "(use \`make latexpdf' here to do that automatically)." 112 | 113 | latexpdf: 114 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 115 | @echo "Running LaTeX files through pdflatex..." 116 | $(MAKE) -C $(BUILDDIR)/latex all-pdf 117 | @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." 118 | 119 | latexpdfja: 120 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 121 | @echo "Running LaTeX files through platex and dvipdfmx..." 122 | $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja 123 | @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." 124 | 125 | text: 126 | $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text 127 | @echo 128 | @echo "Build finished. The text files are in $(BUILDDIR)/text." 129 | 130 | man: 131 | $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man 132 | @echo 133 | @echo "Build finished. The manual pages are in $(BUILDDIR)/man." 134 | 135 | texinfo: 136 | $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 137 | @echo 138 | @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." 139 | @echo "Run \`make' in that directory to run these through makeinfo" \ 140 | "(use \`make info' here to do that automatically)." 141 | 142 | info: 143 | $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 144 | @echo "Running Texinfo files through makeinfo..." 145 | make -C $(BUILDDIR)/texinfo info 146 | @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." 147 | 148 | gettext: 149 | $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale 150 | @echo 151 | @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." 152 | 153 | changes: 154 | $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes 155 | @echo 156 | @echo "The overview file is in $(BUILDDIR)/changes." 157 | 158 | linkcheck: 159 | $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck 160 | @echo 161 | @echo "Link check complete; look for any errors in the above output " \ 162 | "or in $(BUILDDIR)/linkcheck/output.txt." 163 | 164 | doctest: 165 | $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest 166 | @echo "Testing of doctests in the sources finished, look at the " \ 167 | "results in $(BUILDDIR)/doctest/output.txt." 168 | 169 | xml: 170 | $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml 171 | @echo 172 | @echo "Build finished. The XML files are in $(BUILDDIR)/xml." 173 | 174 | pseudoxml: 175 | $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml 176 | @echo 177 | @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." 178 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Citation Style Language Documentation 2 | 3 | 8 | 9 | This is the official repository for documentation/specification of the Citation Style Language (CSL). 10 | The documentation is also viewable [as a formatted web page](https://docs.citationstyles.org/en/stable/specification.html). 11 | 12 | To recommend a change or clarification to the CSL documentation, please open an Issue or Pull Request in this repository. 13 | 14 | To recommend a change or new feature for CSL itself, please open an Issue or Pull Request on the [CSL Schema Repository](https://github.com/citation-style-language/schema). 15 | 16 | To report a bug in a specific application or citation processor, please use those projects' support avenues or post to [CSL forum](https://discourse.citationstyles.org/). 17 | 18 | For more information about CSL, visit . 19 | 20 | For general quesions and discussions, have a look at the [CSL forum](https://discourse.citationstyles.org/). 21 | 22 | ## Licensing 23 | 24 | This repository is released under the [CC-BY-SA-4.0 License](LICENSE.txt). 25 | -------------------------------------------------------------------------------- /attic/specification.rst: -------------------------------------------------------------------------------- 1 | translated-title 2 | Primary title of the item, translated into the lanugage of the citing document, often by the author of the citing document (e.g. "Handbook of industrial, work, and organizational psychology" for "Endüstri, iş ve örgüt psikolojisi: el kitabı") 3 | -------------------------------------------------------------------------------- /conf.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | # 3 | # Citation Style Language documentation build configuration file, created by 4 | # sphinx-quickstart on Mon Mar 9 22:40:07 2015. 5 | # 6 | # This file is execfile()d with the current directory set to its 7 | # containing dir. 8 | # 9 | # Note that not all possible configuration values are present in this 10 | # autogenerated file. 11 | # 12 | # All configuration values have a default; values that are commented out 13 | # serve to show the default. 14 | 15 | import sys 16 | import os 17 | 18 | # If extensions (or modules to document with autodoc) are in another directory, 19 | # add these directories to sys.path here. If the directory is relative to the 20 | # documentation root, use os.path.abspath to make it absolute, like shown here. 21 | #sys.path.insert(0, os.path.abspath('.')) 22 | 23 | # -- General configuration ------------------------------------------------ 24 | 25 | # If your documentation needs a minimal Sphinx version, state it here. 26 | #needs_sphinx = '1.0' 27 | 28 | # Add any Sphinx extension module names here, as strings. They can be 29 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 30 | # ones. 31 | extensions = [] 32 | 33 | # Add any paths that contain templates here, relative to this directory. 34 | templates_path = ['_templates'] 35 | 36 | # The suffix of source filenames. 37 | source_suffix = '.rst' 38 | 39 | # The encoding of source files. 40 | #source_encoding = 'utf-8-sig' 41 | 42 | # The master toctree document. 43 | master_doc = 'index' 44 | 45 | # General information about the project. 46 | project = u'Citation Style Language' 47 | copyright = u'2015, Rintze M. Zelle' 48 | 49 | # The version info for the project you're documenting, acts as replacement for 50 | # |version| and |release|, also used in various other places throughout the 51 | # built documents. 52 | # 53 | # The short X.Y version. 54 | version = '1.0.1-dev' 55 | # The full version, including alpha/beta/rc tags. 56 | release = '1.0.1-dev' 57 | 58 | # The language for content autogenerated by Sphinx. Refer to documentation 59 | # for a list of supported languages. 60 | #language = None 61 | 62 | # There are two options for replacing |today|: either, you set today to some 63 | # non-false value, then it is used: 64 | #today = '' 65 | # Else, today_fmt is used as the format for a strftime call. 66 | #today_fmt = '%B %d, %Y' 67 | 68 | # List of patterns, relative to source directory, that match files and 69 | # directories to ignore when looking for source files. 70 | exclude_patterns = ['_build'] 71 | 72 | # The reST default role (used for this markup: `text`) to use for all 73 | # documents. 74 | #default_role = None 75 | 76 | # If true, '()' will be appended to :func: etc. cross-reference text. 77 | #add_function_parentheses = True 78 | 79 | # If true, the current module name will be prepended to all description 80 | # unit titles (such as .. function::). 81 | #add_module_names = True 82 | 83 | # If true, sectionauthor and moduleauthor directives will be shown in the 84 | # output. They are ignored by default. 85 | #show_authors = False 86 | 87 | # The name of the Pygments (syntax highlighting) style to use. 88 | pygments_style = 'sphinx' 89 | 90 | # A list of ignored prefixes for module index sorting. 91 | #modindex_common_prefix = [] 92 | 93 | # If true, keep warnings as "system message" paragraphs in the built documents. 94 | #keep_warnings = False 95 | 96 | 97 | # -- Options for HTML output ---------------------------------------------- 98 | 99 | # The theme to use for HTML and HTML Help pages. See the documentation for 100 | # a list of builtin themes. 101 | html_theme = 'sphinx_rtd_theme' 102 | 103 | # Theme options are theme-specific and customize the look and feel of a theme 104 | # further. For a list of options available for each theme, see the 105 | # documentation. 106 | #html_theme_options = {} 107 | 108 | # Add any paths that contain custom themes here, relative to this directory. 109 | #html_theme_path = [] 110 | 111 | # The name for this set of Sphinx documents. If None, it defaults to 112 | # " v documentation". 113 | #html_title = None 114 | 115 | # A shorter title for the navigation bar. Default is the same as html_title. 116 | #html_short_title = None 117 | 118 | # The name of an image file (relative to this directory) to place at the top 119 | # of the sidebar. 120 | #html_logo = None 121 | 122 | # The name of an image file (within the static path) to use as favicon of the 123 | # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 124 | # pixels large. 125 | #html_favicon = None 126 | 127 | # Add any paths that contain custom static files (such as style sheets) here, 128 | # relative to this directory. They are copied after the builtin static files, 129 | # so a file named "default.css" will overwrite the builtin "default.css". 130 | html_static_path = ['_static'] 131 | 132 | # Add any extra paths that contain custom files (such as robots.txt or 133 | # .htaccess) here, relative to this directory. These files are copied 134 | # directly to the root of the documentation. 135 | #html_extra_path = [] 136 | 137 | # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, 138 | # using the given strftime format. 139 | #html_last_updated_fmt = '%b %d, %Y' 140 | 141 | # If true, SmartyPants will be used to convert quotes and dashes to 142 | # typographically correct entities. 143 | #html_use_smartypants = True 144 | 145 | # Custom sidebar templates, maps document names to template names. 146 | #html_sidebars = {} 147 | 148 | # Additional templates that should be rendered to pages, maps page names to 149 | # template names. 150 | #html_additional_pages = {} 151 | 152 | # If false, no module index is generated. 153 | #html_domain_indices = True 154 | 155 | # If false, no index is generated. 156 | #html_use_index = True 157 | 158 | # If true, the index is split into individual pages for each letter. 159 | #html_split_index = False 160 | 161 | # If true, links to the reST sources are added to the pages. 162 | #html_show_sourcelink = True 163 | 164 | # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. 165 | #html_show_sphinx = True 166 | 167 | # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. 168 | #html_show_copyright = True 169 | 170 | # If true, an OpenSearch description file will be output, and all pages will 171 | # contain a tag referring to it. The value of this option must be the 172 | # base URL from which the finished HTML is served. 173 | #html_use_opensearch = '' 174 | 175 | # This is the file name suffix for HTML files (e.g. ".xhtml"). 176 | #html_file_suffix = None 177 | 178 | # Output file base name for HTML help builder. 179 | htmlhelp_basename = 'CitationStyleLanguagedoc' 180 | 181 | 182 | # -- Options for LaTeX output --------------------------------------------- 183 | 184 | latex_elements = { 185 | # The paper size ('letterpaper' or 'a4paper'). 186 | #'papersize': 'letterpaper', 187 | 188 | # The font size ('10pt', '11pt' or '12pt'). 189 | #'pointsize': '10pt', 190 | 191 | # Additional stuff for the LaTeX preamble. 192 | #'preamble': '', 193 | } 194 | 195 | # Grouping the document tree into LaTeX files. List of tuples 196 | # (source start file, target name, title, 197 | # author, documentclass [howto, manual, or own class]). 198 | latex_documents = [ 199 | ('index', 'CitationStyleLanguage.tex', u'Citation Style Language Documentation', 200 | u'Rintze M. Zelle', 'manual'), 201 | ] 202 | 203 | # The name of an image file (relative to this directory) to place at the top of 204 | # the title page. 205 | #latex_logo = None 206 | 207 | # For "manual" documents, if this is true, then toplevel headings are parts, 208 | # not chapters. 209 | #latex_use_parts = False 210 | 211 | # If true, show page references after internal links. 212 | #latex_show_pagerefs = False 213 | 214 | # If true, show URL addresses after external links. 215 | #latex_show_urls = False 216 | 217 | # Documents to append as an appendix to all manuals. 218 | #latex_appendices = [] 219 | 220 | # If false, no module index is generated. 221 | #latex_domain_indices = True 222 | 223 | 224 | # -- Options for manual page output --------------------------------------- 225 | 226 | # One entry per manual page. List of tuples 227 | # (source start file, name, description, authors, manual section). 228 | man_pages = [ 229 | ('index', 'citationstylelanguage', u'Citation Style Language Documentation', 230 | [u'Rintze M. Zelle'], 1) 231 | ] 232 | 233 | # If true, show URL addresses after external links. 234 | #man_show_urls = False 235 | 236 | 237 | # -- Options for Texinfo output ------------------------------------------- 238 | 239 | # Grouping the document tree into Texinfo files. List of tuples 240 | # (source start file, target name, title, author, 241 | # dir menu entry, description, category) 242 | texinfo_documents = [ 243 | ('index', 'CitationStyleLanguage', u'Citation Style Language Documentation', 244 | u'Rintze M. Zelle', 'CitationStyleLanguage', 'One line description of project.', 245 | 'Miscellaneous'), 246 | ] 247 | 248 | # Documents to append as an appendix to all manuals. 249 | #texinfo_appendices = [] 250 | 251 | # If false, no module index is generated. 252 | #texinfo_domain_indices = True 253 | 254 | # How to display URL addresses: 'footnote', 'no', or 'inline'. 255 | #texinfo_show_urls = 'footnote' 256 | 257 | # If true, do not generate a @detailmenu in the "Top" node's menu. 258 | #texinfo_no_detailmenu = False 259 | -------------------------------------------------------------------------------- /index.rst: -------------------------------------------------------------------------------- 1 | .. Citation Style Language documentation master file, created by 2 | sphinx-quickstart on Mon Mar 9 22:40:07 2015. 3 | You can adapt this file completely to your liking, but it should at least 4 | contain the root `toctree` directive. 5 | 6 | Citation Style Language - Documentation 7 | ======================================= 8 | 9 | .. toctree:: 10 | :maxdepth: 1 11 | 12 | primer 13 | translating-locale-files 14 | specification 15 | -------------------------------------------------------------------------------- /make.bat: -------------------------------------------------------------------------------- 1 | @ECHO OFF 2 | 3 | REM Command file for Sphinx documentation 4 | 5 | if "%SPHINXBUILD%" == "" ( 6 | set SPHINXBUILD=sphinx-build 7 | ) 8 | set BUILDDIR=_build 9 | set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . 10 | set I18NSPHINXOPTS=%SPHINXOPTS% . 11 | if NOT "%PAPER%" == "" ( 12 | set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% 13 | set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% 14 | ) 15 | 16 | if "%1" == "" goto help 17 | 18 | if "%1" == "help" ( 19 | :help 20 | echo.Please use `make ^` where ^ is one of 21 | echo. html to make standalone HTML files 22 | echo. dirhtml to make HTML files named index.html in directories 23 | echo. singlehtml to make a single large HTML file 24 | echo. pickle to make pickle files 25 | echo. json to make JSON files 26 | echo. htmlhelp to make HTML files and a HTML help project 27 | echo. qthelp to make HTML files and a qthelp project 28 | echo. devhelp to make HTML files and a Devhelp project 29 | echo. epub to make an epub 30 | echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter 31 | echo. text to make text files 32 | echo. man to make manual pages 33 | echo. texinfo to make Texinfo files 34 | echo. gettext to make PO message catalogs 35 | echo. changes to make an overview over all changed/added/deprecated items 36 | echo. xml to make Docutils-native XML files 37 | echo. pseudoxml to make pseudoxml-XML files for display purposes 38 | echo. linkcheck to check all external links for integrity 39 | echo. doctest to run all doctests embedded in the documentation if enabled 40 | goto end 41 | ) 42 | 43 | if "%1" == "clean" ( 44 | for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i 45 | del /q /s %BUILDDIR%\* 46 | goto end 47 | ) 48 | 49 | 50 | %SPHINXBUILD% 2> nul 51 | if errorlevel 9009 ( 52 | echo. 53 | echo.The 'sphinx-build' command was not found. Make sure you have Sphinx 54 | echo.installed, then set the SPHINXBUILD environment variable to point 55 | echo.to the full path of the 'sphinx-build' executable. Alternatively you 56 | echo.may add the Sphinx directory to PATH. 57 | echo. 58 | echo.If you don't have Sphinx installed, grab it from 59 | echo.http://sphinx-doc.org/ 60 | exit /b 1 61 | ) 62 | 63 | if "%1" == "html" ( 64 | %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html 65 | if errorlevel 1 exit /b 1 66 | echo. 67 | echo.Build finished. The HTML pages are in %BUILDDIR%/html. 68 | goto end 69 | ) 70 | 71 | if "%1" == "dirhtml" ( 72 | %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml 73 | if errorlevel 1 exit /b 1 74 | echo. 75 | echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. 76 | goto end 77 | ) 78 | 79 | if "%1" == "singlehtml" ( 80 | %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml 81 | if errorlevel 1 exit /b 1 82 | echo. 83 | echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. 84 | goto end 85 | ) 86 | 87 | if "%1" == "pickle" ( 88 | %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle 89 | if errorlevel 1 exit /b 1 90 | echo. 91 | echo.Build finished; now you can process the pickle files. 92 | goto end 93 | ) 94 | 95 | if "%1" == "json" ( 96 | %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json 97 | if errorlevel 1 exit /b 1 98 | echo. 99 | echo.Build finished; now you can process the JSON files. 100 | goto end 101 | ) 102 | 103 | if "%1" == "htmlhelp" ( 104 | %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp 105 | if errorlevel 1 exit /b 1 106 | echo. 107 | echo.Build finished; now you can run HTML Help Workshop with the ^ 108 | .hhp project file in %BUILDDIR%/htmlhelp. 109 | goto end 110 | ) 111 | 112 | if "%1" == "qthelp" ( 113 | %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp 114 | if errorlevel 1 exit /b 1 115 | echo. 116 | echo.Build finished; now you can run "qcollectiongenerator" with the ^ 117 | .qhcp project file in %BUILDDIR%/qthelp, like this: 118 | echo.^> qcollectiongenerator %BUILDDIR%\qthelp\CitationStyleLanguage.qhcp 119 | echo.To view the help file: 120 | echo.^> assistant -collectionFile %BUILDDIR%\qthelp\CitationStyleLanguage.ghc 121 | goto end 122 | ) 123 | 124 | if "%1" == "devhelp" ( 125 | %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp 126 | if errorlevel 1 exit /b 1 127 | echo. 128 | echo.Build finished. 129 | goto end 130 | ) 131 | 132 | if "%1" == "epub" ( 133 | %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub 134 | if errorlevel 1 exit /b 1 135 | echo. 136 | echo.Build finished. The epub file is in %BUILDDIR%/epub. 137 | goto end 138 | ) 139 | 140 | if "%1" == "latex" ( 141 | %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex 142 | if errorlevel 1 exit /b 1 143 | echo. 144 | echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. 145 | goto end 146 | ) 147 | 148 | if "%1" == "latexpdf" ( 149 | %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex 150 | cd %BUILDDIR%/latex 151 | make all-pdf 152 | cd %BUILDDIR%/.. 153 | echo. 154 | echo.Build finished; the PDF files are in %BUILDDIR%/latex. 155 | goto end 156 | ) 157 | 158 | if "%1" == "latexpdfja" ( 159 | %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex 160 | cd %BUILDDIR%/latex 161 | make all-pdf-ja 162 | cd %BUILDDIR%/.. 163 | echo. 164 | echo.Build finished; the PDF files are in %BUILDDIR%/latex. 165 | goto end 166 | ) 167 | 168 | if "%1" == "text" ( 169 | %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text 170 | if errorlevel 1 exit /b 1 171 | echo. 172 | echo.Build finished. The text files are in %BUILDDIR%/text. 173 | goto end 174 | ) 175 | 176 | if "%1" == "man" ( 177 | %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man 178 | if errorlevel 1 exit /b 1 179 | echo. 180 | echo.Build finished. The manual pages are in %BUILDDIR%/man. 181 | goto end 182 | ) 183 | 184 | if "%1" == "texinfo" ( 185 | %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo 186 | if errorlevel 1 exit /b 1 187 | echo. 188 | echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. 189 | goto end 190 | ) 191 | 192 | if "%1" == "gettext" ( 193 | %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale 194 | if errorlevel 1 exit /b 1 195 | echo. 196 | echo.Build finished. The message catalogs are in %BUILDDIR%/locale. 197 | goto end 198 | ) 199 | 200 | if "%1" == "changes" ( 201 | %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes 202 | if errorlevel 1 exit /b 1 203 | echo. 204 | echo.The overview file is in %BUILDDIR%/changes. 205 | goto end 206 | ) 207 | 208 | if "%1" == "linkcheck" ( 209 | %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck 210 | if errorlevel 1 exit /b 1 211 | echo. 212 | echo.Link check complete; look for any errors in the above output ^ 213 | or in %BUILDDIR%/linkcheck/output.txt. 214 | goto end 215 | ) 216 | 217 | if "%1" == "doctest" ( 218 | %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest 219 | if errorlevel 1 exit /b 1 220 | echo. 221 | echo.Testing of doctests in the sources finished, look at the ^ 222 | results in %BUILDDIR%/doctest/output.txt. 223 | goto end 224 | ) 225 | 226 | if "%1" == "xml" ( 227 | %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml 228 | if errorlevel 1 exit /b 1 229 | echo. 230 | echo.Build finished. The XML files are in %BUILDDIR%/xml. 231 | goto end 232 | ) 233 | 234 | if "%1" == "pseudoxml" ( 235 | %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml 236 | if errorlevel 1 exit /b 1 237 | echo. 238 | echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. 239 | goto end 240 | ) 241 | 242 | :end 243 | -------------------------------------------------------------------------------- /media/cc-by-sa-80x15.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/citation-style-language/documentation/19c7164dcb203497064044238e7c3a8ccb5ed070/media/cc-by-sa-80x15.png -------------------------------------------------------------------------------- /media/csl-infrastructure.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/citation-style-language/documentation/19c7164dcb203497064044238e7c3a8ccb5ed070/media/csl-infrastructure.png -------------------------------------------------------------------------------- /primer.rst: -------------------------------------------------------------------------------- 1 | Primer — An Introduction to CSL 2 | =============================== 3 | 4 | by `Rintze M. Zelle, PhD `_ 5 | 6 | | |CCBYSA|_ 7 | | This work is licensed under a `Creative Commons Attribution-ShareAlike 4.0 International License`__. 8 | 9 | .. |CCBYSA| image:: /media/cc-by-sa-80x15.png 10 | .. _CCBYSA: https://creativecommons.org/licenses/by-sa/4.0/ 11 | __ CCBYSA_ 12 | 13 | .. contents:: **Table of Contents** 14 | 15 | Preface 16 | ~~~~~~~ 17 | 18 | This primer is an introduction to the `Citation Style Language`_ (CSL), an open XML-based language to describe the formatting of citations and bibliographies. For a more technical and in-depth description of CSL, see the `CSL Specification`_. 19 | 20 | .. _Citation Style Language: http://citationstyles.org 21 | .. _CSL Specification: specification.html 22 | 23 | What is CSL? 24 | ~~~~~~~~~~~~ 25 | 26 | If you ever wrote a research paper, you probably included references to other works. Referencing is important in scholarly communication, as it provides attribution, and links together published research. However, manually formatting references can become very time-consuming, especially when you're dealing with multiple journals that each have their own citation style. 27 | 28 | Luckily, reference management software can help out. Programs like Zotero, Mendeley, and Papers not only help you manage your research library, but can also automatically generate citations and bibliographies. But to format references in the desired style, these programs need descriptions of each citation style in a language the computer can understand. As you might have guessed, the Citation Style Language (CSL) is such a language. 29 | 30 | Citation Formats 31 | ~~~~~~~~~~~~~~~~ 32 | 33 | There are hundreds, if not thousands of different citation styles in use around the world. Fortunately, most citation styles fall within a few basic categories. CSL distinguishes between the following types: 34 | 35 | In-text Styles 36 | ^^^^^^^^^^^^^^ 37 | 38 | Citation styles can be divided in two main categories. The first category consists of **in-text** styles, where a *citation* in the sentence directly points to one or multiple entries in the *bibliography*. CSL subdivides this category in **author-date**, **author**, **numeric** and **label** styles. 39 | 40 | Each citation points to one or more *bibliographic entries*. In CSL, each individual pointer is called a *cite*. For example, the citation "(Doe et al. 2002, Smith 1997)" contains two cites: one to a 2002 publication by Doe et al., and one to a 1997 publication by Smith. In the context of CSL, bibliographic entries are sometimes also called *references*. 41 | 42 | "author-date" & "author" Styles 43 | ''''''''''''''''''''''''''''''' 44 | 45 | Cites of **author-date** styles show author names and the date of publication, e.g. "(Van der Klei et al. 1991; Zwart et al. 1983)", whereas cites of **author** styles only show names, e.g. "(Gidijala et al.)". Bibliographic entries are typically sorted alphabetically by author. 46 | 47 | Note that many style guides use the confusing term "Harvard" to refer to **author-date** formats, even though most of these styles have no connection to Harvard University. There is also no such thing as a single official "Harvard" style. 48 | 49 | **Example Bibliography** 50 | 51 | Gidijala L, Bovenberg RA, Klaassen P, van der Klei IJ, Veenhuis M, et al. (2008) Production of functionally active *Penicillium chrysogenum* isopenicillin N synthase in the yeast *Hansenula polymorpha*. BMC Biotechnol 8: 29. 52 | 53 | van der Klei IJ, Harder W, Veenhuis M (1991) Methanol metabolism in a peroxisome-deficient mutant of *Hansenula polymorpha*: a physiological study. Arch Microbiol 156: 15-23. 54 | 55 | Zwart KB, Veenhuis M, Harder W (1983) Significance of yeast peroxisomes in the metabolism of choline and ethanolamine. Antonie van Leeuwenhoek 49: 369-385. 56 | 57 | "numeric" Styles 58 | '''''''''''''''' 59 | 60 | Cites of **numeric** styles consist of numbers, e.g. "[1, 2]" and "[3]". Bibliographic entries are typically sorted either alphabetically by author, or put in the order by which they have been first cited. 61 | 62 | **Example Bibliography** 63 | 64 | 1. Gidijala L, Bovenberg RA, Klaassen P, van der Klei IJ, Veenhuis M, et al. (2008) Production of functionally active *Penicillium chrysogenum* isopenicillin N synthase in the yeast *Hansenula polymorpha*. BMC Biotechnol 8: 29. 65 | 66 | 2. Zwart KB, Veenhuis M, Harder W (1983) Significance of yeast peroxisomes in the metabolism of choline and ethanolamine. Antonie van Leeuwenhoek 49: 369-385. 67 | 68 | 3. van der Klei IJ, Harder W, Veenhuis M (1991) Methanol metabolism in a peroxisome-deficient mutant of *Hansenula polymorpha*: a physiological study. Arch Microbiol 156: 15-23. 69 | 70 | "numeric" Compound Styles 71 | ''''''''''''''''''''''''' 72 | 73 | Compound styles are a variation of the **numeric** in-text style format. With these styles, popular in the field of chemistry, bibliographic entries may contain multiple references. Once a citation has defined such a bibliographic entry (e.g, "[2]"), it becomes possible to cite individual items within the entry (e.g., "[2b]"). This format is not yet supported by CSL. 74 | 75 | **Example Bibliography** 76 | 77 | 1. Gidijala L, et al. (2008) BMC Biotechnol 8: 29. 78 | 79 | 2. \a) Zwart KB, et al. (1983) Antonie van Leeuwenhoek 49: 369-385, b) van der Klei IJ, et al. (1991) Arch Microbiol 156: 15-23. 80 | 81 | "label" Styles 82 | '''''''''''''' 83 | 84 | Cites of **label** styles consist of short keys, e.g. "[GBKv2008]" and "[ZwVH1983; vaHV1991]". These keys are also included in the bibliographic entries. CSL has limited support for this format, since it currently doesn't allow for (style-specific) customisation of the key format. 85 | 86 | **Example Bibliography** 87 | 88 | [GBKv2008] Gidijala L, Bovenberg RA, Klaassen P, van der Klei IJ, Veenhuis M, et al. (2008) Production of functionally active *Penicillium chrysogenum* isopenicillin N synthase in the yeast *Hansenula polymorpha*. BMC Biotechnol 8: 29. 89 | 90 | [vaHV1991] van der Klei IJ, Harder W, Veenhuis M (1991) Methanol metabolism in a peroxisome-deficient mutant of *Hansenula polymorpha*: a physiological study. Arch Microbiol 156: 15-23. 91 | 92 | [ZwVH1983] Zwart KB, Veenhuis M, Harder W (1983) Significance of yeast peroxisomes in the metabolism of choline and ethanolamine. Antonie van Leeuwenhoek 49: 369-385. 93 | 94 | Note Styles 95 | ^^^^^^^^^^^ 96 | 97 | The second category of citation styles consists of **note** styles. Here a *marker*, which can be a number or a symbol, is added to the sentence when works are cited, e.g. "[*]_" and "[*]_". Each marker points to a footnote or endnote. CSL styles do not control which number formats or symbols are used for the markers, which is left to the word processor. In contrast to **in-text** citations, footnotes and endnotes typically contain all information required to identify the cited works. Some **note** styles include a bibliography to give an overview of all cited works, and to describe the works in more detail. 98 | 99 | .. [*] 'Voyage to St. Kilda' (3rd edit. 1753), p. 37. 100 | .. [*] Sir J. E. Tennent, 'Ceylon,' vol. ii. 1859, p. 107. 101 | 102 | The CSL Ecosystem 103 | ~~~~~~~~~~~~~~~~~ 104 | 105 | To understand how CSL works, let's start by taking a look at the various bits and pieces of the CSL ecosystem: 106 | 107 | |csl-infrastructure| 108 | 109 | .. |csl-infrastructure| image:: /media/csl-infrastructure.png 110 | :width: 257pt 111 | 112 | Independent and Dependent Styles 113 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 114 | 115 | Styles! Everything in the world of CSL revolves around styles. But not all CSL styles are alike. There are two types: **independent styles** and **dependent styles**. 116 | 117 | An **independent CSL style** has two functions: first, it needs to define a citation format. What does the format look like? Is it an "author-date" style, or a "note" style? Are cites ordered alphabetically, or by date? Should bibliographic entries include DOIs? What punctuation and capitalization should be used? Does the year of publication come before or after the title? Etcetera, etcetera. Secondly, the CSL style must describe itself. We call this self-describing information **style metadata**, and it can include the title of the journal for which the CSL style was created, a link to that journal's website, the name of the creator of the CSL style, etc. 118 | 119 | A **dependent CSL style**, on the other hand, only contains **style metadata**. Instead of providing a definition of a citation format, a dependent style simply refers to an independent CSL style (its "parent"), whose citation format will be used instead. 120 | 121 | Dependent styles come in handy when multiple CSL styles share the same citation format. Take a publisher which uses a single citation format for all its journals. If we were limited to using independent CSL styles, every journal's CSL style would need to contain a full definition of the citation format, even though it would be the same for each journal. This would produce a collection of bulky styles that are hard to maintain. If the publisher makes a change to its citation format, we would have to update every single independent CSL style. 122 | 123 | Dependent styles solve these problems. For example, the journals "Nature Biotechnology", "Nature Chemistry", and "Nature" all use the same citation format. We therefore created dependent CSL styles for "Nature Biotechnology" and "Nature Chemistry" that both point to our independent CSL style for "Nature". Since they don't define a citation format, dependent styles are a fraction of the size of an independent style. And, if the Nature Publishing Group ever decides to change the "Nature" citation format across its journals, we only have to correct the citation format in the "Nature" CSL style, without having to touch any of its dependents. 124 | 125 | Locale Files 126 | ^^^^^^^^^^^^ 127 | 128 | I have a little secret to share with you: most independent styles aren't fully independent. 129 | 130 | Take the reference below: 131 | 132 | Hartman, P., Bezos, J. P., Kaphan, S., & Spiegel, J. (1999, September 28). Method and system for placing a purchase order via a communications network. Retrieved from https://www.google.com/patents/US5960411 133 | 134 | You can describe this citation format in an independent CSL style by hard-coding all language-specific information into the style. For example, you can put the text "Retrieved from" before the URL, and use "YYYY, Month DD" as the date format. However, such a style would only be usable in US English. If you later need a German variant of this citation format, you would have to change all the translations and date formats within the style. 135 | 136 | Fortunately, independent CSL styles can rely on the CSL **locale files** for translations of common terms, localized date formats, and grammar. For example, we can rewrite our CSL style to use the "retrieved" and "from" CSL terms, and to use the localized "text" date format. If we then set the locale of the style to US English, this style will retrieve the term translations and localized date format from the US English CSL locale file, which will produce the reference as written above. But if we switch the style locale to German, the German locale file will be used instead, producing: 137 | 138 | Hartman, P., Bezos, J. P., Kaphan, S., & Spiegel, J. (28. September 1999). Method and system for placing a purchase order via a communications network. Abgerufen von https://www.google.com/patents/US5960411 139 | 140 | So with CSL locale files, it becomes possible to write CSL styles that are largely language-agnostic. As illustrated above, such styles can easily switch between different languages. However, languages are complex, and CSL's automatic localization doesn't support the peculiarities of all languages for which we have locale files. But even if you find that you need to modify a CSL style to adapt it to your language of preference, language-agnostic styles have value, since they're easier to translate. 141 | 142 | Locale files have the added benefit that we only need to define common translations, date formats, and grammar once per language. This keeps styles compact, and makes locale data easier to maintain. Since citation formats for a given language don't always agree on a translation or date format, CSL styles can selectively overwrite any locale data that is defined in the locale files. 143 | 144 | Item Metadata 145 | ^^^^^^^^^^^^^ 146 | 147 | Next up are the bibliographic details of the items you wish to cite: the **item metadata**. 148 | 149 | For example, the bibliographic entry for a journal article may show the names of the authors, the year in which the article was published, the article title, the journal title, the volume and issue in which the article appeared, the page numbers of the article, and the article's Digital Object Identifier (DOI). All these details help the reader identify and find the referenced work. 150 | 151 | Reference managers make it easy to create a library of items. While many reference managers have their own way of storing item metadata, most support common bibliographic exchange formats such as BibTeX and RIS. The citeproc-js CSL processor introduced a JSON-based format for storing item metadata in a way citeproc-js could understand. Several other CSL processors have since adopted this "CSL JSON" format (also known as "citeproc JSON"). 152 | 153 | Citing Details 154 | ^^^^^^^^^^^^^^ 155 | 156 | For a given citation format, the way citations and bibliographies look not only depends on the metadata of the cited items, but also on the context in which these items are cited. We refer to this type of context-specific information as the **citing details**. 157 | 158 | For instance, the order in which items are cited in a document can affect their order in the bibliography. And in "note" styles, subsequent cites to a previously cited item are often written in a more compact form. Another example is the use of locators, which guide the reader to a specific location within a cited work, such as the page numbers within a chapter where a certain argument is made, e.g. "(Doe 2000, pp. 43-44)". 159 | 160 | CSL Processors 161 | ^^^^^^^^^^^^^^ 162 | 163 | With CSL styles, locale files, item metadata and citing details in hand, we now need a piece of software to parse all this information, and generate citations and bibliographies in the correct format: the **CSL processor**. 164 | 165 | Most reference managers use one of the freely available open source CSL processors, such as citeproc-js. 166 | 167 | Understanding CSL Styles 168 | ~~~~~~~~~~~~~~~~~~~~~~~~ 169 | 170 | By now you've learned what CSL is, how it can be used, and how its different parts and pieces fit together. We're now ready to dive into the CSL styles themselves, and look at their XML code. 171 | 172 | XML Basics 173 | ^^^^^^^^^^ 174 | 175 | If you're new to XML, this section gives a short overview of what you need to know about XML in order to read and edit CSL styles and locale files. For more background, just check one of the many XML tutorials online. 176 | 177 | Let's take a look at the following dependent CSL style: 178 | 179 | .. sourcecode:: xml 180 | 181 | 182 | 198 | 199 | There are several concepts and terms you need to be familiar with. These are: 200 | 201 | - **XML Declaration**. The first line of each style and locale file is usually the XML declaration. In most cases, this will be ````. This declaration makes it clear that the document consists of XML, and specifies the XML version ("1.0") and character encoding ("utf-8") used. 202 | 203 | - **Elements and Hierarchy**. Elements are the basic building blocks of XML documents. Each XML document contains a single root element (for CSL styles this is ````). In our example, the ````). Child elements are typically indented with spaces or tabs to show the different hierarchical levels. We use 2 spaces per level in our CSL styles and locale files. 206 | 207 | In the rest of this primer we will use the prefix "cs:" when referring to CSL elements (e.g., ``cs:style`` instead of `` 249 | 250 | The start and end tags of the ``cs:style`` root element. Its ``xmlns`` attribute specifies that all elements in the style are part of CSL, while the ``version`` attribute indicates CSL version compatibility. The ``default-locale`` attribute tells the style to generate citations and bibliographies in a certain language (in this case US English). 251 | 252 | .. sourcecode:: xml 253 | 254 | 255 | 256 | Most of our dependent styles are automatically generated from spreadsheet data. This XML comment makes it clear that this style has been generated, and contains a link to the spreadsheet. 257 | 258 | .. sourcecode:: xml 259 | 260 | 261 | ... 262 | 263 | 264 | The ``cs:info`` section is used to store most of the style's metadata. 265 | 266 | .. sourcecode:: xml 267 | 268 | Applied and Environmental Microbiology 269 | 270 | The title of the style. 271 | 272 | .. sourcecode:: xml 273 | 274 | http://www.zotero.org/styles/applied-and-environmental-microbiology 275 | 276 | The style ID, which is used by reference managers to identify styles and tell them apart. 277 | 278 | .. sourcecode:: xml 279 | 280 | 281 | 282 | The style's "self" link. This URL links to an online copy of the style. For simplicity, we use the same URL as style ID and "self" link for our repository styles. 283 | 284 | .. sourcecode:: xml 285 | 286 | 287 | 288 | Dependent styles need to link to an independent parent style, whose citation format will be used. Here we use the citation format from the CSL style for the American Society for Microbiology. 289 | 290 | .. sourcecode:: xml 291 | 292 | 293 | 294 | It's much easier to maintain our collection of CSL styles if each style's purpose is clear. We therefore require that all our repository styles contain at least one "documentation" link. In this case, to the journal's home page. 295 | 296 | .. sourcecode:: xml 297 | 298 | 299 | 300 | 301 | To help cataloguing our styles, we specify the citation format with the ``citation-format`` attribute on ``cs:category``. Similarly, we assign each style to one or more fields of study, using the ``field`` attribute. 302 | 303 | .. sourcecode:: xml 304 | 305 | 0099-2240 306 | 1098-5336 307 | 308 | When a CSL styles is created for a journal, we store the journal's print ISSN and electronic ISSN in the ``cs:issn`` and ``cs:eissn`` elements, respectively. 309 | 310 | .. sourcecode:: xml 311 | 312 | 2014-04-30T03:45:36+00:00 313 | 314 | A time stamp to indicate when the style was last updated. 315 | 316 | .. sourcecode:: xml 317 | 318 | This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 License 319 | 320 | Last, but certainly not least, the license under which the style is released. 321 | 322 | Anatomy of an Independent Style 323 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 324 | 325 | Finally, a real independent CSL style, one that actually defines a citation format! Well, okay, maybe it's not exactly a realistic style. Most independent styles in our repository are quite a bit bigger than the simplified example style below. But our "author-date" style below is valid CSL, and still has the same overall design as any other independent style. 326 | 327 | .. sourcecode:: xml 328 | 329 | 330 | 409 | 410 | Style Structure 411 | ''''''''''''''' 412 | 413 | To understand the style above, lets first look at the child elements of the ``cs:style`` root element: 414 | 415 | .. sourcecode:: xml 416 | 417 | 418 | 426 | 427 | Compared to a dependent style, which only has the ``cs:info`` child element, we see several additional elements here. In additional to ``cs:info``, we see ``cs:locale``, ``cs:macro``, ``cs:citation``, and ``cs:bibliography``. 428 | 429 | What do these elements do? 430 | 431 | - The required ``cs:info`` element fulfills the same function in independent styles as it does in dependent styles: it stores the style metadata. 432 | - The optional ``cs:locale`` elements can be used to overwrite the locale data from the locale files. 433 | - The optional ``cs:macro`` elements can be used to store CSL code for use by ``cs:citation``, ``cs:bibliography``, or other ``cs:macro`` elements. 434 | - The required ``cs:citation`` element defines the format of citations. 435 | - The optional ``cs:bibliography`` element defines the format of the bibliography. 436 | 437 | With this in mind, let's step through the style, starting with the ``cs:style`` element. 438 | 439 | ``cs:style`` Root Element 440 | ''''''''''''''''''''''''' 441 | 442 | .. sourcecode:: xml 443 | 444 | 447 | 448 | We've already come across the ``xmlns`` and ``version`` attributes when we looked at the ``cs:style`` element of our dependent style. The ``class`` attribute is new. It tells the CSL processor whether it is an "in-text" or "note" style. 449 | 450 | ``cs:info`` Element 451 | ''''''''''''''''''' 452 | 453 | The style metadata for independent styles is usually more expansive than for dependent styles: 454 | 455 | .. sourcecode:: xml 456 | 457 | 458 | Example Style 459 | http://www.zotero.org/styles/example 460 | 461 | 462 | 463 | 464 | John Doe 465 | JohnDoe@example.com 466 | 467 | 468 | Jane Doe 469 | 470 | 471 | Bill Johnson 472 | 473 | 474 | 475 | 2014-10-15T18:17:09+00:00 476 | This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 License 477 | 478 | 479 | The title, style ID, "self" link, categories, time stamp, and license work the same, but there are differences. First, independent styles don't depend on a parent style. Instead we usually provide a "template" link to indicate which style was used as a starting point for creating the current style (CSL styles are rarely written from scratch, since it's usually much faster to adapt an existing one). In this case, the template was the APA style. We also like to include one or more "documentation" links that point to an online description of the citation format in question. 480 | 481 | To acknowledge the creators of CSL styles, their names and contact information can be added to the style. In this case, we have one author and two contributors. Authors usually have done most of the work in creating the style, whereas contributors have provided small improvements. 482 | 483 | ``cs:citation`` and ``cs:macro`` Elements 484 | ''''''''''''''''''''''''''''''''''''''''' 485 | 486 | Let's jump down now to the macros and ``cs:citation`` element. The purpose of the ``cs:citation`` element is to describe the format of citations (or, for "note" styles, the format of footnotes or endnotes). 487 | 488 | .. sourcecode:: xml 489 | 490 | 491 | 492 | 493 | 494 | 495 | 496 | 497 | 498 | 499 | 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 509 | 510 | 511 | 512 | 513 | 514 | 515 | 516 | 517 | 518 | 519 | 520 | The code above generates citations like "(A.C. Smith et al., 2002; W. Wallace, J. Snow, 1999)". To understand how this citation format is encoded in CSL, let's first focus on the ``cs:layout`` element of ``cs:citation``. Its ``prefix`` and ``suffix`` attributes define the parentheses around the citation, while the value of the ``delimiter`` attribute ("; ") separates neighboring cites. The format of each individual cite is defined by the contents of ``cs:layout``, which consists of the output of the "author" and "issued-year" macros, separated by the value of the "delimiter" attribute (", ") on the ``cs:group`` element. 521 | 522 | The "author" macro prints the names stored in the "author" name variable of the cited item. The ``initialize-with`` attribute on ``cs:name`` specifies that given names should appear as initials, and that each initial is followed by the attribute's value ("."). 523 | 524 | The "issued-year" macro starts with a test, defined with the ``cs:choose`` element. If the cited item has a date stored in its "issued" date variable, the year of this date is printed. Otherwise, the style prints the value of the "no date" term. 525 | 526 | You might wonder why we didn't just put the CSL code from the two macros directly into the ``cs:citation`` element. What are the advantages of using macros? Well, in the example above, the use of macros simplifies the structure of ``cs:citation``, making it easier to follow. In addition, both macros are called a total of four times in the style (twice in ``cs:citation``, and twice in ``cs:bibliography``). Without macros, we'd have to repeat the CSL code of these macros multiple times. Macros thus allow for more compact styles. 527 | 528 | We're not done yet. The ``cs:citation`` element carries two attributes, ``et-al-min`` and ``et-al-use-first``. Together, they specify that if an item has three or more "author" names, only the first name is printed, followed by the value of the "et al" term. 529 | 530 | Finally, ``cs:citation`` contains the ``cs:sort`` element, which itself contains two ``cs:key`` elements. This section specifies how cites within a citation are sorted. The first sorting key consists of the output of the "author" macro (CSL is smart enough to sort names by the family name first, and by initials second). Any cites with the same output for the first key are then sorted by the second sorting key, which is the output of the "issue-year" macro. 531 | 532 | ``cs:bibliography`` Element 533 | ''''''''''''''''''''''''''' 534 | 535 | Whereas ``cs:citation`` is responsible for citations and cites, the ``cs:bibliography`` element is used to define the format of bibliographic entries. 536 | 537 | .. sourcecode:: xml 538 | 539 | 540 | 541 | 542 | 543 | 544 | 545 | 546 | 547 | 548 | 549 | 550 | 551 | 552 | 553 | 554 | 555 | 556 | ... 557 | 558 | 559 | 560 | 561 | 562 | 563 | 564 | 565 | 566 | 567 | 568 | 569 | 570 | 571 | 572 | 573 | 574 | 575 | 576 | 577 | 578 | The ``cs:bibliography`` section of our example style really only works well for a single type of items: journal articles. It generates bibliographic entries in the form of: 579 | 580 | A.C. Smith, D. Williams, T. Johnson. 2002. Story of my life. Journal of Biographies, 12(2), 24—27. 581 | W. Wallace, J. Snow. 1999. Winter is coming. Journal of Climate Dynamics, 6(9), 97—102. 582 | 583 | How were we able to define this format? First, the structure of ``cs:bibliography`` is very similar to that of ``cs:citation``, but here ``cs:layout`` defines the format of each individual bibliographic entry. In addition to the "author" and "issued-year" macro, the bibliographic entries also show each item's "title" and "container-title" (for journal articles, the "container-title" is the title of the journal), the "volume" and "issue" in which the article was printed, and the pages ("page") on which the article appeared. The style uses the ``prefix`` and ``suffix`` attributes to wrap the journal issue number in parentheses, and relies on the ``suffix`` and ``delimiter`` attributes on the ``cs:layout`` and ``cs:group`` elements to place the rest of the punctuation. 584 | 585 | The ``cs:bibliography`` element also contains a ``cs:sort`` element, with three keys: the "author" and "issued-year" macros, and, as a third key, the item's "title". 586 | 587 | ``cs:locale`` Element 588 | ''''''''''''''''''''' 589 | 590 | The last section of our style is ``cs:locale``. As we wrote above, CSL locale files allow CSL styles to quickly translate into different languages. However, sometimes it's desirable to overwrite the default translations. 591 | 592 | .. sourcecode:: xml 593 | 594 | 595 | 596 | without date 597 | 598 | 599 | 600 | The translation for the "no date" term in the CSL locale file for US English is, not very surprising, "no date". However, for our example style, I wanted to use "without date" instead. To overwrite the default translation, we can use the ``cs:locale`` element as shown above. For an item without an issued date, this would result in a citation like "(D. Williams, without date)". 601 | 602 | The ``xml:lang`` attribute on ``cs:locale`` is set to "en", which tells the style to overwrite the "no date" translation whenever the style is used in English. If we used the style in German, the style would still print the translation from the German locale file ("ohne Datum"). 603 | 604 | Diving Deeper 605 | ~~~~~~~~~~~~~ 606 | 607 | You finished the primer. Good job! If you're interested in learning more about CSL, you're now well prepared to start reading the `CSL Specification`_ and our other documentation on the `Citation Style Language`_ website. 608 | 609 | Feedback 610 | ~~~~~~~~ 611 | 612 | Questions or feedback? Contact us on Twitter at `@csl_styles`_. 613 | 614 | .. _@csl_styles: https://twitter.com/csl_styles 615 | -------------------------------------------------------------------------------- /translating-locale-files.rst: -------------------------------------------------------------------------------- 1 | Guide to Translating CSL Locale Files 2 | ===================================== 3 | 4 | by `Rintze M. Zelle, PhD `_ 5 | 6 | | |CCBYSA|_ 7 | | This work is licensed under a `Creative Commons Attribution-ShareAlike 4.0 International License`__. 8 | 9 | .. |CCBYSA| image:: /media/cc-by-sa-80x15.png 10 | .. _CCBYSA: https://creativecommons.org/licenses/by-sa/4.0/ 11 | __ CCBYSA_ 12 | 13 | .. contents:: **Table of Contents** 14 | 15 | Preface 16 | ~~~~~~~ 17 | 18 | This document describes how you can help us improve the language support of 19 | Citation Style Language (CSL) styles by translating the CSL locale file of your 20 | favorite language. 21 | 22 | CSL styles are either bound to one particular locale (e.g. the "British 23 | Psychological Society" CSL style will always produce citations and 24 | bibliographies in British English), or they (automatically) localize, e.g. to a 25 | user-selected locale, or to the locale of the user's operating system. 26 | 27 | All CSL styles, both those with and without a fixed locale, rely on locale files 28 | for default localization data, which consists of translated terms commonly used 29 | in citations and bibliographies, date formats, and grammar rules. Storing 30 | localization data in separate files has several benefits: translations are 31 | easier to maintain, styles are more compact (although styles can still include 32 | their own localization data to override the defaults), and styles can be 33 | (mostly) language-agnostic. 34 | 35 | Below we will describe the structure of a locale file, give instructions on how 36 | to translate all its parts, and explain how you can submit your translations. 37 | See the `CSL specification 38 | `_ for more in-depth 39 | documentation on the structure and function of locale files. 40 | 41 | Getting Started 42 | ~~~~~~~~~~~~~~~ 43 | 44 | The CSL locale files are kept in a GitHub repository at 45 | https://github.com/citation-style-language/locales/. 46 | 47 | Each locale file contains the localization data for one language. Locale files 48 | are named "locales-xx-XX.xml", where "xx-XX" is a `BCP 47 language code 49 | `_ (e.g. the locale code 50 | for British English is "en-GB"). The `repository wiki 51 | `_ lists the locale 52 | code, language, and translation status of all locale files in the repository. 53 | 54 | If you find that a locale file already exists for your language, but that its 55 | translations are inaccurate or incomplete, you can start translating that file. 56 | If there is no locale file for your language, copy the "locales-en-US.xml" file 57 | and start from there. Don't worry about finding the correct BCP 47 locale code 58 | for a new language; we'll be happy to look it up when you submit your new locale 59 | file. 60 | 61 | Modifications to existing locale files can be made directly via the GitHub 62 | website. New locale files can be submitted as a "gist" or through a pull 63 | request. For details, see the `instructions on submitting CSL styles 64 | `_. If 65 | you edit a locale file on your own computer, use a suitable plain text editor 66 | such as TextWrangler for OS X, Notepad++ for Windows, or jEdit. 67 | 68 | Translating Locale Files 69 | ~~~~~~~~~~~~~~~~~~~~~~~~ 70 | 71 | When translating locale files, leave the overall structure of the locale file 72 | untouched. It makes life easier for us if you don't remove existing elements, 73 | introduce new ones, or move stuff around (exceptions are discussed below). 74 | 75 | xml:lang 76 | ^^^^^^^^ 77 | 78 | At the top of the locale file you'll find the ``locale`` root element. The value 79 | of its ``xml:lang`` attribute should be set to the same language code used in 80 | the file name of the locale file. For the locales-en-US.xml locale file, this is 81 | "en-US": 82 | 83 | .. sourcecode:: xml 84 | 85 | 86 | 87 | 88 | Locale File Metadata 89 | ^^^^^^^^^^^^^^^^^^^^ 90 | 91 | Directly below the ``locale`` root you'll find an ``info`` element. Here you can 92 | list yourself as a translator using the ``translator`` element. Optionally you 93 | can include contact information such as a website or email address. A locale 94 | file can list multiple translators. The ``rights`` element indicates under which 95 | license the locale file is released. All locale files in our repository use the 96 | same Creative Commons license, so you don't have to change anything here. The 97 | ``updated`` element is used to keep track of when the locale file was last 98 | updated. Feel free to ignore it if the format looks too intimidating. 99 | 100 | .. sourcecode:: xml 101 | 102 | 103 | 104 | John Doe 105 | john.doe@citationstyles.org 106 | http://citationstyles.org/ 107 | 108 | This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 License 109 | 2012-07-04T23:31:02+00:00 110 | 111 | 112 | Grammar Rules 113 | ^^^^^^^^^^^^^ 114 | 115 | Next up is the ``style-options`` element: 116 | 117 | .. sourcecode:: xml 118 | 119 | 120 | 121 | This element is used to define localized grammar rules, as described in the 122 | `Locale Options 123 | `_ 124 | section in the CSL specification. 125 | 126 | Date Formats 127 | ^^^^^^^^^^^^ 128 | 129 | CSL styles can render dates in either non-localizing or localizing formats: 130 | 131 | .. sourcecode:: xml 132 | 133 | 150 | 151 | Each locale file defines two localized date formats: a numeric format (e.g. 152 | "2012/9/3"), and a textual format, where the month is written out in full (e.g. 153 | "September 3, 2012"). 154 | 155 | To localize a date format, place the date-part elements for "day", "month", and 156 | "year" in the desired order. Use the ``prefix`` and ``suffix`` attributes (on 157 | the ``date-part`` elements), or the ``delimiter`` attribute (on the ``date`` 158 | element) to define punctuation before, after, and between the different 159 | date-parts. When using affixes, make sure that dates that only consist of a year 160 | and a month, or of only a year, still render correctly. For example, the US 161 | English localized "text" date format, 162 | 163 | .. sourcecode:: xml 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | will produce dates like "September 3, 2012", "September 2012", and "2012". 172 | Compare this to 173 | 174 | .. sourcecode:: xml 175 | 176 | 177 | 178 | 179 | 180 | 181 | 182 | which gives the same correct complete date ("September 3, 2012"), but which 183 | produces incorrect output for dates that don't have a day, or don't have a day 184 | and month ("September, 2012" and ", 2012", respectively). 185 | 186 | To read more about customizing date formats, see the `Localized Date Formats 187 | `_ 188 | and `Date-part 189 | `_ sections in 190 | the CSL specification. 191 | 192 | Terms 193 | ^^^^^ 194 | 195 | The ``terms`` element makes up the last section of the locale file, and contains 196 | all the term translations. Below we discuss the different types of terms, and 197 | how to translate them. 198 | 199 | In its simplest form, a term consists only of a ``term`` element with the 200 | ``name`` attribute indicating the term name, and with the translation enclosed 201 | between the start and end tag: 202 | 203 | .. sourcecode:: xml 204 | 205 | 206 | et al. 207 | 208 | 209 | See the `Terms `_ 210 | section in the CSL specification. 211 | 212 | 213 | Abbreviations 214 | ''''''''''''' 215 | 216 | When translating abbreviations such as "et al.", always include periods where 217 | applicable. 218 | 219 | Plurals 220 | ''''''' 221 | 222 | Many terms have translations for both the singular and plural form. In this 223 | case, the ``term`` element contains a ``single`` (for singular) and a 224 | ``multiple`` (for plural) element, which enclose the translations: 225 | 226 | .. sourcecode:: xml 227 | 228 | 229 | 230 | edition 231 | editions 232 | 233 | 234 | 235 | Forms 236 | ''''' 237 | 238 | Terms can also vary in their 'form', which is indicated with the "form" 239 | attribute on the ``term`` element. The different forms are "long" (the default), 240 | "short" (abbreviated form of "long"), "verb", "verb-short" (abbreviated form of 241 | "verb"), and "symbol". Examples of the different forms: 242 | 243 | .. sourcecode:: xml 244 | 245 | 246 | 247 | editor 248 | editors 249 | 250 | 251 | 252 | ed. 253 | eds. 254 | 255 | 256 | edited by 257 | ed. 258 | 259 | 260 | paragraph 261 | paragraph 262 | 263 | 264 | 265 | 266 | ¶¶ 267 | 268 | 269 | 270 | AD/BC 271 | ''''' 272 | 273 | The "ad" and "bc" terms are used to format years before 1000. E.g. the year "79" 274 | becomes "79AD", and "-2500" becomes "2500BC". 275 | 276 | See the `AD and BC 277 | `_ section in 278 | the CSL specification. 279 | 280 | Punctuation 281 | ''''''''''' 282 | 283 | The terms "open-quote", "close-quote", "open-inner-quote", "close-inner-quote", 284 | and "page-range-delimiter" define punctuation. 285 | 286 | When a CSL style renders a title in quotes through the use of the ``quotes`` 287 | attribute, it uses the "open-quote" and "close-quote" terms. When the title 288 | contains internal quotes, these are replaced by "open-inner-quote", 289 | "close-inner-quote". For example, with 290 | 291 | .. sourcecode:: xml 292 | 293 | 294 | “ 295 | ” 296 | ‘ 297 | ’ 298 | – 299 | 300 | 301 | styles can render titles as 302 | 303 | :: 304 | 305 | “Moby-Dick” 306 | “Textual Analysis of ‘Moby-Dick’” 307 | 308 | The "page-range-delimiter" terms is used to connect the first and last page of 309 | page ranges, e.g. "15–18" (it's default value is an en-dash). 310 | 311 | See the `Quotes 312 | `_ and `Page 313 | Ranges `_ 314 | sections in the CSL specification. 315 | 316 | Ordinals 317 | '''''''' 318 | 319 | CSL styles can render numbers (e.g., "2") in two ordinal forms: "long-ordinal" 320 | ("second") and "ordinal" ("2nd"). Both forms are localized through the use of 321 | terms. 322 | 323 | The "long-ordinal" form is limited to the numbers 1 through 10 (the fallback for 324 | other numbers is the "ordinal" form). Each of these ten numbers has its own term 325 | ("long-ordinal-01" through "long-ordinal-10"). 326 | 327 | Things are different for the "ordinal" form. Here, terms are only used to define 328 | the ordinal suffix ("nd" for "2nd"). Furthermore, terms and numbers don't 329 | correspond one-to-one. For example, the "ordinal" term defines the default 330 | suffix, which is used for all numbers (unless, as described below, exceptions 331 | are introduced through the use of the terms "ordinal-00" through "ordinal-99"). 332 | 333 | CSL also supports gender-specific ordinals (both for "long-ordinal" and 334 | "ordinal" forms). In languages such as French, ordinal numbers must match the 335 | gender of the target noun, which can be feminine or masculine. E.g. "1re 336 | édition" ("édition" is feminine) and "1er janvier" ("janvier" is masculine). See 337 | the relevant section below. 338 | 339 | Terms for "ordinal" numbers 340 | ||||||||||||||||||||||||||| 341 | 342 | Terms for the "ordinal" form follow special rules to make it possible to render 343 | any number in the "ordinal" form (e.g., "2nd", "15th", "231st"), without having 344 | to define a term for each number. 345 | 346 | The logic for defining ordinal suffixes with terms is described at `Ordinal Suffixes 347 | `_, and 348 | won't be revisited here. Instead, we'll look at an example. 349 | 350 | In English, there are four different ordinal suffixes in use: "st", "nd", and 351 | "rd" are used for numbers ending on 1, 2, and 3, respectively, while "th" is 352 | used for numbers ending on 0 and 4 through 9. Exceptions are numbers ending on 353 | "11", "12", and "13", which also use "th". 354 | 355 | To capture this logic, we start by defining the "ordinal" term as "th", which is 356 | the most common suffix. Then, we define the terms "ordinal-01", "ordinal-02", 357 | and "ordinal-01" as "st", "nd", and "rd", respectively. By default (i.e., when 358 | the ``term`` elements don't carry a ``match`` attribute), the terms "ordinal-00" 359 | through "ordinal-09" repeat at intervals of 10. For example, the term 360 | "ordinal-01" overrides the "ordinal" term for numbers 1, 11, 21, 31, etc. At 361 | this point, we would get "ordinal" numbers such as "1st", "2nd", "3rd", "4th", 362 | "21st", "67th", and "101st", but we would also get the incorrect "11st", "12nd" 363 | and "13rd". For these cases, we define the terms "ordinal-11", "ordinal-12", and 364 | ""ordinal-13" as "th". By default, the terms "ordinal-10" though "ordinal-99" 365 | repeat at intervals of 100. For example, the term "ordinal-11" overrides the 366 | "ordinal" and "ordinal-01" terms for numbers "11", "111", "211", etc. So, in 367 | total, we need the following seven terms: 368 | 369 | .. sourcecode:: xml 370 | 371 | 372 | th 373 | st 374 | nd 375 | rd 376 | th 377 | th 378 | th 379 | 380 | 381 | Fortunately, many languages have simpler "ordinal" numbers. E.g., for German all 382 | "ordinal" numbers receive a period as the suffix, so it suffice to define the 383 | "ordinal" term: 384 | 385 | .. sourcecode:: xml 386 | 387 | 388 | . 389 | 390 | 391 | Gender-specific Ordinals 392 | |||||||||||||||||||||||| 393 | 394 | To use gender-specific ordinals, we first need to define the gender of several 395 | target nouns: the terms accompanying the number variables (it is probably 396 | sufficient to specify the gender for "edition", "issue", and "volume") and the 397 | month terms ("month-01" through "month-12", corresponding to January through 398 | December). This is done by setting the ``gender`` attribute on the "long" 399 | (default) form of these terms to either "masculine" or "feminine". 400 | 401 | Secondly, we need to define "feminine" and "masculine" variants of the ordinal 402 | terms, which is done with the ``gender-variant`` attribute (set to "masculine" 403 | or "feminine"). 404 | 405 | A minimal example for French: 406 | 407 | .. sourcecode:: xml 408 | 409 | 410 | 411 | 412 | 413 | édition 414 | éditions 415 | 416 | éd. 417 | janvier 418 | 419 | premier 420 | première 421 | premier 422 | deuxième 423 | troisième 424 | quatrième 425 | cinquième 426 | sixième 427 | septième 428 | huitième 429 | neuvième 430 | dixième 431 | 432 | e 433 | re 434 | er 435 | 436 | 437 | 438 | In this example, the "edition" term is defined as feminine, and the "month-01" 439 | term ("janvier") is defined as masculine. For French, of the "long-ordinal" 440 | terms, only "long-ordinal-01" has gender-variants ("premier" for masculine, 441 | "première" for feminine). To cover cases where no gender is defined for the 442 | target noun (e.g., a style author might redefine a term like "edition" but 443 | forget to specify the gender), also a neuter variant of "long-ordinal-01" is 444 | defined without the ``gender`` attribute. The "ordinal" term defines the default 445 | suffix. The only exceptions are for the number 1 when the target noun is either 446 | feminine or masculine (with ``match`` set to "whole-number", the term does not 447 | repeat), e.g. "1re édition" but "11e édition". 448 | 449 | For more information, see the `Gender-specific Ordinals 450 | `_ 451 | section in the CSL specification. 452 | 453 | Submitting Contributions 454 | ~~~~~~~~~~~~~~~~~~~~~~~~ 455 | 456 | To submit changes to an existing locale file, or to submit a new locale file, 457 | follow the `submission instructions for CSL styles 458 | `_. 459 | 460 | Questions? 461 | ~~~~~~~~~~ 462 | 463 | Questions? Contact us on Twitter at `@csl_styles`_, or create an issue on GitHub `here `_. 464 | 465 | .. _@csl_styles: https://twitter.com/csl_styles 466 | --------------------------------------------------------------------------------