User:PleaseStand/References segregator

From Wikipedia, the free encyclopedia
Jump to: navigation, search
The segregate-refs.js logo

References segregator (segregate-refs.js) is a user script by PleaseStand – an attempt to make editing articles that have many citation templates easier. It works by moving the first non-empty occurrence of a <ref> tag to a separate text box that is below the main editing textbox. That first occurrence of the ref is replaced by a short tag as if there were an identical reference before it. It is also capable of migrating articles to the list-defined references format (LDR).

How does it work?[edit]

Segregate button
After the button is pressed, references are "segregated" into their own edit box, separate from the main editing box.

A small amount of informal testing of the MediaWiki parser allowed for writing regexes to locate and parse various elements of <ref> tags. There are two phases that the script proceeds as you edit a page with it:

  1. Segregation. This phase is when ref tags are pulled out of the text, initiated when you click the button. Then you are free to edit the page content without the interference of lengthy citation templates. In order for this to work even with unnamed refs, the unnamed refs get a unique name: the prefix (the word "Auto" followed by two alphanumeric characters and a hyphen) plus a number specific to the unnamed ref. Don't worry about this; as long as you don't add another ref tag with the same name or mess with the autogenerated ref tag, the next phase will recognize this and strip the automatic name out. If you wish to name all the refs, you should do it before starting the script, as it will save work later.
    • Please note that in many places, the script capitalizes ref tags (i.e. REF vs. ref). This is intentional and is not a bug. Rather, this quirk serves to prevent unnecessary shifting in location of the contents of the tags.
  2. Integration. When you click a button that submits the edit form (Save, Preview, or Show Changes), the script finds all ref tags that are in the "Inline footnotes" box. Then it proceeds to substitute these ref tags in place of the first occurrences of the same-named shortened ref tags generated during segregation. Finally, your changes are sent to the Wikipedia servers as normal.

This is completely independent from the citation template syntax, as long as all footnotes are surrounded in non-nested <ref> tags in MediaWiki format.

What are its limitations?[edit]

The script has been successfully tested in Mozilla Firefox, Opera, Safari, and Google Chrome by the author with no problems found. Internet Explorer 9 should also work; however, the author has not tested the script in that browser. Internet Explorer 8 and below are incompatible with the current version of this script. For the time being, Internet Explorer 6/7/8 users (on Windows XP) should use one of the alternatives listed above.

Some aspects of MediaWiki parser syntax, such as the braces tag syntax for nested refs, are not supported. If there turn out to be any severe limitations other than listed below, you should leave a message for PleaseStand. Since you are ultimately responsible for your edits, please confirm that the script doesn't break any aspect of the page you are editing by clicking Show changes before you commit your edits.

  • Currently there is no section editing support: this is a special case of the above limitation and would require checking all other sections for ref contents. The script is not active on these edit pages.
  • Some user scripts might be incompatible with the References Segregator (including User:Js/ajaxPreview.js, although I have asked for a compatibility fix so that script should be working soon). The same goes for the "live preview" feature found in "My preferences". The script is, however, written for compatibility with wikEd.
  • Probably the least of these issues is that refs with such insane names as __proto__ might not work correctly with the script. This is a quirk of using JavaScript objects as "associative arrays" and might eventually be fixed in a future version of the script.

How do I use it?[edit]

Installation[edit]

First of all you need to be running a standards-compliant browser. This includes the latest versions of most browsers, but not Internet Explorer (see list below).

Then copy the following code into your skin JS file or your common.js file:

importScript("User:PleaseStand/segregate-refs.js");
  • You will need to click the green button below the box every time you want to use the script.
    • Then the first occurrence of each ref will appear in a new textbox below the main edit box that it disappears from. Read above for details.
  • To view the source code for the script (fairly well documented), please see User:PleaseStand/segregate-refs.js. This includes a brief description on how to make translation files that cause the interface to appear in a different language.
  • The script is licensed under the ISC License in addition to Wikipedia's copyright terms, so you are welcome to integrate the script (or parts of it) into your own Greasemonkey user scripts, for example, as long as you include the copyright and permission notice.

Supported browsers[edit]

The latest versions of Mozilla Firefox, Opera, Safari, and Google Chrome work with no problems.

In Safari, when wikEd is used, the green "Segregate refs" button might be located strangely. This only is a cosmetic anomaly and actual functionality should not be affected.

Internet Explorer 9 should also work; however, the author has not tested the script in that browser. Internet Explorer 8 and below are incompatible with the current version of this script. For the time being, Internet Explorer 6/7/8 users (on Windows XP) should use one of the alternatives listed below.

Installing on other wikis[edit]

On a MediaWiki installation other than the English Wikipedia you will need to use this code:

// install [[Wikipedia:User:PleaseStand/References segregator]] editing tool
importScriptURI('http://en.wikipedia.org/w/index.php?title=' +
'User:PleaseStand/segregate-refs.js&action=raw&ctype=text/javascript');

Just like the code for English Wikipedia users, this code automatically gives the latest version of the code including any updates or bug fixes. If your wiki is on a network without an Internet connection, you will need to copy the complete source code into your wiki instead.

Userbox[edit]

While its use is in no way mandatory, there is a userbox that you may place on your user page if you find References Segregator useful and would recommend it to other editors. It looks like this:

References Segregator Logo.svg This user uses
References Segregator
to get ref tags out of the way.


To place the userbox on your user page, use the code {{User:PleaseStand/References segregator UBX}}

Development version[edit]

Until it is reasonably certain that any update to the script does not break it, any changes will be made to a separate development version. The development version be kept at User:PleaseStand/segregate-refs-dev.js.To recommend a change, please list your recommendation on the talk page for this page.

Converting footnotes to list-defined (LDR) format[edit]

This subsection describes how to permanently convert an article's footnotes to LDR format. You must not do this without proper consensus. To make this conversion, you need to add the following line above the importScript() line:

var SegregateRefsJsAllowConversion = true;

Then make sure to follow these steps. Do not forget a step or you will find yourself breaking the citations/footnotes!

1. If you wish to name all the references yourself, do so now, as it will save you some work later. You can alternatively follow the optional Step 7 below to accomplish the same thing.

2. Click the red "Migrate article to LDR" button. Click OK to acknowledge your understanding that consensus is required to convert citation/footnote style. Nothing will be saved yet when clicking OK.

3. If you are converting a specially-named group (such as "nb" footnotes), enter the HTML-quoted name in the box and click OK. If not, or if you don't know what footnote groups are, leave the box blank and click OK.

4. Notice that you now see two separate edit boxes:

  • The larger upper box contains the article text, but with its inline references removed, and replaced by named references.
  • The smaller lower box contains a list of the actual references.

5. In the upper box, find the article's references section. It will contain either <references/> or {{reflist}}.

  • If it contains <references/>, change this to:
    <references>
    REFS HERE
    </references>

  • If it contains {{reflist}}, change this to:
    {{reflist|refs=
    REFS HERE
    }}

6. Copy the entire contents of the lower edit box (the list of references) and paste it in place of the words "REFS HERE". If you are converting a special group, make sure that the group name is included.

7. The following is not technically required, but is best practice: This script auto-generates names for references that don't already have names. You should change these to descriptive names. The easiest way to do so is to copy the entire wikitext of the article (from the large upper edit box) into a good text editor. Use the find-and-replace feature to replace each ref name that has the form "AutoXY-Z" (the auto-generated names) with a human-readable name that makes sense. Each autogenerated name should be surrounded in double quotes when you use Find/Replace, or you may screw things up. Paste your changes back into the large upper edit box. Click the Show Changes button and check the diff for any potential problems. This step is not necessary if you followed Step 1, or if all references were already named before you began.

8. Click the Preview button. Check to make sure that there are no cite errors anywhere on the page, including in the references section. Then pick a sampling of footnote links and make sure they work.

9. Once you've confirmed that everything looks good and there are no errors, save your changes.

Earlier attempts[edit]

wikEd has reference/template hiding (even in the stable version), but for some tasks it can be cumbersome to use (it's necessary to switch out of ref-hiding mode to delete a reference).

dereference.js is an earlier script that I was unaware of when I originally wrote this script, but it seems to have some of the same limitations as wikEd and is no longer maintained (user is not currently active on Wikipedia).

Yet another earlier script is User:Magnus Manske/less edit clutter.js. That one has some additional features and was actually proposed as a gadget.

Any questions?[edit]

Please leave a message for me. Generally, I will respond quickly, but be patient – it might take a few days, or sometimes even longer, to get a reply.

References[edit]