Differences

This shows you the differences between two versions of the page.

--- csl_simple_edits [2011/04/10 21:25] – [Some Basic Examples] rmzelle
+++ csl_simple_edits [2012/05/24 11:40] (current) – removed rmzelle
@@ Line 1: / Line 1: @@
-======A Step-by-step Guide to Changing CSL Styles======
-Although there currently is no style editor for the Citation Style Language (CSL) styles used by Zotero, changing styles is not hard. The following guide is designed to enable everyone, including users, with no prior knowledge of XML/HTML or programming, to adjust existing styles to their needs.
-===== The Zotero Reference Test Pane =====
-An easy way to get started with editing CSL styles is by using the Zotero Reference Test Pane. This tool renders items from your Zotero library with the CSL style of your choice, and gives real-time feedback when you edit the style.
-To open the Zotero Reference Test Pane, paste
-''<nowiki>chrome://zotero/content/tools/csledit.xul</nowiki>''
-into the Firefox address bar and press Enter.
-{{:test-pane.png?600}}
-Open the Zotero pane, and select one or several items. Now select a style from the drop-down menu in the top-right corner of the Test Pane, or copy and paste a CSL style into the text box into the upper half of the split pane window. The lower half of the window will show how citations and bibliographies are formatted for the selected style and Zotero items.
-==== Make some changes ====
-You can now make changes to the CSL code in the upper half of the split window. As long as the changed style is still correct XML and CSL, the lower half of the window will automatically update after each change. **Style changes are lost when you close the Firefox tab or switch styles. If you plan to make extensive changes, make sure to save your edits often.**
-====Some Basic Examples====
-Minor issues are likely to be in the ''<citation>'' or ''<bibliography>'' sections, which are at the bottom of the style.
-===Changing Punctuation===
-Frequently, two citation styles differ only in their use of periods, spaces, and commas between different elements of a citation. In Zotero these are set using the ''prefix'', ''suffix'' and (group) ''delimiter'' attributes. Let's say we want to put a colon and a space between the list of authors and the date of a citation. There are three ways to do this:
-<code><text variable="author" suffix=": "/>
-<text variable="issued"/></code>
-or
-<code><text variable="author"/>
-<text variable="issued"  prefix=": "/></code>
-or
-<code><group delimiter=": ">
-<text variable="author"/>
-<text variable="issued"/>
-</group></code>
-With the third option, the delimiter is only printed when both variables exist.
-===Changing Options===
-Options are specified at the beginning of both the <citation> and the <bibliography> section. They determine for example if and when //et al.// abbreviation is used and how citations that would otherwise look the same are disambiguated. //The syntax for options differs between CSL 0.8.1 and 1.0//
-==CSL 0.8.1==
-For example, to remove all [[kb/given_name_disambiguation|given-name disambiguation]], find the line:
-''<option name="disambiguate-add-givenname" value="true"/>''
-And just delete the whole line.
-You'll see the change occur immediately in the preview pane below.
-If a style prints //et al.// for citations with more than three authors and only prints the first author, you'll find this in the options:
-<code><option name="et-al-min" value="4" />
-<option name="et-al-use-first" value="1"/></code>
-If you would like to change this so //et al.// is only used for more than five authors and displays the first three, change it to
-<code><option name="et-al-min" value="6" />
-<option name="et-al-use-first" value="3"/></code>
-The [[dev/csl_syntax_summary|CSL 0.8.1 syntax summary]] explains how CSL 0.8.1 works.  Common options you might wish to change are [[dev/csl_syntax_summary#options|here]].
-==CSL 1.0==
-In CSL 1.0, the same options - and several new ones - exist, but they are not listed separately, but included in the <citation> and <bibliography> lines, e.g.
-<code><citation et-al-min="4" et-al-use-first="1" disambiguate-add-year-suffix="true" disambiguate-add-names="true"></code>
-A bit of trial and error, and testing with a few combinations should help. You can see what different items and combinations will look like by selecting them in Zotero (Ctrl-click to select multiple items), and then "Refresh" at the top-left of the Test pane.
-<html>
-<blockquote><font color="blue" size="+1.2">TIP :</font>
-If your style has a mistake, an error message is displayed instead of a citation. Often these messages can help you figure out what you're doing wrong.<br>Also, you can use Ctrl-Z to undo, or if you get really stuck, just select the style from the drop-down again and you're back where you started.</blockquote></html>
-==== Change the Style Title and ID ====
-While not strictly necessary, it is strongly recommended that you change the title and ID of your style.
-Changing the title and ID of your modified style has two advantages:
-  * Installing your modified style won't overwrite the original style
-  * It will prevent your modified from being overwritten itself. The styles that ship with Zotero are automatically updated. If you modified one of these styles and didn't change the title/ID, your modified style will be overwritten when a style update becomes available.
-The title and ID are stored within the ''<title>'' and ''<id>'' elements near the top of the style. For example,
-<code><title>Harvard Reference format 1 (Author-Date)</title>
-<id>http://www.zotero.org/styles/harvard1</id></code>
-can be changed to
-<code><title>Harvard Style Modified</title>
-<id>http://www.zotero.org/styles/harvard-modified</id></code>
-=== Different CSL versions ===
-Starting with version 2.1, Zotero uses an updated version of the Citation Style Language, [[http://citationstyles.org/downloads/specification.html|CSL 1.0]], which has a changed syntax. The styles that come with your copy of Zotero as well as most styles in the [[http://www.zotero.org/styles|Zotero Style Repository]] are in the old CSL 0.8.1 format and are updated internally. You can still edit CSL 0.8.1 styles, but if you want to make more substantive changes or take advantage of one of the [[http://citationstyles.org/downloads/upgrade-notes.html|new features of CSL 1.0]], you should download an updated version of the style from the [[https://github.com/citation-style-language/styles|CSL 1.0 repository]] or use [[http://citationstyles.org/downloads/upgrade-notes.html#updating-csl-0-8-styles|update the CSL 0.8.1 style]] yourself. //You cannot mix CSL 0.8.1 and 1.0. If you want to use some of the new features in 1.0 you will need to use a style converted to 1.0.//
-===== Using your Edited Style with Zotero =====
-You've made some changes to a style, and now you'd like to use your edited style with Zotero. How do you install this new style?
-Select all the style code in the upper half of the test pane (Ctrl-A on Windows, Cmd-A on Mac OS X). Copy and paste the code into a text editor and save the style with a ".csl" file extension (don't use Microsoft Word or WordPad; suitable text editors include Notepad on Windows, and TextEdit on Mac OS X [in plain text mode: Format menu -> Make Plain Text], and gedit or Kate on Linux).
-To install the style, drag the file from where you saved it into an open Firefox page, and click Install in the pop-up message.
-{{:style_install.png?450}}
-You can ignore the grey bar at the top of the window (This XML style does not appear...)
-=====  Some Slightly more advanced tips =====
-For anything more advanced, [[dev/creating_citation_styles|this page]] is your friend. It also includes links to comprehensive documentation for both csl 1.0 and csl 0.
-If you are making several changes, you might want to copy all the CSL code from the top window (Ctrl-A, Ctrl-C) and paste it into a new file in a text editor. Notepad works fine, though using a good text editor designed for programming like the free [[http://notepad-plus.sourceforge.net|Notepad++]] for Windows or [[http://www.barebones.com/products/TextWrangler/|TextWrangler]] for Mac, can help you to see the structure clearly and not make mistakes.  Set the "language" to XML  (CSL is based around XML).
-You'll find that your fellow users on the Zotero forum will be happy to help you with any problems. The forums also have little nuggets of gold all through them, and [[/search/#support|searching ]] usually finds the solution to any issue.  If you are still having trouble, post a question in the Styles section of the Forum and it's likely to get answered quickly.
-===== Sharing Styles =====
-If your new style has general appeal, consider [[dev:submitting_citation_styles|submitting]] it for inclusion into the [[http://www.zotero.org/styles|Zotero Style Repository]].