Benutzer:PerfektesChaos/js/refNames

Benutzerskript (JavaScript) – Überblick über Zuweisungen von <ref name="..."> und deren Veränderung.

Aufgabe dieses Werkzeugs ist es, die Bezeichner von benannten Elementen <ref> zu verbessern:

Auffinden im Wikitext,
Markieren falls unerwünscht,
Umbenennung ohne Kollisionen in der gesamten Seite,
Löschung falls überflüssig und verwirrend.

Die Bearbeitung ist allerdings begrenzt auf den Quelltext der bearbeiteten Seite. Syntax, die in Vorlageneinbindungen versteckt ist oder andere nicht offenkundige Syntaxkonstrukte bleiben unbeachtet.

Zweck Bearbeiten

Bei Angabe von Belegen sollen die Bezeichner selbsterklärend und nicht verwirrend sein.

VisualEditor weist Bezeichner wie name=":1" oder name=":5" zu, was völlig nichtssagend ist.
Manchmal wird aus einer Syntaxbeschreibung kopiert name="ReferenceA" und dies fortgesetzt bis name="ReferenceZ" – was wiederum keinen Hinweis liefert, worum es dabei inhaltlich gehen würde.
Anderswo wird die ursprüngliche Nummerierung der Anmerkungen als Bezeichner benutzt wie name="q1" oder name="ref1" für ^[1] und name="q2" für ^[2] usw. Sobald jemand dazwischen einen Beleg einfügt, stürzt diese Taktik ab, weil jetzt ^[3] definiert wird durch name="q2" und es wird völlig konfus.
Einige Werkzeuge fügen name="autogenerated1" usw. ein.

Bezeichner sollen einen eindeutigen Hinweis innerhab der Seite geben, welcher Inhalt damit verknüpft wird.

Petra Meier: Wie werden sinnvolle Bezeichner definiert? 2024, S. 42.
name="PMeier-42" könnte eine gute Idee sein, wenn keine andere Publikation von ihr oder anderen PMeier in dieser Seite erwähnt wird.

Bezeichner sollten keine Zeichen der Syntax enthalten, die für Menschen oder Werkzeuge Verwirrung stiften können, wie < > # " ' & oder typografische Zeichen ähnlichen Aussehens oder unsichtbare Zeichen.

Einbindung Bearbeiten

Wenn das Projekt dieses Gadget bereits registriert haben sollte, genügt ein Häkchen auf der Seite Einstellungen („Helferlein“).
Sonst wären die folgenden Zeilen in die persönliche common.js, global.js etc. einzufügen:

mw.loader.load( "https://en.wikipedia.org/w/index.php?title=User:PerfektesChaos/js/refNames/r.js&action=raw&maxage=86400&ctype=text/javascript" );

Funktion Bearbeiten

Auslösung Bearbeiten

Standardmäßig zeigt das Werkzeug in drei Namensräumen Aktivitäten:

Haupt-Namensraum (Artikel, 0)
Benutzer (2)
Projekt (Wikipedia, 4)

Mehr können über individuelle Konfiguration vereinbart werden, aber Spezialseiten sind nicht sinnvoll.

In der Seiten-Ansicht oder bei Vorschau einer Quelltextbearbeitung wird in der Toolbox der Desktop-Skins eine Verlinkung angeboten, um die Analyse dieser Seite zu starten.

Mittels individueller Konfiguration kann auch vereinbart werden, die Analyse bei jeder Vorschau einer Quelltextbearbeitung auszulösen.

Überblick und Bewertung Bearbeiten

Wenn die Analyse angefordert wurde, werden Auflistungen per <references> mit einer Markierung für jedes benannte Element versehen.

Symbole
<ref>	Analyse auslösen anschließend bei Vorschau der Quelltextbearbeitung die Überschrift des Bereichs am Seitenende
ID	`name="ID"` Bezeichner
:0	Problem gefunden
	Änderung dieses Bezeichners
	Löschung anfordern (nur bei verwaisten Bezeichnern, also ohne Bezugnahme)
2×	Mehrfache (identische) Spezifikation des Inhalts; sollte eliminiert werden, um nicht bei Änderung nur einer davon einen Fehler auszulösen und zu verwirren.
<ref />	Fehlende Spezifikation des Inhalts.

Bei Vorschau einer Quelltextbearbeitung wird im letzten Abschnitt der Bearbeitungsseite eine sortierte Auflistung aller Bezeichner angezeigt, die in der Quelltextsyntax gefunden wurden.

Der Tooltip zeigt den textlichen Inhalt.
Der Marker ist verlinkt mit der zugeordneten Präsentation in der Darstellung, sofern gefunden. Bei gruppierten Elementen mit gleichnamigen Bezeichnern ist diese Zuordnung jedoch nicht eindeutig und kann nicht ermittelt werden.

Die Überschrift dieses Bereichs ist verlinkt mit dieser Dokumentationsseite.

Die Markierungen im Vorschaubereich sind verlinkt mit dieser Überschrift.

Austausch und Löschung Bearbeiten

Wenn die gesamte Seite bei Vorschau einer Quelltextbearbeitung angezeigt und die Syntax eindeutig interpretiert werden konnte, kann die einheitliche, vollständige Umbenennung von Bezeichnern angefordert werden.

öffnet ein Bearbeitungsformular.
ermöglicht die Löschung eines Bezeichners, wenn der Mauszeiger an dieser Stelle nach dem Klicken für mehr als eine Sekunde gehalten wird. Danach wird über einen erneuten Klick die Löschung ausgeführt. Falls der Mauszeiger bewegt wird, erfolgt aus Sicherheitsgründen ein Abbruch.

Bei der Bearbeitung wird der dargestellte Inhalt oder der Wikitext angeboten, um mittels Copy&Paste Schlüsselwörter übernehmen zu können.

Symbole
	Änderungsvorschlag ist nicht bereit zur Ersetzung
×	Abbruch
	Tausche diesen Bezeichner aus
	Ausführung; abwarten
	Löschung ausführen

Ein Austausch hat keine Auswirkung auf Bezeichner, die in Vorlageneinbindungen versteckt sind, oder mittels {{#tag:ref|}} Parserfunktion eingebunden wurden.

Der Austausch wirkt auch auf Elementsyntax, die mittels  Kommentare oder <nowiki> <pre> <syntaxhighlight> unwirksam gemacht wurde.

Auffinden von Syntaxfehlern Bearbeiten

Wenn ungültige Syntax angetroffen wurde, wird keine Manipulation der Bezeichner angeboten. Details können in der Fehlerkonsole nachgelesen werden; nach dem # steht dann die Nummer des Zeichens im Quelltext. Auf @ folgt die Zeilennummer, die sich ggf. aus der Diffpage abschätzen lässt. Allerdings kann eine Quelltextzeile recht lang sein und an mehreren Stellen verdächtige <ref> enthalten. Die Nachricht wird abgeschlossen mit dem Versuch, das unverstandene Tag abzubilden.

Individuelle Konfiguration Bearbeiten

Die standardmäßige Umgebung und das Verhalten kann durch alle Benutzer und anbietende Projekte angepasst werden.

Interaktive Schnellkonfiguration Bearbeiten

Einige Optionen können nach Installation des Skriptes auf einer Spezialseite interaktiv konfiguriert werden.

Wähle die gewünschten Optionen.
Mit einem Klick auf den Button + werden die Optionen an den Server übertragen.

Beim nächsten Aufruf einer inhaltlichen Seite wird diese Konfiguration wirksam.

Namensraum-Anforderung mittels JavaScript wird dadurch überschrieben.

Auch nicht angemeldete Benutzer können davon Gebrauch machen; während die Konfiguration für angemeldete Benutzer beim Benutzerprofil auf dem Wiki-Server gespeichert ist, wird hier das Browserprofil benutzt.

Die folgenden Möglichkeiten werden angeboten:

Namensraum-Nummern, bei denen die Toolbox mit einer Verlinkung ausgestattet werden soll, durch Leerzeichen getrennt.
Vorgabe: siehe Namensräume.
* für alle Namensräume.
Regulärer Ausdruck für unerwünschte Bezeichner.
Namensraum-Nummern, bei denen die Analyse in der Vorschau einer Quelltextbearbeitung automatisch ausgelöst werden soll, durch Leerzeichen getrennt.

Konfiguration mittels JavaScript Bearbeiten

Individuelle Wünsche können vor dem Laden des Gadgets vereinbart werden, sofern die interaktive Schnellkonfiguration nicht für Namensräume benutzt wird und diese wieder überschreibt.

Der JavaScript-Code dafür würde folgendermaßen aussehen:

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

Momentan sind die folgenden Optionen verfügbar:

Key	Default	Bedeutung
`rooms`	`[ 0, 2, 4 ]`	Array, mit Namensraum-Nummern, bei denen die Toolbox mit einer Verlinkung ausgestattet werden soll. Vorgabe: siehe Namensräume. String `"*"` für alle Namensräume.
`warn`	`null`	String, mit einem Regulären Ausdruck, um sich über unerwünschte Bezeichner zu beschweren. Array, mit solchen strings.
`trigger`	`null`	Array, mit Namensraum-Nummern, bei denen die Analyse in der Vorschau einer Quelltextbearbeitung automatisch ausgelöst werden soll.

CSS Bearbeiten

Alle relevanten Elemente haben Selektoren mit gadget-refnames- als Präfix.

Spezifikationen in den Gadget-CSS mögen angepasst werden (durch höhere Spezifität usw.).

Um FOUC zu vermeiden, könnte es helfen, die Deklarationen von gadget-refnames-item in zuvor wirksame Stylesheets zu kopieren, weil jene erst nach Einfügung der Werkzeugverlinkung eintreffen könnten.

Codes Bearbeiten

Zu technischen Einzelheiten siehe englischsprachige Dokumentationsseite.