User:PerfektesChaos/js/refNames

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

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

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

Triggering

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

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)
2×	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

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

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

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

Quick interactive costumization

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

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`	String with Regular Expression payload to complain about undesired identifier patterns. Array of such strings.
`trigger`	`null`	Array of namespace numbers to launch immediately on source editing preview.

CSS

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

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

Codes

Source code	JavaScript – for load() human readable version Background: load() and readable Options: load() and readable CSS: .css
ResourceLoader	`ext.gadget.refNames` for mw:Extension:Gadgets Dependencies: None required (self-completing)
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)