diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3b06aea71fb..492531ba7d0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,11 +4,11 @@ The CSL style repository is the central location on the web for collecting and m Software products like Zotero, Mendeley, and Papers all draw their styles from our repository. We welcome style submissions (and corrections), and are particularly interested in styles for journals and published style guides. -If you wish to submit a different type of style, please first check our [Criteria for Accepting Styles](https://github.com/citation-style-language/styles/wiki/Criteria-for-Accepting-Styles). +If you wish to submit a different type of style, please first check our [Criteria for Accepting Styles](https://github.com/citation-style-language/styles/blob/master/README.md#criteria-for-inclusion). To submit a style, please follow the following steps (for locale files, follow the same steps in the [locales](https://github.com/citation-style-language/locales) repository): -#### 1. Check that your style meets all our [style requirements](https://github.com/citation-style-language/styles/wiki/Style-Requirements) +#### 1. Check that your style meets all our [style requirements](https://github.com/citation-style-language/styles/blob/master/STYLE_REQUIREMENTS.md) #### 2. [Validate](https://validator.citationstyles.org/) your style against the CSL schema, and correct any validation errors @@ -20,7 +20,7 @@ To start, create a GitHub account and sign in. ##### 3a. Submitting a new style 1. Visit https://github.com/citation-style-language/styles and click the "Create new file" button. - When submitting a [dependent style](https://github.com/citation-style-language/styles/wiki/Requesting-Styles#dependent-styles), first navigate to the [dependent](https://github.com/citation-style-language/styles/tree/master/dependent) subdirectory. + When submitting a [dependent style](https://github.com/citation-style-language/styles/blob/master/REQUESTING.md#dependent-styles), first navigate to the [dependent](https://github.com/citation-style-language/styles/tree/master/dependent) subdirectory. 2. Type in the file name of the style in the "Name your file..." text field at the top. Don't forget to add the ".csl" extension (e.g., "journal-of-results.csl" instead of just "journal-of-results")! 3. Paste the style code into the "<> Edit new file" tab below. @@ -28,7 +28,7 @@ To start, create a GitHub account and sign in. 5. In the next window, click the "Create pull request" button. Describe the changes you've made, and click the "Create pull request" button once more. -(for more help, see GitHub's instructions on [Creating new files](https://help.github.com/articles/creating-new-files)) +(For more help, see GitHub's instructions on [Creating new files](https://help.github.com/articles/creating-new-files).) ##### 3b. Submitting changes to an existing style @@ -41,7 +41,7 @@ To start, create a GitHub account and sign in. 5. In the next window, click the "Create pull request" button. Describe the changes you've made, and click the "Create pull request" button once more. -(for more help, see GitHub's instructions on [Editing files in another user's repository](https://help.github.com/articles/editing-files-in-another-user-s-repository)) +(For more help, see GitHub's instructions on [Editing files in another user's repository](https://help.github.com/articles/editing-files-in-another-user-s-repository).) Instead of relying solely on the GitHub website, you can also use a git client, such as [GitHub Desktop](https://desktop.github.com/) for Mac and Windows, or [SmartGit](http://www.syntevo.com/smartgit/). When using a client, [fork](https://help.github.com/articles/fork-a-repo/) the [style repository](https://github.com/citation-style-language/styles), create a branch off of "master", commit your changes, and then create a [pull request](https://help.github.com/articles/using-pull-requests/). diff --git a/QUALITY_CONTROL.md b/QUALITY_CONTROL.md new file mode 100644 index 00000000000..96bc01c86ae --- /dev/null +++ b/QUALITY_CONTROL.md @@ -0,0 +1,194 @@ +# CSL Style Quality Control + +We love the CSL style repository, and wish to keep it in tip-top shape. +Because we have thousands of styles and hundreds of contributors, we rely heavily on automated quality control and periodic maintenance. +This page describes our best practices. + +## Forks and Pull Requests + +The "master" branch of the style repository stores the styles for the most recent CSL release. +To allow changes to be reviewed before they end up in "master", we try to avoid committing changes directly to "master" as much as possible. + +Instead, we rely heavily on forks, branches, and pull requests. +Only our maintainers have direct commit access to the repository. +Contributors can fork the repository, make their changes in their copy of the repository (ideally in a branch), and create a pull request. +This allows us to review your changes, and merge them into the official repository. + +## Travis CI + +[Travis CI](https://travis-ci.org/) is a Continuous Integration service that runs a series of checks on every commit made to the "master" branch, and on every commit in incoming pull requests. +Each Travis test run is called a "build". + +If Travis doesn't detect any problems in your pull request, it will report that the build passed. +Otherwise the build fails, and you will find a link to the build report that shows which tests failed. +Add a new commit to your pull request, and Travis will start a new build and run all tests again. +Only pull requests that pass all the Travis tests can be accepted into the repository. + +The tests are stored in the style repository itself. +Among other things, they make sure that: + +* there are no styles with the same file name, title, or ISSN +* all styles are named correctly, and have style IDs and "self" links matching the file names +* all styles validate against the CSL schema +* all styles have the correct license +* all "template" and "independent-parent" links point to existing independent styles +* all style macros are defined and used +* the root directory contains all independent styles, and the "dependent" subdirectory all dependent styles + +It is possible to [run the tests locally](#Test-Environment) on your computer, which is especially useful to frequent contributors. + +## Indentation, Ordering, and Escaping + +To keep styles consistently formatted, we manually run a [Python script](https://github.com/citation-style-language/utilities/blob/master/csl-reindenting-and-info-reordering.py) every few weeks or so. +The script does the following: + +* reindent the XML code, using 2 spaces per indentation level +* put the elements in the `` section in a standard order +* escape characters that are hard to identify by eye (such as the various dashes and spaces) + +## Extra-strict Validation + +Every so often, we also manually run a [bash script](https://github.com/citation-style-language/utilities/blob/master/style-qc.sh) that validates the styles against a [customized CSL schema](https://github.com/citation-style-language/schema/blob/master/csl-repository.rnc) that is extra strict, and includes requirements specific to our repository. + +## Repairing Problematic Code Patterns + +_Here we keep track of problematic CSL code patterns we have observed in the wild, and provide information on how they can be detected and corrected._ + +### Superscript on citation-number instead of whole citation + +In numeric styles where superscripted numbers are used, it's important to superscript the entire citation so that any punctuation is also superscripted, and e.g. use: + +```xml + + + +``` + +instead of: + +```xml + + + +``` + +**History** + +2016-10: [#2256](https://github.com/citation-style-language/styles/issues/2256) : 47 hits + +### Spaces if second field is flushed + +If the second field in the bibliography is flushed, then it should not have a space as a prefix. + +**Search patterns** + + ]*second-field-align="flush"[^>]*>.*]*>\r\n\s*]*/>\r\n\s*]*prefix=" " + +**Fix** + +Delete `prefix=" "` by hand, but it seems possible to automatically delete the last prefix attribute in this pattern. +No, critical case found. +Moreover, no case with a different prefix beginning with a space found. + +**History** + +2015-01: [#1349](https://github.com/citation-style-language/styles/pull/1349) and [#1346](https://github.com/citation-style-language/styles/pull/1346) : ca. 39 matches + + +### Adjacent spaces from suffix and prefix + +**Search Pattern** + + <[^/>]*suffix="[^"/>]* "[^/>]*/?>\s*\r\n\s*<[^/>]*prefix=" [^"/>]*"[^/>]*/?> + +**Fix** + +Manually look at every case and either + (i) delete the space in suffix, + (ii) delete the space in the prefix, + (iii) use a group with `delimiter=" "`, or + (iv) rewritte some parts of the style. +This can take some time in order to not change the punctation. +It may be possible to restrict the search pattern more, in order to obtain smaller sets of the same/similar replacements. + +**History** + +2015-01: [#1301](https://github.com/citation-style-language/styles/issues/1301) : ca. 300 hits in 230 files + + +## Test Environment + +[![Build Status](https://secure.travis-ci.org/citation-style-language/styles.png?branch=master)](http://travis-ci.org/citation-style-language/styles) + +To maintain the quality of the styles in the official repository, we have set up an environment for quality-control testing in the repository's [master branch](https://github.com/citation-style-language/styles/tree/master). +After every commit to this branch, the tests will be executed on [Travis CI](http://travis-ci.org/#!/citation-style-language/styles) in order to alert us should new (or newly updated) styles break any of the quality control rules. + +If you are a style author, maintainer or would like to contribute to an existing style, you are advised to install the test environment on your computer in order to run the tests while you're working on a style and to make sure all tests are still passing before you commit any changes to the repository. + +### Installation + +Before installing the test environment, please make sure that Ruby is available on you computer. +If Ruby is not installed, please follow the [official instructions](http://www.ruby-lang.org/en/downloads/) on how to install it on your operating-system. +The test environment should work on all current releases of Ruby and is backwards compatible with version 1.8.7. +Some of our tests involve RelaxNG schema validation; these tests are based on [libxml](http://www.xmlsoft.org/) via [Nokogiri](http://nokogiri.org/). +Please see these [operating-system specific instructions](http://nokogiri.org/tutorials/installing_nokogiri.html) if you have any problems installing the test setup because of these requirements. + +**Note: it seems in Ruby 1.8.7 you can get some failures with [] and {} comparison failing** + +Once Ruby is installed on your computer, it is easy to setup the test environment. +First, clone into the official repository (if you have previously cloned the repository you can skip this step): + + $ git clone https://github.com/citation-style-language/styles.git + $ cd styles + +You should work directly on the master branch. + +Next, we will install all requirements using [Bundler](http://gembundler.com/) (run `[sudo] gem install bundler` to make sure you have the latest version installed). +Please note that depending on how Ruby is installed on your system you might need administrator privileges to install Ruby Gems, therefore, we have prefixed the commands with an optional `[sudo]`: + + $ [sudo] bundle install + +### Usage + +Once your bundle is installed there are two ways to run the tests. +You can use rake: + + $ rake + +Or you can run the tests using `rspec`: + + $ bundle exec rspec spec + +The latter is useful if you would like to pass special parameters. +For example, if your Terminal does not support colors, the output may be illegible. +In this case try running the tests with: + + $ bundle exec rspec spec --no-color + +Or, if you would like a more verbose output of all tests, you can switch to a different format, for example: + + $ bundle exec rspec spec --format documentation + +Will print a summary of all tests for each style. + +#### Testing styles in isolation + +With the growing number of styles and tests available in the repository the number of test cases to execute has risen into the range of 100,000 – for obvious reasons, execution may take up to a few minutes on your computer. +In order to allow for quicker feedback-loops when working on styles, you can set the environment variable CSL_TEST to control which styles to include in the test. + +The CSL_TEST variable may contain a list of file names (separated by spaces) of styles to include; +please note that the name should be the file's full base-name including the '.csl' extension. +However, for additional flexibility, you can include regular expression wildcards as well. + + $ CSL_TEST="apa.csl vancouver.csl" bundle exec rspec spec + + $ CSL_TEST="chicago.*" bundle exec rspec spec + +Finally, you can set the CSL_TEST variable to the special value 'git'; +by doing that you can limit the styles to be included in the test run to those styles which are currently marked as modified in your local git repository. + + $ CSL_TEST="git" bundle exec rspec spec + +#### Windows + +For colored output of the test results on Windows, [see this guide](http://softkube.com/blog/ansi-command-line-colors-under-windows/). diff --git a/README.md b/README.md index 1ea1fd4efaf..39c98ce0dea 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ The primary components of the CSL ecosystem are: This README describes our official curated repository of CSL styles, hosted at https://github.com/citation-style-language/styles/. CSL locale files, which provide default localization data for CSL styles (such as translations and date formats), can be found at https://github.com/citation-style-language/locales. -For more information about CSL and CSL styles, check out https://citationstyles.org/ and the [repository wiki](https://github.com/citation-style-language/styles/wiki). +For more information about CSL and CSL styles, check out https://citationstyles.org/ and the information files in this repository ([Style Requirements](https://github.com/citation-style-language/styles/blob/master/STYLE_REQUIREMENTS.md), [Style Development](https://github.com/citation-style-language/styles/blob/master/STYLE_DEVELOPMENT.md), [Requesting Styles](https://github.com/citation-style-language/styles/blob/master/REQUESTING.md), [Contributing Styles](https://github.com/citation-style-language/styles/blob/master/CONTRIBUTING.md), and [Quality Control](https://github.com/citation-style-language/styles/blob/master/QUALITY_CONTROL.md)). Criteria for inclusion ---------------------- @@ -29,7 +29,7 @@ The official CSL style repository is the only repository of its kind, is used by The popularity of this repository is in large part due to its crowd-sourced nature, and, we believe, also due to our careful curation. While we evaluate style submissions on a case-by-case basis, we generally use the following criteria for inclusion in the CSL style repository: -* Styles must be of sufficient quality and meet our [Style Requirements](https://github.com/citation-style-language/styles/wiki/Style-Requirements). +* Styles must be of sufficient quality and meet our [style requirements](https://github.com/citation-style-language/styles/blob/master/STYLE_REQUIREMENTS.md). While we may be able to assist with this, its ultimately the submitter's responsibility to provide a style that meets our standards. * Styles should be based on an official style guide (and link to the style guide in online or printed form). * Styles should be of interest to a wider audience. diff --git a/REQUESTING.md b/REQUESTING.md new file mode 100644 index 00000000000..d548eedafa9 --- /dev/null +++ b/REQUESTING.md @@ -0,0 +1,94 @@ +# Requesting CSL Styles + +Below are instructions to request new CSL styles and to report problems in existing styles. + +We only have a few volunteers who respond to incoming requests, so please follow our instructions closely to make the process more efficient. +While we typically work for free, we do charge for, e.g., creating styles for universities or departments ([contact us](http://citationstyles.org/contact/) for pricing). +You can also try to [edit CSL styles](https://github.com/citation-style-language/styles/blob/master/STYLE_DEVELOPMENT.md#editing-styles) yourself. + +## Requesting a New Style + +1. First, make sure the style you're requesting isn't already available. + The easiest way to check this is to search the [Zotero Style Repository](http://www.zotero.org/styles), which has all our styles. +2. If we don't have the style, try a quick search of the [Zotero forums](http://forums.zotero.org/) to see if there is already a Zotero forum thread for the style you want to request. + If there is an existing thread, check whether you can provide any missing information that we might need to create the style. + The thread might also contain (technical) reasons why we currently cannot support your style. +3. If you can't find an existing Zotero forum thread, create a new one. + **If you have already started a thread, just update it; do not create a new one.** + Name your post "Style Request: [name of style]", and include the following information: + + * A link to online style documentation (e.g. for a journal, this would generally be a link to the journal's "Instructions to Authors" section). + * For journals, the journal's ISSN (print version) and/or e-ISSN (online version). + If you can't find this information on the journal website, try looking up the journal in the [NLM Catalog](http://www.ncbi.nlm.nih.gov/nlmcatalog). + * Two citations, for a journal article and a book chapter, in the format of the style you're requesting. + **Create these citations for the two items shown below, the article by Campbell and Pedersen and book chapter by Mares.** + **If your request does not contain these specific citations, you will be asked to revise it**. + Provide both in-text citations and bibliographic entries. + For, e.g., the APA style, these citations would look like: + + > In-text citation: + > (Campbell & Pedersen, 2007) + > (Mares, 2001) + > + > Bibliography: + > Campbell, J. L., & Pedersen, O. K. (2007). The varieties of capitalism and hybrid success. *Comparative Political Studies*, *40*(3), 307–332. https://doi.org/10.1177/0010414006286542 + > Mares, I. (2001). Firms and the welfare state: When, why, and how does social policy matter to employers? In P. A. Hall & D. Soskice (Eds.), *Varieties of capitalism. The institutional foundations of comparative advantage* (pp. 184–213). New York: Oxford University Press. + + | Field | Value | + |---------------------|----------------------------------------------------------------------------------| + | Type | article-journal | + | Title | The varieties of capitalism and hybrid success | + | Author | John L. Campbell, Ove K. Pedersen | + | Issued | 2007/3/1 | + | Container-title | Comparative Political Studies | + | Volume | 40 | + | Issue | 3 | + | Page | 307-332 | + | URL | http://cps.sagepub.com.turing.library.northwestern.edu/content/40/3/307.abstract | + | DOI | 10.1177/0010414006286542 | + | ISSN | 1552-3829 | + | JournalAbbreviation | Comp. Polit. Stud. | + | Language | en-US | + | Accessed | 2010/7/26 | + + | Field | Value | + |-----------------|-----------------------------------------------------------------------------------------| + | Type | chapter | + | Title | Firms and the welfare state: When, why, and how does social policy matter to employers? | + | Author | Isabela Mares | + | Editor | Peter A Hall, David Soskice | + | Issued | 2001 | + | Container-title | Varieties of capitalism. The institutional foundations of comparative advantage | + | Page | 184-213 | + | Publisher | Oxford University Press | + | Publisher-place | New York | + | Event-place | New York | + | ISBN | 9780199247752 | + | Language | en-US | + + * Finally, if possible, also provide a link to a freely available paper formatted with the style you're requesting. + Published papers often help clarify formatting requirements not discussed in the style guide. + For journals that aren't open access, you can often find a free sample issue, or you maybe be able to find a freely available PDF of a recent journal article via, e.g., Google Scholar. + +P.S. Instead of requesting a new style, you can also look for an existing CSL style that has a format identical or similar to what you're looking for. +You can do this with our [CSL style editor](http://editor.citationstyles.org/). +Visit the “Search by Example” tab, and change one of the example references into the desired format (using the metadata of the selected item). +Click “Search”, and the editor will show you the CSL styles that most closely match the format you provided. +See also the [CSL editor user guide](https://github.com/citation-style-editor/csl-editor/wiki/User-guide-for-the-CSL-Editor). + +### Dependent Styles + +Please tell us if we already have a CSL style with the format you're looking for, but with a different style name. +For instance, journals from the same publisher (e.g. "Nature" and "Nature Biotechnology") often use the same style format. +Other journals simply use one of the main style guides, such as APA. + +In these cases, we can create a *dependent style*. +These dependent styles (e.g. the CSL style for "Nature Biotechnology") simply point to a regular *independent style* with the desired style format (e.g. the CSL style for "Nature"). +Dependent styles don't define a style format themselves and are much easier to create than independent styles. + +## Reporting Style Errors + +Requesting changes to existing CSL styles is very similar to requesting new styles. +However, in this case, there will often already be a Zotero forum thread for your style of interest. +Before posting, please make sure you have the most recent version of the style installed. +In your post, give examples of how the existing CSL style format should change, and include the relevant excerpt from the style guidelines, or just give a link to the guidelines. diff --git a/STYLE_DEVELOPMENT.md b/STYLE_DEVELOPMENT.md new file mode 100644 index 00000000000..e84548fe697 --- /dev/null +++ b/STYLE_DEVELOPMENT.md @@ -0,0 +1,267 @@ +# CSL Style Development + +CSL relies on volunteers to develop, edit, and maintain its library of citation styles. +Below are guidelines and tips for editing and developing CSL styles. + + +## Editing Styles + +### CSL Visual Editor + +To edit styles, you can use the [Visual CSL Editor](http://editor.citationstyles.org/about/), developed in a cooperation between Mendeley and Columbia University Library. +See the [CSL Visual Editor user guide](https://github.com/citation-style-editor/csl-editor/wiki/User-guide-for-the-CSL-Editor). +If you have questions about editing styles with the CSL Visual Editor, you can still ask for help on the [Zotero forums](https://zotero.org/forum) or on the [CSL Discourse page](https://discourse.citationstyles.org/). +Please only use the [Issues page of this repository](https://github.com/citation-style-language/styles/issues) to report bugs, not to ask general style editing questions. + + +### Manually editing CSL styles + +You can also edit CSL styles manually. +Zotero includes a [built-in CSL Style Editor](https://zotero.org/support/dev/citation_styles/reference_test_pane) that allows you to see how your edits change style output in real time. + +You can also edit CSL styles in any plain text editor (e.g. Notepad on Windows or TextEdit on macOS). +Note that text editors with XML support can be very useful by offering features like syntax highlighting and real-time validation. +Popular choices are [Atom Editor](https://atom.io/), [VS Code](https://code.visualstudio.com/), the [oXygen XML Editor](https://www.oxygenxml.com/), [Emacs in nXML mode](https://www.thaiopensource.com/nxml-mode/), and [jEdit](https://www.jedit.org/). + +Currently, most documentation for editing CSL styles can be found at: + +* http://citationstyles.org/citation-style-language/documentation/ + + +### 1 - Start from the Right Style + +If you want to improve an existing CSL style, make sure that you start from the most recent version. +The most recent version of each CSL style can be found in the [`master` branch of this repository](https://github.com/citation-style-language/styles). + +If you want to create a new style, find an existing style that closely matches what you need using the previews in the style repository. +Typically the best way to find a most similar style is the ["seach by example"](http://editor.citationstyles.org/searchByExample/) function of the CSL Visual Editor. + + +### 2 - Edit the Style + +Download the style you want to edit to your computer, and open it your plain text editor. +Make any edits and save your style. +Be sure that the new file has a `.csl` file extension (you can generally do this by simply typing ”.csl” after the name of your file). + +If you are using the Zotero CSL Editor, be sure to save your edits often using the "Save" button to avoid losing your changes. + +Refer to the [CSL specification](http://citationstyles.org/downloads/specification.html) for information on the various options available in CSL styles. +Below, we discuss a few common style edits to get you started. + +#### Changing punctuation + +In this example, we want to display the publisher ("CSHL Press") and the location of the publisher ("Cold Spring Harbor, NY") in a bibliographic entry. +While this can be achieved with the code: + +```xml + + +``` + +this would result in "CSHL PressCold Spring Harbor, NY". +Fortunately, we can add some punctuation with the `prefix`, `suffix`, and `delimiter` attributes. +Let's say we want to separate the `publisher` and `publisher-place` by a comma-space, and wrap the whole in parentheses, i.e. "(CSHL Press, Cold Spring Harbor, NY)". +This can be done with: + +```xml + + + + +``` + +The advantage of use a `group` element is that whenever you have a `publisher`, but no `publisher-place`, you don't end up with incorrect punctuation: the output would become "(CSHL Press)". +If you would set the punctuation directly onto the `text` elements, e.g.: + +```xml + + +``` + +you would lose the closing bracket, i.e. "(CSHL Press". + +#### Changing et-al abbreviation + +There are two main settings for et-al abbreviation (e.g., rendering the names "Doe, Smith & Johnson" as "Doe et al."). +The minimum number of names that activates et-al abbreviation, and the number of names shown before "et al.". + +In CSL, these settings can appear on the `style`, `citation`, `bibliography` or `names` elements in the form of the `et-al-min` and `et-al-use-first` attributes (it is possible to have separate settings for items that have been cited previously by using the `et-al-subsequent-min` and `et-al-subsequent-use-first` attributes). + +For example, + +```xml + + ... + +``` + +will result in name lists like "Doe", "Doe & Smith" and, if there are three or more names, "Doe et al.". +Try changing these numbers and observe the effect. + +#### Changing disambiguation rules + +CSL offers multiple methods to disambiguate cites or names. +For example, a style might normally render only the family name (e.g., "(Doe 1999, Doe 2002)"). +If the authors are Jane Doe and Thomas Doe, these names can be disambiguated by adding initials or the full given names (e.g., "(J. Doe 1999, T. Doe 2002)"). + +Disambiguation methods are selected on the `citation` element. +For example, to disable [given name disambiguation](https://zotero.org/support/kb/given_name_disambiguation), delete the `disambiguate-add-givenname` attribute, e.g., change: + +```xml + + ... + +``` + +to: + +```xml + + ... + +``` + +#### Changing author separation + +By default, several authors are separated by a delimiter `, ` and the word `and`. +This settings can be changed, for example to use the symbol `&` instead: + +```xml + + + ... + +``` + +or to not use `and` at all, but to use the delimiter `/`: + +```xml + + + .. + +``` + +#### Conditional rendering (full footnote style) + +The appearance of citations in (full) footnote styles may depend on their position in the paper. +If the same source is cited twice, it may be that a shortened version is used in the second (and any further) citation. +To handle this distinction, one can use [conditional rendering based on the position](http://citationstyles.org/downloads/specification.html#choose) of the citation. +A generic structure could then look like: + +```xml + + + + + ... + + + ... + + + ... + + + ... + + + + +``` + +If a case is missing in your style, you can add a new case and specify how information should be rendered in that case (e.g. see [Chicago (full note)](https://www.zotero.org/styles/chicago-fullnote-bibliography?source=1) for an example). + +#### Note: Updating from Older CSL Versions + +You should alway begun editing from a style that uses the current version of CSL. +If you are starting from an older version of CSL (e.g. CSL 0.8.1), you should first [upgrading it to the current CSL version](http://citationstyles.org/downloads/upgrade-notes.html#updating-csl-0-8-styles) to take advantage of the newest CSL features. + +CSL 0.8.1 and 1.0 styles can be easily distinguished by looking at the ``` +``` + +##### 4 - File Name + +The file name of a style should be based on its title. +However, file names may only contain lowercase roman letters (a-z), digits (0-9), and single hyphens (-), and must end with the ".csl" extension. +To create the file name from the title: + + * replace capitals with lowercase letters + * replace ampersands with "and" (e.g., "Arts & Health" becomes "arts-and-health.csl") + * replace spaces and apostrophes with hyphens (e.g., "Documents d'archéologie française (French)" becomes "documents-d-archeologie-francaise.csl") + * drop diacritics (e.g., "für" becomes "fur", not "fuer") + * drop text between parentheses (e.g., "Ugeskrift for Læger (Danish)" becomes "ugeskrift-for-laeger.csl") + * avoid abbreviations (e.g., use "modern-humanities-research-association.csl" instead of "mhra.csl") + * add the ".csl" extension + +You can use a 'slugify' tool like https://blog.tersmitten.nl/slugify/ to quickly lowercase titles and replace spaces by hyphens, although you may have to make some more changes by hand. + +##### 5 - Style ID + +The style ID must be "http://www.zotero.org/styles/file-name", with "file-name" representing the style's file name without the ".csl" extension. +For example, the style ID would be "http://www.zotero.org/styles/modern-humanities-research-association" for "modern-humanities-research-association.csl": + +```xml + + http://www.zotero.org/styles/modern-humanities-research-association + +``` + +##### 6 - "self" Link + +The style's "self" link, which tells where the style will available online, must be "http://www.zotero.org/styles/file-name", with "**file-name**" representing the style's file name without the ".csl" extension. +For example, "http://www.zotero.org/styles/modern-humanities-research-association" for "modern-humanities-research-association.csl": + +```xml + + + +``` + +##### 7 - License + +The style must be licensed under the Creative Commons Attribution-ShareAlike 3.0 License. +Use the exact text below, without any hard line breaks for ````: + +```xml + + This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 License + +``` + +##### 8 - "template" Link + +If you started from another CSL style, delete the original style authors and contributors, and point to the original style with a "template" link: + +```xml + + + +``` + +##### 9 - ISSN and eISSN + +Journal styles should list the journal's print ISSN (````) and online ISSN (````), if available: + +```xml + + 0028-0836 + 1476-4687 + +``` + +##### 10 - "documentation" Link + +Independent styles should have a "documentation" link that points to a description of the style's citation format. +For journals, this is typically the "instructions to authors" webpage. +If a style guide is only available in print, provide a URL that allows us to locate a paper copy. + +```xml + + + +``` + +##### 11 - XML Indentation + +Indent the style's XML with 2 spaces per level. +Some text editors support automatic indentation of XML. +Alternatively, use our [style formatter](http://formatter.citationstyles.org/) tool. + +##### 12 - Validation + +Make sure your finished style [validates](https://github.com/citation-style-language/styles/blob/master/STYLE_DEVELOPMENT.md#validation) against the CSL schema. + +That's it! You're ready to [submit](https://github.com/citation-style-language/styles/blob/master/CONTRIBUTING.md) your style!