Module:Annotated link/sandbox/doc: Difference between revisions

VisualWikitext

Latest revision as of 22:20, 14 March 2025

@@ Line 1: / Line 1: @@
-{{Module: Annotated link/doc}}
+<includeonly>
+{{Lua|Module:GetShortDescription|Module:Arguments|Module:Lang}}
+{{info|This module is invoked by {{tlx|annotated link}}.}}
+{{info|This module may, by design, output alarming informational messages under certain circumstances; if these messages are displayed on any page invoking this module directly, or via any other module or template using it, the page will be added to [[:Category:Pages displaying alarming messages about Module:Annotated link]].}}
+== Usage ==
+<pre><nowiki>{{#invoke:Annotated link|main
+  |name= |display= |quote= |abbr= |abbr_title= |template_link= |aka= |wedge= |dash= |desc_first_letter_case= |space_cat= |prefix_parentheses=
+  |link_lang= |link_lang_italic= |link_lang_nocat= |link_lang_size= |link_lang_cat= |link_lang_rtl=
+  |aka_lang= |aka_lang_italic= |aka_lang_nocat= |aka_lang_size= |aka_lang_cat= |aka_lang_rtl=
+  |wedge_lang= |wedge_lang_italic= |wedge_lang_nocat= |wedge_lang_size= |wedge_lang_cat= |wedge_lang_rtl=
+  |only= |prefer= |fallback=
+  |desc_lang_italic= |desc_lang_nocat= |desc_lang_size= |desc_lang_cat= |desc_lang_rtl= |desc_lang_no=
+}}</nowiki></pre>
+=== name ===
+By providing only the '''required''' page name (including namespace), the module will use [[Module:GetShortDescription]] to look for an explicit {{tlx|short description}} in that page, but if not found, will try to fetch the wikidata description. This is equivalent to stating {{para|prefer|explicit}}; see [[#prefer]] (below). If a description is found, it will be appended to a link created for the named page in the style expected for the likes of [[MOS:SEEALSO]]. If no description is found, the link will be created but no extra information will be appended – unless the extensive following parameters are employed.
+Any foreign language (i.e. not ''en'') text supplied to this module or retrieved by Module:GetShortDescription may be appropriately formatted, in accordance with [[MOS:OTHERLANG]], via the parameters for [[Module:Lang]]; see [[#Foreign language text]] (below).
+As this module is responsible for the use of all features of Module:GetShortDescription; all the parameters for that module are available through this module; see [[#Module:GetShortDescription parameters]] (below).
+:'''Markup:''' <code><nowiki>{{#invoke:Annotated link|main |name=The Partisan }}</nowiki></code>
+:'''Result:''' {{#invoke:Annotated link|main|name=The Partisan}}
+This and the following example song titles should be double quoted per [[MOS:POPMUSIC]]; that will be handled by [[#quote]] (below), and you will see the parameters in use where appropriate from here on.
+=== display ===
+Providing a value for {{para|display}} will format the piped link with a display string:
+:'''Markup:''' <code><nowiki>{{#invoke:Annotated link|main |name=Jump (Every Little Thing song) |display=Jump |quote=yes }}</nowiki></code>
+:'''Result:''' {{#invoke:Annotated link|main|name=Jump (Every Little Thing song)|display=Jump|quote=yes}}
+=== quote ===
+Stating {{para|quote|yes}} will double quote the link:
+:'''Markup:''' <code><nowiki>{{#invoke:Annotated link|main |name=The Partisan |quote=yes }}</nowiki></code>
+:'''Result:''' {{#invoke:Annotated link|main|name=The Partisan|quote=yes}}
+:'''Markup:''' <code><nowiki>{{#invoke:Annotated link|main |name=Jump (Every Little Thing song) |display=Jump |quote=yes }}</nowiki></code>
+:'''Result:''' {{#invoke:Annotated link|main|name=Jump (Every Little Thing song)|display=Jump|quote=yes}}
+=== abbr ===
+Providing a value for {{para|abbr}} will append the link with the provided parenthesized abbreviation with {{tag|abbr}} [[semantic markup]]:
+:'''Markup:''' <code><nowiki>{{#invoke:Annotated link|main |name=Confédération Mondiale des Activités Subaquatiques |display=World Underwater Federation |abbr=CMAS }}</nowiki></code>
+:'''Result:''' {{#invoke:Annotated link|main|name=Confédération Mondiale des Activités Subaquatiques|display=World Underwater Federation|abbr=CMAS}}
+An optional {{para|abbr_title}} may be provided:
+:'''Markup:''' <code><nowiki>{{#invoke:Annotated link|main |name=Confédération Mondiale des Activités Subaquatiques |display=World Underwater Federation |abbr=CMAS |abbr_title=Confédération Mondiale des Activités Subaquatiques }}</nowiki></code>
+:'''Result:''' {{#invoke:Annotated link|main|name=Confédération Mondiale des Activités Subaquatiques|display=World Underwater Federation|abbr=CMAS|abbr_title=Confédération Mondiale des Activités Subaquatiques}}
+=== template_link ===
+If the linked page is in the [[WP:TEMPLATE|Template]] namespace; the link will be formatted in the manner expected by {{tlx|template link}}:
+:'''Markup:''' <code><nowiki>{{#invoke:Annotated link|main |name=Template:Annotated link }}</nowiki></code>
+:'''Result:''' {{#invoke:Annotated link|main|name=Template:Annotated link}}
+Stating {{para|template_link|code}} will display the link  formatted with {{tag|code}}:
+:'''Markup:''' <code><nowiki>{{#invoke:Annotated link|main |name=Template:Annotated link |template_link=code }}</nowiki></code>
+:'''Result:''' {{#invoke:Annotated link|main|name=Template:Annotated link|template_link=code}}
+The previously described parameters – {{para|display}}, {{para|quote}}, {{para|abbr}} and {{para|abbr_title}} – and all foreign language link options under {{para|link_lang}} (see [[#Foreign language text]] (below)) will be ignored if the link is in the Template namespace.
+Stating {{para|template_link|no}} will disable this special link formatting and the ignorance of the above-mentioned parameters:
+:'''Markup:''' <code><nowiki>{{#invoke:Annotated link|main |name=Template:Annotated link |template_link=no |display=Annotated link }}</nowiki></code>
+:'''Result:''' {{#invoke:Annotated link|main|name=Template:Annotated link|template_link=no|display=Annotated link}}
+=== aka ===
+Providing a value for {{para|aka}} will append the link (and {{para|abbr}} if provided) with a useful alternative name:
+:'''Markup:''' <code><nowiki>{{#invoke:Annotated link|main |name=The Partisan |quote=yes |aka=La Complainte du partisan }}</nowiki></code>
+:'''Result:''' {{#invoke:Annotated link|main|name=The Partisan|quote=yes|aka=La Complainte du partisan}}
+:'''Markup:''' <code><nowiki>{{#invoke:Annotated link|main |name=Confédération Mondiale des Activités Subaquatiques |display=World Underwater Federation |abbr=CMAS |aka=Confédération Mondiale des Activités Subaquatiques }}</nowiki></code>
+:'''Result:''' {{#invoke:Annotated link|main|name=Confédération Mondiale des Activités Subaquatiques|display=World Underwater Federation|abbr=CMAS|aka=Confédération Mondiale des Activités Subaquatiques}}
+These and some following examples contain foreign language text that, per [[MOS:OTHERLANG]], should be appropriately displayed and declared via [[HTML]] markup as being of that language; this will be handled by various parameters; see [[#Foreign language text]] (below) for full details, and you will see the parameters in use where appropriate from here on.
+=== wedge ===
+Providing a value for {{para|wedge}} will append the link (and {{para|abbr}} and {{para|aka}} in that order if either or both is provided) with any extra details felt suitable:
+:'''Markup:''' <code><nowiki>{{#invoke:Annotated link|main |name=The Partisan |quote=yes |wedge=from the album ''[[Songs from a Room]]'' |aka=La Complainte du partisan |aka_lang=fr }}</nowiki></code>
+:'''Result:''' {{#invoke:Annotated link|main|name=The Partisan|quote=yes|wedge=from the album ''[[Songs from a Room]]''|aka=La Complainte du partisan|aka_lang=fr}}
+For complementary foreign language params; see [[#Foreign language text]] (below).
+=== dash ===
+For list consistency, per [[MOS:LISTFORMAT]]; by providing a value for {{para|dash}}; the dash between the short description and the preceding text may be exchanged for a suitable alternative:
+:'''Markup:''' <code><nowiki>{{#invoke:Annotated link|main |name=The Partisan |quote=yes |dash=, }}</nowiki></code>
+:'''Result:''' {{#invoke:Annotated link|main|name=The Partisan|quote=yes|dash=,}}
+=== desc_first_letter_case ===
+Short descriptions on en Wikipedia [[WP:SDFORMAT|should be formatted]] with an uppercase first letter, but the typical application of this module will require the first character to be lowercase. By default; this module will ensure all the short descriptions retrieved by Module:GetShortDescription are transformed to start with a lowercase first letter, but this may be overridden if required using {{para|desc_first_letter_case|upper}} or {{para|desc_first_letter_case|lower}}.
+=== prefix_parentheses ===
+Sometimes date ranges in short descriptions are included in a suffixed parenthetical, per [[WP:SDDATES]] e.g. for [[Jimmy Wales]]: "Co-founder of Wikipedia (born 1966)".
+However when listing people in disambiguation pages per [[MOS:DABPEOPLE]], birth and death dates in parentheticals should precede the comma, as in "[[Jimmy Wales]] (born 1966), co-founder of Wikipedia".
+If the optional parameter {{para|prefix_parentheses|y}} is provided, this behavior will be performed, so any suffixed parenthetical text will be moved to before the dash (or comma) separator.
+Note that current consensus is to not use {{tl|annotated link}} for disambiguation pages; see [[Template:Annotated link/doc#Usage]].
+=== space_cat ===
+In the event that a short description with no spaces is retrieved and displayed; pages transcluding the annotation will be added to [[:Category:Pages displaying short descriptions with no spaces via Module:Annotated link]] for interested editors to monitor for potential issues. Potential issues might include: garbage keyboard mashings, a typo of "none" while attempting to disable an explicit {{tlc|short description}} or some misunderstanding on the part of an editor placing one.
+If the transclusion on a page in this category is checked and it is determined to be okay; stating a value for {{para|space_cat}} in the invocation will disable the categorisation. This should only be done on a case by cases basis, as opposed to as a default, or no potentially inappropriate annotations will be categorised; i.e. allow this parameter to be set in individual transclusions of templates which invoke this module, like {{tlx|annotated link}}, rather than in the template code.
+=== Module:GetShortDescription parameters ===
+{{main|Module:GetShortDescription/doc}}
+The value provided with {{para|name}} is passed through this module to Module:GetShortDescription where it is also '''required'''; the expectations of this module are described in [[#name]] (above). Module:GetShortDescription uses the
+value to find a {{tlx|short description}} in the named page, or various alternatives depending on parameter values.
+==== only ====
+Providing a value for {{para|only}} will limit the search to being only for the stated description. If no description is found, the result will be an empty string, unless a fallback is provided; see [[#fallback]] (below).
+:Stating {{para|only|explicit}} will limit the search to only short descriptions set by use of {{tlc|short description}} on the searched page.
+:Stating {{para|only|wikidata}} will limit the search to only wikidata descriptions.
+==== prefer ====
+Providing a value for {{para|prefer}} will initiate the search for the stated description, but try for the alternative if none is found. If no description is found, the result will be an empty string, unless a fallback is provided; see [[#fallback]] (below).
+:State {{para|prefer|explicit}} to use the explicit short description if available, or try for the wikidata description if not.
+:State {{para|prefer|wikidata}} to use the wikidata description if available, or try for an explicit short description if not.
+==== fallback ====
+If a {{para|fallback}} value is provided, and no description is found by the expressed route, the appended description will be the stated fallback value.
+=== Foreign language text ===
+Module:GetShortDescription may return a foreign language (i.e. not ''en'') wikidata description; editor discretion determines if that should be displayed. If it is displayed; it will be in accordance with [[MOS:OTHERLANG]], by [[Module:Lang]] (the module powering {{tlx|lang}}). The appropriate language code will be set automatically, but all other parameters of {{tlc|lang}} are available to affect the formatting of the returned description:
+Use {{para|lang_italic}}, {{para|lang_nocat}}, {{para|lang_size}}, {{para|lang_cat}} and {{para|lang_rtl}}; see [[Template:Lang/doc|lang's documentation]] for details.
+If the editor determines that {{tlc|lang}} formatting is not appropriate; it may be disabled with {{para|lang_no|yes}}. The following {{tlc|lang}} formatting parameters are optional, so there is no off-switch required.
+==== link_lang ====
+If the link text is of a foreign language (again; editor discretion); control the formatting with: {{para|link_lang|<language code>}}, {{para|link_lang_italic}}, {{para|link_lang_nocat}}, {{para|link_lang_size}}, {{para|link_lang_cat}} and {{para|link_lang_rtl}}
+==== aka_lang ====
+If the {{para|aka}} text is of a foreign language (again; editor discretion); control the formatting with: {{para|aka_lang|<language code>}}, {{para|aka_lang_italic}}, {{para|aka_lang_nocat}}, {{para|aka_lang_size}}, {{para|aka_lang_cat}}, {{para|aka_lang_rtl}}
+==== wedge_lang ====
+If the {{para|wedge}} text is of a foreign language (again; editor discretion); control the formatting with: {{para|wedge_lang|<language code>}}, {{para|wedge_lang_italic}}, {{para|wedge_lang_nocat}}, {{para|wedge_lang_size}}, {{para|wedge_lang_cat}}, {{para|wedge_lang_rtl}}
+<includeonly>
 [[Category:Module sandboxes]]
 [[Category:Module sand&test]]