Module:Portal excerpt/doc

ATTENTION! Template whitelisting or blacklisting is not just a "enter-and-be-done" deal. Whitelisting untested templates WILL cause problems!

Unknown templates that are not entered into its configuration are removed by default. This is expected behavior.

This module selects pages for portal excerpts. It can choose one page, a specified page, or random entry from a list, or choose a page linked from another page. Its excerpt processing is adapted from Module:Excerpt/portals and adapted for this very wiki. Selected page leads or sections are cleaned up and returned with an optional image and a link to the full article.

Usage

See the documentation on the five entry-point templates for more information.

The templates below currently do not call this module but its predecessor, as I haven't had time to test them fully yet.

{{#invoke:Portal excerpt|lead}}

Transcludes the lead of an article as an excerpt. See {{Transclude lead excerpt}} for more information.

{{#invoke:Portal excerpt|linked}}

Transcludes as an excerpt the lead of an article selected randomly from wikilinks on a page. See {{Transclude linked excerpt}} for more information.

{{#invoke:Portal excerpt|listitem}}

Transcludes as an excerpt the lead of an article selected randomly from list items on a page. See {{Transclude list item excerpt}} for more information.

{{#invoke:Portal excerpt|random}}

Transcludes as an excerpt the lead of an article randomly from the parameters. See {{Transclude random excerpt}} for more information.

{{#invoke:Portal excerpt|selected}}

Transcludes the lead of a selected article as an excerpt. See {{Transclude selected excerpt}} for more information.

Candidate selection

To learn more about a specific function (template), you are advised to read that template's /doc instead. The technical language here might be too confusing.

For lead, parameter 1 is the page to excerpt. For selected and random, the numbered parameters are candidate pages. selected requires selected= which may be a numbered or a named parameter. Numeric selections beyond the highest numbered parameter wrap around that number. random considers nonempty numbered parameters in numerical order.

For linked and listitem, parameter 1 is a source page containing links to candidate pages, not the page that will be excerpted. linked searches wikilinks in source wikitext. listitem searches wikilinks occurring on lines marked as bulletin or numbered list items, and will halt before a See also heading. Duplicate destinations will only be considered once. File, category, special, external, and other nonsensical destinations will be ignored.

The candidate fucntions try entries in random order until one produces a nonempty excerpt. Use nostubs=yes if you wish to skip pages containing {{Stub}} ({{Notastub}} is excused). A bad or empty candidate can be skipped while another candidate is tried. Because lead has only one candidate to try, if it fails you will meet an error excerpt. To see what this looks like, try pointing any of the templates at Schizophrenia with errors/debug enabled (more on this below).

Annotated links are also supported and recognized as links to target pages.

Candidate-specific options

An entry in a numbered candidate list may override some common settings:

{{#invoke:Portal excerpt|random

|Article A{{!}}paragraphs=1{{!}}files=1

|Article B{{!}}paragraphs=1-2{{!}}more=Read more

|Article C{{!}} ... {{!}} ...

}}

Supported per-candidate keys are paragraphs, files, fileargs, more, nobold, keepsubsections, captions, filelayout, and filecaption & filecaptionN along with multi- prefixed multiple-image keys (see more below). They override the corresponding general settings for that candidate. only cannot be set per candidate, it is global only, and a per-candidate only will be ignored. A candidate may begin with a wikilink, for example [[Article A|Display text]]|files=1 the link's target will be used as the page. Other keys embedded in candidate strings will be ignored.

Excerpt options

Parameter	Effect
paragraphs	Selects numbered paragraphs, for example 1, 1,3, or 1-2. By default all paragraphs in the chosen lead or section are included. A nonempty selection that matches no paragraphs makes that candidate fail.
files	Selects numbered images, for example 1 or 1,3-4. No images are included unless this is supplied. The module looks for existing directly linked images and images in supported infobox image fields, including galleries there. Repeated file names are included once.
filelayout=multiple	When two or more images are selected, setting filelayout to multiple wraps them in {{Multiple image}} instead of stacking separate [[File:...]] links. Has no effect with a single selected image. Layout parameters MUST be set with multi- prefixed keys, e.g. multi-width=, multi-align= etc. The exact list of supported keys can be found in the /config. If multi-align or a width option is not given, the layout borrows those from the first selected image's own fileargs. You should set those yourself if possible. Read {{Multiple image}} for more information regarding how to use this overall.
fileargs	Supplies pipe-separated formatting options for selected images, such as frameless{{!}}120px{{!}}right. Supported size, border, upright, format, and alignment options are applied when the file markup is rebuilt. The default format is thumb. Do NOT override thumb without good reason, as the excerpt will probably look ugly without it.
captions	Off by default. Set to yes to show an image's own original caption (its gallery line label, or the infobox's caption=). With captions off or unset, a selected image shows no caption unless filecaption/filecaptionN is given, those always apply regardless of this setting.
filecaption, filecaptionN	Replaces an image's original caption. filecaptionN applies to image number N and takes precedence over the general filecaption. An empty replacement removes the caption.
only=files or only=file	Returns selected images without excerpt text or the full-article link. NOTE: IMAGES COST EXPENSIVE PARSER CALLS. NOTE: GLOBAL ONLY.
nobold=yes	Removes bold markup from the excerpt text. Otherwise, a bold occurrence matching the selected page title is linked to that page.
more	Changes the final full-article link text. The default is (Full article...); more=no removes the link.
keepsubsections=yes	When excerpting a section, includes its nested subsections. By default, the excerpt stops at the next heading, even if that heading is a subsection.

Paragraph and file selections accept positive numbers through 20 and comma-separated ranges. An invalid item in a selection is ignored. The module does not display images by default, so specify files= when a portal card needs one. File options apply to the selected images, they never select images themselves.

Sections and links

Append #Section name to a candidate page to excerpt the section instead of the lead.

{{#invoke:Portal excerpt|lead|Example article#history|paragraphs=1-2}}

Keep in mind this has differing behavior by template.

For linked and listitem, use section= to restrict the source page from which links are collected. By default, nested subsections are searched too. sectiononly=yes stops at the next heading.

These source-selection options are separate from a candidate's own #Section name and keepsubsections setting.

Section calls, depending on how resolved, are handled in a hierarchy. Specifically, if you link a redirect page which redirects to a section, it will always override your specified section link.

Other candidates

Parameter	Effect
list=Title	Adds a collapsible list of the candidates that remain after the first successful choice. When no title is supplied, the title is Other articles.
showall=Separator	Appends excerpts for the remaining candidates after the first successful one. Its value is used literally as the separator between excerpts, so supply the wikitext you want between them. Enabling showall also enables the remaining-candidates list.

The first successful candidate is chosen randomly where there is more than one candidate. showall processes the remainder in their remaining order, and does not restore the original numbered order. The list likewise names the remaining candidate strings, not a fresh search of the source page.

With the current implementation, the retard who wrote this forgot to make list=no to suppress the list when showall is enabled, it will produce a box titled "no". This will be fixed soon. Use showall only where both the additional excerpts and the list are wanted.

Diagnostics

By default, error selections return no visible error message. Set errors=yes to display fatal errors, such as no valid candidates. Set debug=yes to display fatal errors and informational diagnostics, including skipped candidates and content removal logs. These settings help when figuring out how your candidate is processed and what was removed, etc.

Excerpt cleanup

This module removes the following from selected content:

1. References

2. Category links

3. Comments

4. TemplateStyle tags

5. choose blocks

6. original image markup

7. disallowed templates

8. parser functions

9. certain magic words

10. certain behavior switches

It only keeps authorized templates per set policy. Configuration is available in the /whitelist and /blacklist sections. This does not mean you can just add a template into a whitelist, doing so will cause issues. When files= is used, selected existing images are rebuilt separately from the excerpt text. If unsafe constructs somehow remain after cleanup, the candidate will be forced to fail and another can be tried.

See also

• Module:Excerpt/portals