JavaScript gadget – keep survey and rename <ref name="..."> assignments.

The goal of this tool is to improve the identifiers of named <ref> tags:

  • detect,
  • mark if undesired,
  • rename easily in the entire page without clashes
  • dismiss if superfluous and confusing.

However, editing is limited to the source text of the foreground page. Syntax hidden in transcluded templates or otherwise not obvious elements will be kept unchanged.

Mission

edit

On referencing annotations, identifiers should be self-explaining and not misleading.

  • VisualEditor assigns like name=":1" or name=":5" which tells absolutely nothing.
  • Some users are copying the syntax description name="ReferenceA" and continue until name="ReferenceZ" which gives no clue what is referred to.
  • Others use the initial numbering and provide name="ref1" for [1] and name="ref2" for [2] etc. As soon something is inserted between this strategy crashes since then [3] is defined by name="ref2" and becomes entirely confusing.
  • Some tools insert name="autogenerated1" etc.

The identifier should give a unique hint within this particular page which content will be linked.

  • Jane Smith: How to make reasonable identifiers? 2022, p. 42.
  • name="Smith-42" may be a good choice if no other publications written by any Smith are occurring.

Identifiers should not contain syntax characters which cause confusion on various stages, like < > # " ' & or typographic characters of similar appearance nor hidden characters.

Usage

edit
  • If your project has registered this as a gadget, just activate on your Preferences page.
  • Otherwise include the following line into your common.js, global.js etc.:
mw.loader.load( "https://en.wikipedia.org/w/index.php?title=User:PerfektesChaos/js/refNames/r.js&action=raw&maxage=86400&ctype=text/javascript" );

Functionality

edit

Triggering

edit

By default, the gadget takes action in three namespaces:

  • Main spaces (articles, 0)
  • User space (2)
  • Project spaces (4)

More can be configured by individual configuration, but special pages are not meaningful.

In view or source editing preview mode the toolbox of desktop interface will offer a link to start analysis.

Overview and judging

edit

If analysis is requested the lists of <references> will be equipped with a label for each named item.

Symbols
<ref> Trigger analysis
ID name="ID" identifier
:0 Problem detected
Edit this identifier
Request removal (orphan elements only)
Multiple content definitions, should be merged to avoid redundant and inconsistent declaration
<ref /> Missing definition

On source editing preview mode the final section of the edit page will repeat all named reference identifiers visible in source code by tag syntax, even if not in effect on rendered pages.

  • The tooltip will show the text of that reference.
  • The marker is linked with the related presentation of this item at rendered page, if found. On grouped elements with identical name the assignment is not unique and cannot hit the related rendering.

The headline is linked to this docpage.

  • The items at rendered part are linked to this headline.

Exchanging and deletion

edit

If the entire page is covered by source editing preview and syntax leaves no doubt it is possible to ask for global renaming of identifiers.

  •   will open an edit form.
  •   will permit name deletion if mouse pointer is kept for about two seconds in this position after clicking. If moving out this action is aborted for security reasons.

On editing the rendered content or wikitext will be offered to exploit names and words via copy&paste.

Symbols
Suggestion not yet ready for exchange
× Abort
Exchange this identifier
Executing, please wait
Execute removal

Exchanging will not cover identifiers which are hidden in templates, as template parameters or within {{#tag:ref|}} functions.

Exchanging is in effect for tag syntax disabled by <!-- --> comments or <nowiki> <pre> <syntaxhighlight> elements.

Syntax error tracking

edit

If invalid syntax is encountered, manipulation is not offered and error messages can be read at browser console. After # they tell the character position in edit field. @ precedes the line number which may be guessed from diff page. However, a line might be quite long and multiple <ref> could occur. The message is terminated by an attempt to reproduce the invalid element.

Individual Configuration

edit

The initial environment and the behaviour can be equipped by each user individually.

Quick interactive costumization

edit

Some options can be set interactively on specific Special:Blankpage as soon as the script has been loaded.

When reloading a page the preferences declared here come into effect. This dynamic assignment for namespaces overrides the static setting by hooked object.

Anonymous users can use this mode, too; options will be stored in browser profile rather than on wiki server.

The following capabilities are offered:

  • Namespace numbers to be equipped with toolbox link (space separated).
    Default: see namespaces.
    * for all namespaces.
  • Regular expression for undesired name patterns.
  • Namespace numbers to launch on source editing preview (space separated).

Configuration by JavaScript

edit

Before the request for loading described at “Usage” something like the following statement might be executed:

mw.hook( "refNames.config" ).fire( { rooms:   [ 0, 2, 4, 100 ],
                                     warn:    "^ref\\d+$",
                                     trigger: [ 0 ] } );
mw.loader.load( /* ... */ );    // as shown above

By those keywords the process might be influenced as described here:

Key Default Bedeutung
rooms [ 0, 2, 4 ]
  • Array of namespace numbers to be equipped with toolbox link.
    Default: see namespaces
  • String "*" for all namespaces.
warn null
trigger null Array of namespace numbers to launch immediately on source editing preview.

All relevant elements have selectors prefixed by gadget-refnames-.

The gadget CSS definitions may be adopted by higher specificity.

To avoid FOUC it might be helpful to provide the declarations of gadget-refnames-item since those decorations might arrive a bit later while the toolbox link has been inserted already.

Internationalization

edit

A translation of this page may be offered. Translations of interactive costumization is also welcome.

Codes

edit
Source code
ResourceLoader
Namespaces all
Actions view edit
Cookies
  • sessionStorage
    • refNames for memorizing section editing. (but currently unused)
  • localStorage
    • refNames for memorizing system messages etc. (but currently unused)
mw.libs refNames (reserved, but currently unused)
mw.hook
  • refNames.ready
    When basic code has been loaded.
    Tells implementation metadata.
  • refNames.config
    To specify individual configuration.
MediaWiki MW 1.22
JavaScript 1.5 (2000)