Template:AnnotatedListOfLinks/doc

When substituted, AnnotatedListOfLinks wraps the {{Annotated link}} template around un-annotated wikilinks in a list. It's designed to avoid clobbering existing descriptions so it can be placed around mixed content without much concern. One notable exception is the loss of HTML-style comments. The expected common use is for quickly updating "See also" sections while making sure to respect prior manual edits.

Usage

{{subst:AnnotatedListOfLinks|
<!-- mixed wikitext (including headings, comments, templates) -->
== See Also ==
{{Portal|example}}
* [[Standard links]]
* [[Piped links|Pipers]]
* [[Generic Links]] - links that require more context than just the text
* {{Annotated link |Good Articles}}
* [[More links]]
* [[File:Some_photo_from_1944]]
<!-- though the File: example would be unusual -->
Followup prose with [[embedded links]] to other things. 
}}

When applied as above, the resulting wikitext is as follows:

== See Also ==
{{Portal|example}}
* {{Annotated link |Standard links}}
* {{Annotated link |Piped links|Pipers}}
* [[Generic Links]] - links that require more context than just the text
* {{Annotated link |Good Articles}}
* {{Annotated link |More links}}
* [[File:Some_photo_from_1944]]
Followup prose with [[embedded links]] to other things.

The net result is that three links have been updated to use the {{Annotated link}} template, two HTML-style comments have been removed, and the other wikitext has remained unchanged.

Tips

Keep updates narrow

Don't surround an entire page if you don't need to. If there are unforeseen errors (like important lost comments), they will be more limited if you use this only where it's really needed. Keeping updates narrow also speeds things up a bit. Plus, there's no reverse-edit equivalent to change annotated links back to regular square-bracket links which means the fastest way to undo accidental damage done with this template is a revert.

Preview AND Show Changes

You might not realize what you are and aren't changing without taking a quick peak at the "Show Changes" results that bring up the wikitext changes to be made. Double check that and preview the page to be safe.

Leave a useful edit summary

This template doesn't explain the reason for the changes it makes; that's your job. Linking to one or more of these may be helpful at your discretion: Template:Anl, WP:WPSD, WP:HOWTOSD.

Write missing descriptions

After using this template, consider visiting any pages that don't show a WP:Short description even though they are already wrapped with {{Annotated link}}. Filling in missing descriptions is an easy way to help other editors understand what the template does. It also really helps out WP:WPSD.

What it updates

This template only updates a link if all these criteria are met

1. The link is an unordered list item which may or may not be indented
2. The only thing in the list item is a square-bracketed wikilink which may be piped
3. The link does not have a namespace identifier (i.e. [[Special: Random]] will not be changed).
4. The link does not make use of Pipe tricks
5. The linked title is longer than one character. (i.e. not a link to the article titled [[T]])

Links that meet those criteria are updated regardless of whether the target article already has a WP:WPSD or not with the understanding that when one is added, it will be correctly rendered by the {{Annotated link}} template. This means some edits with this template will initially appear to have no effect. You can fix this by visiting any article which needs a description and writing it for the target page. Also note that links targeting redirect pages will be updated but may show a different WP:WPSD than the target page since each can have their own description. This can be confusing to editors who check for SD consistency between annotated links and their target but it is generally not a problem for readers since articles do not include the description as part of the rendered content. Readers, in other words, will only see the SD for the redirect page, not the target page.

HTML-style comments

Comments passed through this template will be removed and should be re-added manually in a subsequent edit if they are desired. Alternatively, relocate important comments outside the template before substitution to preserve them.

What it does NOT update

These are unlikely to change

• Anything on the same line as this template call: In general keep the opening call to this template and the closing call on two separate and dedicated lines above and below the wikitext that should be updated.
• Ordered lists: These are currently avoided out of an abundance of caution. Ordering implies editors have made some effort to manage the presentation of the list so this template tries not to interfere.
• Redirected links (kind of): This template will wrap links to redirects but will not re-pipe them to the target (i.e. inject the appropriate canonical name) and it will not pull in the WP:WPSD from the target of the redirect if it differs from the SD on the redirect page itself - even if the redirect page has an empty description. Redirects may have their own WP:Short descriptions and that description would naturally be favored if the editor who wrote the link chose to use a redirected title rather than the target's canonical title.
• Any links pointing outside the article namespace: Although WP:Short descriptions are used in a limited fashion in some other namespaces, article content should not typically link to those pages. In the few cases where it does, short descriptions probably aren't needed.
• Links that contain a colon (:) in the target or substituted text: Looking for a colon is the mechanism used to avoid changing non-article namespace links.
• Links which share a list item location with anything else: This includes wiki formatting like bold links but those are rarely consistent with WP:MOS anyway. It also includes links that use extensions such as Vintage cars (note the added 's' at the end) and lines with more than one link.
• Links that make use of the Pipe trick or the reverse pipe trick: Testing seems to indicate pipe tricks are substituted when edits are saved. If true, the only time you should encounter these are when you try to substitute this template and use pipe tricks within the enclosed wikitext. An easy way around it is to separate your edits into two: one to add a pipe tricked link and a followup to annotate all the links in the list.

Why should this be substituted?

Transcluding this template has no effect. It would be technically possible to write the template in such a way that it accomplished the same thing using transclusion but this was avoided mostly in an effort to borrow the WP:Principle of least astonishment for use in the context of editing wikitext. It's unusual for templates to perform selective parsing of wikitext which is essentially what this one does: certain links get parsed and others do not. This might lead to editors modifying the wikitext used within the template and seeing unexpected results. Using substitution allows the template code to plop {{Annotated link}} templates specifically where they are needed making it clear which parts of the wikitext source are being supplemented and which are not.

Another benefit of substitution is display consistency with the "Annotated link" template. Transcluding would require re-implementing the rendering of WP:Short descriptions into HTML output, and in the long term, might lead to slight differences between links rendered with this template and with individual annotated links. Substitution avoids that potential diversion.

Finally, substitution reduces the familiarity burden on future wikitext editors. Substituting the template leaves no trace of the template's name in the subsequent edit. Although it sounds problematic it actually has a subtle benefit: although editors who use this template need to know what it does, editors encountering the results of this template only need to have knowledge of {{Annotated link}} to understand the final output. In effect, it helps direct other wikitext editors to that template instead of this one.

Limitations

• HTML-style comments will be stripped. This might not ever change. Be cautious about placing this template around helpful comments in wikitext as they will be removed. It's particularly difficult to see this as comments don't show up on the page in preview mode by design. You can see this change before it is final however by using the "Show changes" button in the wikitext editor.
• It only works on English Wikipedia. Do not attempt to use this template on another wiki outside of English Wikipedia (i.e. copy the code there) as it will have no effect unless WP:Short descriptions come into common use there. You're just wasting your time until then.
• There are few things mentioned above that this template will not update.

Troubleshooting

Target article has a WP:WPSD but it doesn't show

This is probably a case of a redirected link. For redirected links, the SD of the target article is not automatically pulled back by {{Annotated link}}. The actual redirect page needs to have its own description as well or it will register as blank. Generally this is preferred because descriptions may vary slightly in the choice of words that best describe the same subject by alternate names.

Why did(n't) it update some link?

If it's not covered above, it may be helpful to review the module's testcases.

History

• A relevant discussion from May 2021 about the length of short descriptions touched on their usefulness in "See also" sections of the encyclopedia. See: Wikipedia talk:Short description/Archive 9#But what about wp:think of the reader?
• This was the first live edit made with this template (hosted in user space at the time). This edit had no visible effect on the rendered page content because none of the linked pages had short descriptions written. It's still a useful and productive edit though because future short descriptions will be automatically exposed on the target article without additional updates.