Reba inkomoko ya Inyandikorugero:Template usage/doc

{{Documentation subpage}}

{{tsh|tlusage|tlre}}

== Purpose ==

This template helps field the details of users' <kbd>parameter=value</kbd> deployments on the wiki for any inline template usage.<ref>Some templates, like ''Info box'', and ''Cite'' are usually written with one line per parameter.  These are possible to find using regexp, but this feature is not yet available for this template.</ref> 

[[Special:Version#installed software|This version]] of the search engine, [[mw:Help:CirrusSearch|Cirrus Search]], offers  
regular expression searches.  Here is the advantage:
: {{Sl|hastemplate:"Convert" insource:"{{!}}xx{{!}}" prefix::}} finds 3123 articles, but
: {{Template usage|Convert|[\{{!}}xx\{{!}}]|0}} finds the 45 you really wanted, the ones having the xx ''inside the template call''.

This template instills some regexp-search best practices:
* Always filter a regexp search. Never run a bare regexp search. This template creates a search link, but unlike {{tl|search link}}, this template pre-builds filters and the more arcane elements of the regexp necessary to target a pattern ''inside'' a template wikitext.  Here you need only enter the template name, and start focusing on the search "pattern".
* Start in a small search domain before running it on the wider wiki. This template defaults the search domain to ''one page'' in order to create a small footprint, because only a few regex searches are technically able to run at a time against the database.  It minimizes your footprint, and guarantees that your search link will never run an untested regexp on {{NUMBEROFPAGES}} pages, even if [[H:S#User preferences|someone's default search]] would let them do that.
*Develop the query with the target data in view for study. By default you start with this template in an ''ad hoc'' sandbox, the edit box of a page that already contains a sample of the target. [[Regular expressions]] are formal logic, and so these little computer programs will usually contain mistakes at first that are very easy to discover by running a quick test, so it is characteristic of regex that they are rapidly developed around a small set of test data, rather than slowly debugged against the large data-set they are designed for. 
{{tl|Regex}} also employs these practices, but not specifically for template calls.

With this template developers can 1) generate lists of sub-optimal or non-preferred template usage, and <ref>These will propagate themselves as there presence tempts editors who copy other template calls that they see.  These errors are caused by haste, or poor, or misunderstood template documentation.</ref> 2) achieve template feature parity and avoid the need for backward compatible code. They can do this by directly removing unwanted template usage from the wikitext. Robo-edits can change a feature or add a new feature in lock step with a new version of a template. [[WP:AWB]] is such a robo-editor and it can also do safe regexp searches, and is a complete alternative, but you'd have to download Wikipedia first.

== Arguments ==
{{details|Help:Template#Parameters}} 

{| class="wikitable"
|-
|{{para|template}} or {{param|1}}|| template name. Defaults to "Template usage".  It is also the first unnamed parameter.
|-
|{{para|pattern}} or {{param|2}}|| a regexp search pattern. Targets the inside of all occurrences of the template in wikitext, that is, after the first pipe and before the closing curly bracket: 
<kbd>&#123;&#123;Val{{!}}{{hilite|1=9999{{!}}ul=m/s{{!}}fmt=commas}}&#125;&#125;</kbd>. 
Always use {{tl|!}} for `{{!}}'.  Use {{tl|1==}} for `=' at any time, or when using the unnamed form. See [[#About CirrusSearch|&sect;About CirrusSearch]]" below for more details about types of queries.
|-
|{{para|prefix}} or {{param|3}}|| search domain. Has [[H:S#Parameters|the usual ''prefix:'' meaning]], plus accepts a [[WP:namespace|namespace]] number, or <code>n</code> for the current namespace (or `{<nowiki/>{ns:1}}:', etc.). For all of mainspace use <code>:</code> or <kbd>0</kbd> (zero). To search only mainspace articles that start with ''letter(s)'', assign ''that'' to prefix. To search another namespace that starts with ''letter(s)'', spell-out the namespace (or use `{<nowiki/>{ns:1}}:''letter(s)'', etc.'). Defaults to its current page.
|-
|{{para|label}} or {{param|4}}|| search link label.  It is the forth "unnamed" parameter, so if you enter the first three directly (unnamed), you can also enter a link label directly.
|}


{<nowiki />{Template | parameters | can direct template behavior.}}
:"Named" parameters use <kbd>|{{spaces|2}}name{{spaces|2}}={{spaces|2}}indirect value{{spaces|2}}|</kbd>{{spaces|2}}passing in{{spaces|2}}'<kbd>indirect value</kbd>'.
:"Unnamed" parameters use <kbd>|{{spaces|2}}direct value{{spaces|2}}|</kbd>{{spaces|2}}passing in{{spaces|2}}'<kbd>{{spaces|2}}direct value{{spaces|2}}</kbd>' (with outer spaces.)

== Procedure ==

Namespace plus pagename equals fullpagename.

The procedure here is an iterative, read-evaluate-modify cycle.  
# Find an existing fullpagename with the template instances you are interested in targeting. Or create one yourself, and save it to the database so the query will find it.  
# Open the wikitext. Enter the template name and a regex pattern. (A prefix will be added later.)
# Show Preview.  
# Click the newly rendered search link. Note the bold text in each match, the query (centered), and the count (off to the right).
# Go back in your browser to the edit box. (Or don't go back, you may want to modify the query on the search results page.)
# Modify the regexp in the edit box. Cycle. 
# Enter a prefix. Start with a namespace.  You can then reduce the number of results by adding [[H:S#Parameters|the first letter(s) of]] pagenames onto the namespace.

Then you might need to run each alias (name) the template might have.

Step '''6''' is the core provision of this template.  ''Caveat emptor'': if you change the ''target'', you'll have to save and [[WP:Purge|purge]], ''but not if you just change the pattern''.

This template offers the addition of the search link label, but defaults to showing the regexp.

Currently there is no way to share a {{tlf|tlusage}} search link if you want it to search more than one namespace.  The workaround is one ''tlusage'' per namespace, or to copy the regexp from a ''tlusage'' results page query to a {{tl|search link}} template, which offers the setting of namespaces, and all.  Currently choosing a namespace is not mandatory there, but if you don't choose a namespace there, be aware of possible inconsistencies: the search domain will be different every time it runs, depending on the current user's current search domain. You can set it and forget it at [[Special:Search]] Advanced.

== Examples and sandbox ==

As an ''ad hoc'' sandbox, you can show the wikitext of a section like this, already saved in the database, with template calls on it, modify some patterns, do a Show Preview, and see what matches when you click on the newly formed "search the database" link, all quite safely, and without changing a thing in the database.

<!--If you change the below, sample, targets, you'll have to save the page
vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
to get them into the database to find them in the query. The first batch here
is such concentrated text that it shows up to six or seven hits on the results page.  There is no excess verbiage here. -->
The template calls that produce "{{val|1|ul=ft/s|fmt =   commas}},
{{val|2|u=ft2}},
{{val|3|u=m/s| fmt =commas }},
{{val|4|u=m*s-2}},
{{val|5|u=ft.s-2}},
{{val|6|u=C/J}}, and
{{val|7|ul=J/C}}"
appear in the wikitext of this section like this:
# <kbd><nowiki>{{val|1|ul=ft/s|fmt =   commas}}</nowiki></kbd> 
# <kbd><nowiki>{{val|2|u=ft2}}</nowiki></kbd> 
# <kbd><nowiki>{{val|3|u=m/s| fmt =commas }}</nowiki></kbd> 
# <kbd><nowiki>{{val|4|u=m*s-2}}</nowiki></kbd> 
# <kbd><nowiki>{{val|5|u=ft.s-2}}</nowiki></kbd>
# <kbd><nowiki>{{val|6|u=C/J}}</nowiki></kbd> 
# <kbd><nowiki>{{val|7|ul=J/C}}</nowiki></kbd> → {{val|7|ul=J/C}}
<!--^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you change the above targets, you'll have to save the page
to get them into the database to find them in the query.-->

Note how the above targets are |numbered|, then click on these links.

{| class="wikitable"
! scope="col" width="200px" | Query
! Transcluding {{tlf|tlusage}} produces a [[Template:Internal search templates common doc#Search links|search link]]
! Answer
|-
|'''Q1''' Does this page employ template Val?
|{{#invoke:DemoTemplate|search link|hastemplate:"val" prefix:{{FULLPAGENAME}}}} 
|'''A.''' Yes, because its title shows on the search results.
|-
|'''Q2''' Does this page use Val's fmt parameter?
|<code><nowiki>{{tlusage|val|fmt }}</nowiki></code> → 
{{tlusage|val|fmt }}
|'''A'''. Look for 1 and 3 in the search results in bold text.  
|-


|'''Q3'''. Which calls to Val on this page use <kbd>u=ft</kbd> OR <kbd>ul=ft</kbd>? (a one letter diff)
| <code><nowiki>{{tlusage|val|pattern=ul?=ft}}</nowiki></code> →
{{tlusage|val|pattern=ul?=ft}}
|'''A'''. Look for 1, 2, and 5 in bold text.


|-
|'''Q4'''. AND of these, who also uses fmt=commas after that?
|<code><nowiki>{{tlusage|val|pattern=ul?=ft.*commas}}</nowiki></code> →
{{tlusage|val|pattern=ul?=ft.*commas}}
|A. No context shown, but article title is shown. A half a Bug?
|-
|Which use one space before commas?
|<code><nowiki>{{tlusage|val|. commas}}</nowiki></code> →
{{tlusage|val|. commas}}
|'''A'''. 1 but not 2.


|-
|'''Q5'''. Which use either ul?=ft OR fmt=commas
|<code><nowiki>{{tlusage|val|pattern=(ul?=ft{{!}}co)}}</nowiki></code> →
{{tlusage|val|pattern=(ul?=ft{{!}}=co)}}
|'''A'''. 1, 2, 3, and 5.


|-
|'''Q6'''. Which use ''ft'' or ''m'', in {{para|u}} or {{para|ul}}?
|<code><nowiki>{{tlusage|val|pattern=ul?=(ft{{!}}m)}}</nowiki></code> → 
{{tlusage|val|pattern=ul?=(ft{{!}}m)}}
|'''A'''. 1, 2, 3, 4, and 5.


|-
|'''Q7'''. Which use . or * in the unit code?
|<code><nowiki>{{tlusage|val|pattern=u.+(\.{{!}}\*) }}</nowiki></code> → 
{{tlusage|val|pattern=u.+(\.{{!}}\*) }}
|'''A'''. 4 and 5.
|-
|Which use a pipe?
|<code><nowiki>{{tlusage|val|\{{!}} }}</nowiki></code> → 
{{tlusage|val|\{{!}} }}
|All of them

|-
|'''Q8'''. Which use / or - ''within'' the {{para|u}} or {{para|ul}} paramter?
|<code><nowiki>{{tlusage|val|pattern=ul?=[^{{!}}}]+(\/{{!}}-)}}</nowiki></code> → 
{{tlusage|val|pattern=ul?=[^{{!}}}]+(\/{{!}}-)}}
|'''A'''. 1,3,4,5,6 and 7.


|-
|'''Q9'''. Where is Val used in the template namespace with u or ul?
|<code><nowiki>{{tlre|val|pattern=ul?=|prefix=10}}</nowiki></code> →
{{tlre|val|pattern=ul|prefix=10}}
|'''A'''. In the 15 or so articles listed.  (Uses the {{tlf|tlre}} shortcut.)


|-
| '''Q10''' Which articles employ {{tl|Convert}}'s "and(-)" option?
| <code><nowiki>{{tlre|Convert|Articles using {{tlf|Convert}}'s "and(-)" option.|pattern=and\(-\)|prefix = 0|}}|prefix = 0|}}</nowiki></code> →
{{tlre|Convert|Articles using {{tlf|Convert}}'s "and(-)" option.|pattern=and\(-\)|prefix = 0|}}
| '''A''' Only two.
|} 

In '''Q2''', notice how the MediaWiki software ignores the spaces ''around'' parameters, but how in '''Q4''' the same MediaWiki software processes the spaces ''inside'' parameters. Q2 might have been solved with a plain <kbd>insource:val fmt</kbd> search because "fmt" and "val" are whole words, and fmt is rarely seen apart from inside Val.  How about <kbd>hastemplate:val insource:fmt</kbd>?

Also see the {{plain link|https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-regexp-query.html#regexp-syntax| more general examples for the regex of CirrusSearch}}.

== About CirrusSearch ==
These powerful (but expensive) [[mw:Extension:CirrusSearch|CirrusSearch]] search results could not be obtained with the previous [[mw:Extension:Lucene-search|Lucene-search]] parameters. Regexp searches are restricted on the server, so this template reduces the regex search footprint by using the ''hastemplate:'' filter every time, and further restricts the search domain to a namespace ''at most'', by using the ''prefix:'' filter.  The ''prefix:'' filter can also filter a namespace by specifying that only page names that start with given letters are searched.

=== Parameters insource and hastemplate ===

{{See also|Help:Search#Parameters}}

Here are some notes on the [[mw:Help:CirrusSearch|CirrusSearch]] features of ''hastemplate'' and ''insource''.


''Hastemplate'' finds what is deployed:
* hastemplate will '''not''' count a template when only their sub-template is called
* hastemplate will '''not''' count templates inside comments
* hastemplate will '''not''' count templates inside nowiki tags
* hastemplate '''will''' count templates inside parser functions and other templates, as long as the template is wrapped with double curly braces.
Hastemplate is case-insensitive.


Insource has a dual role:
*<kbd>insource:"''quotes-delimited arguments''"</kbd> finds only whole, alphanumeric words, adjacent to one another in that sequence in the wikitext, treating the entire set of non-alpanumeric characters between them as if they were whitespace. For example, <code>insource:"M S"</code> matches <kbd>m/s</kbd>, as do <code>insource:"M-S"</code> and <code>insource:"m=s"</code>; they all have two arguments, and what matched is shown in bold.
*Plain <kbd>insource:word1 word2</kbd> has one argument, word1. The words after word1 are treated normally: they're all ANDed as whole words (never as pieces or patterns) OR their word stems, anywhere in the wikitext of the page, and in any sequence; and the match is not shown in bold. (Intitle acts the same way around the "quotes" syntax.)
* <kbd>Insource:/''slash delimited argument''/</kbd> finds everything, even comments. It only ever has one argument.  What matched is shown in bold text.
*<kbd>Insource:/''regexp''/</kbd> finds everything, even pieces and parts, conveying no notion of "words", but only that of a character in an adjacent position to another character in a sequence.
* <kbd>Insource:/''regexp''/</kbd> requires you to use <kbd>\/</kbd> for any slash character in the pattern for an obvious reason.  It also requires you to "backslash-escape" other metacharacters for various other reasons.
For ''insource:'' spaces are not allowed after the colon; it's <code>insource:"</code>, or <code>insource:/</code> for good reasons.


Insource "with quotes" is a safe and sufficient way to find many kinds of template usage. Say the target string is {{nowrap|<kbd><nowiki>{{Val|9999|ul=AU|fmt=commas}}</nowiki></kbd>}}:
* <kbd>insource:"val 9999 ul AU fmt commas"</kbd> → match
* <kbd>hastemplate: val insource:"9999 ul"</kbd> → match
* <kbd>hastemplate: val insource:"999"</kbd> → no match
* <kbd>hastemplate: val insource:"fmt commas"</kbd> → match
* <kbd>hastemplate: val insource:"ul AU"</kbd> → match
* <kbd>hastemplate: val insource:"ul au"</kbd> → match
* <kbd>hastemplate: val insource:fmt</kbd> → match
In some cases there might be disadvantages. The ''insource'':"quotes version", is case insensitive and blind to non-alphanumeric characters.  In other cases it is an advantage to have more search results than intended.  For thorough precision, use /regex/.

=== About regex ===

This covers enough regex to get started using this template to answer any question about wikitext contents on the wiki.  Regex are about using ''meta characters'' to create patterns that match any ''literal characters''.  The pattern you give will match a target, character by character.  To make some positions match with multiple possibilities, metacharacters are needed, and they are from the same keyboard characters that are also in the wikitext.

==== Metacharacters ====

The left curly bracket is a metacharacter, and so the regexp pattern given must "escape" any opening curly bracket <code>\{</code> in the target "<kbd>{</kbd>" intending to match a template in the wikitext.  All target text (all wikitext) is literal text, but we can backslash "escape" the regex metacharacters <code> \. \? \+ \* <nowiki>\{{!}}</nowiki> \{ \[ \] \( \) \"  \\ \# \@ \<  \~ </code> when we refer to them as literal characters in the wikitext we are interested in mining. (Notice the backslash-escape of the already template-escaped pipe character in order to find a literal pipe character in the wikitext.) Search will ignore the backslash wherever it is meaningless or unnecessary: <code>\n</code> matches <kbd>n</kbd>, and so on.  So although you don't need to backslash escape <code>&</code> or <code>></code> or <code>}</code>, it is safe to do so.  An unnecessary backslash will not cause your pattern to fail, but what ''will'' is using certain characters literally{{mdash}}<kbd> [ ] . * + ? &#124; { ( ) "  \ # @ <  ~ </kbd>.

* <code>[0-9]</code> will match any digit, <code>[a-y]</code> any lowercase letter except z, <code>[zZ]</code> any z, (and so on). So square brackets mean "character class". 
* Dot <code>.</code> will match a newline, or ''any character'' in the targeted position

The number of sequential digits or characters these symbols match is expressed by following it with a ''quantifying'' metacharacter: 
* <code>*</code> means zero or more 
* <code>+</code> means one or more
* <code>?</code> means zero or one
of the character it follows after. The number of times it matches can also be given in a range, <code>a{2} a{2,} a{2,5}</code> matches exactly 2, 2 or more, or 2-5 <kbd>a</kbd>'s.  So curly brackets mean "quantifier".

* The parenthesis are a grouping mechanism, so we can quantify more than just the previous character, and so we can make boundaries for a set of ''alternative'' matches.  (See ''alternation'' below.)
* The quotation marks are an escape mechanism, like square brackets or the backslash.
* The angle brackets stand for numerals, not digits.  Say <code><5-799></code>, to match 5{{ndash}}799, in one to three positions.  Compare this with the alternative:  <code>[0-9]{1,3}</code> could match ones, tens, or thousands as, 0-999 or 00-999 or 000-999.
* Tilde <code>~</code> looks ahead and negates the next character. In other words, if the pattern matches in this position, then un-match it if the next character is <code>~</code>''character''.

The {{plain link|https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-regexp-query.html#regexp-syntax|other metacharacters offered by CirrusSearch}} may be helpful in some cases: ''complement'' <kbd>~</kbd>, ''interval'' <kbd> <3-5559></kbd>, ''intersection'' <kbd>&</kbd>, and ''any string'' <kbd>@</kbd>.

==== Character classes ====

A character class is enclosed in [square brackets].  It means these characters, "literal characters", plural. It means "literal", and so ''normally'' you don't have to escape a metacharacter character in a character class; they're already square-brackets escaped.  The /slash delimiters/ mean we must of course escape ''any'' slash character, even inside a character class. No other character in a character class except slash always needs escaping; but because <code>]</code> and <code>-</code> have special meaning (metacharacter) to a character class, they must be escaped sometimes: those two are also literal (escaped) metacharacters ''if they are the first character'', but otherwise they must be also, like dash, be escaped: only backslash-escape works as the escape mechanism in a character class.

A character class can serve to escape metacharacters, so <code>[-|*\/.{\]]</code> or <code>[]|*\/.{\-]</code> means "either a dash OR pipe OR star OR slash OR dot OR left curly bracket or a right square bracket".  So <code>[][.?+*|\/{}()\-]"</code> or <code>[-[.?+*|\/{}()\]]"</code> works to find all the metacharacters in the wikitext, all of them except the backslash.  Neither <code>[\]</code> nor <code>[\\]</code> allows us to OR a literal backslash.  To OR a backslash character, there's '''alternation''' with the pattern <code>\\</code> to handle that case.  (See below.)

A character class understands the "inverse" of itself, <kbd>[^abc]</kbd> is "not a or b or c". A character class stands for a single character in a targeted position, so it's not really an inverse of a set, but rather a NOT of a character.

==== Alternation ====

Finally, '''alternation''' is a class of regex that contains alternative possibilities for a match, say an AA or a BB, or a CC:
* "AA" OR "BB" OR "CC" in Boolean logic  
* <kbd>AA|BB|CC</kbd> in a standard, MediaWiki CirrusSearch, regexp
* <code>'''('''<nowiki>AA{{!}}BB{{!}}CC</nowiki>''')'''</code> where it is used within a larger regexp. We need to replace the pipe character with {{tl|!}} so that the "pipe" for the regexp won't confuse this template (or any other template).  We need the parentheses  at times because an alternation finds the ''longest'' pattern, and so the parentheses define that boundary, but it's a boundary you don't have to make if an alternation is the entire regexp pattern.  In our case the {{para|pattern}} you supply is situated at the end of a longer, pre-built regexp.

==== About this template ====

The wiki regex is pretty straightforward.  Characters stand for themselves unless they are metacharacters.  If they are metacharacters they are escaped if outside of a character class.  Use one of three escape mechanisms:
* <code>"."</code>
* <code>\.</code>
* <code>[.]</code>
where the dot is now a literal dot in the wikitext, not the metacharacter.


First, this template take's [[#Parameters|its arguments]] named or unnamed.  If you use the ''unnamed'' one, you can give regexp patterns that start or end with a space.  If you use the ''named'' one, you must, additionally, "escape" any outer space. (To escape is explained elsewhere.) 


The regexp targets the area after the initial pipe and before the first closing curly bracket, <kbd>&#123;&#123;Val{{!}}'''{{hilite|1=9999{{!}}ul=m/s{{!}}fmt=commas}}'''&#125;&#125;</kbd>. This pattern portion is expanded <kbd>/[Vv]al\|[^}]*</kbd><code>{{param|pattern}}</code><kbd>\}/</kbd>. 


This template ''could'' construct the pattern <kbd>\{[Nn]ame.?\|[^}]*{{param|pattern}}</kbd>, where <kbd>pattern</kbd> is the value you give. That regexp means 
* <kbd>pattern</kbd> ''follows'' any number (<kbd>*</kbd>) of characters that are "''not'' (<kbd>^</kbd>) a right curly bracket"; in other words it will ''precede'' a right curly bracket.
* The template ''Name'' follows a left curly bracket, and is case insensitive.
* A pipe <kbd>\|</kbd> (<code>\{{tl|!}}</code>) follows the name, but makes allowance for one possible character in between, the dot. 
* The dot <kbd> . </kbd> can match any character, including the "zero or one" (<kbd>?</kbd>) newline characters that will match the case where the initial pipe is put on its own line, such as how the citation and infobox templates are often transcluded (or "called"). 
This template ''cannot'' make that pattern with the <kbd>.?</kbd> because in general there are many template names that only differ by the last letter, (such as the [[Template:tl#General-purpose formatting|tl]] family of template names). But to match the particular case where the template's first parameter starts after a newline you have to match that newline with a dot.  You can modify the query and add that <kbd> .? </kbd> for searches for Infobox and Cite templates. Because <code>?</code> counts zero as a match, it will also work where the pipe is on the same line.

== See also ==
* {{tl|Regex}}
* [[User:John of Reading/Typo fixing with AutoWikiBrowser|One power user's AutoWikiBrowser]]

== Notes ==
{{reflist}}

<includeonly>{{Sandbox other||
<!-- Categories below this line, please; interwikis at Wikidata -->
[[Category:Search templates]]

}}</includeonly>