Difference between revisions of "Template:Alphanumeric TOC/doc"

From DMARC Wiki
Jump to navigation Jump to search
(Suppression of the normal TOC: Clarification of muddy explanation)
m (27 revisions imported)
 
(25 intermediate revisions by 18 users not shown)
Line 1: Line 1:
<includeonly>{{template doc page transcluded}}</includeonly><noinclude>{{template doc page viewed directly}}</noinclude>
+
{{Documentation subpage}}
 
<!-- EDIT TEMPLATE DOCUMENTATION BELOW THIS LINE -->
 
<!-- EDIT TEMPLATE DOCUMENTATION BELOW THIS LINE -->
==Purpose==
 
This TOC template was created as a customizable substitute for the growing zoo of CompactTOCs.  Rather than have dozens of stylistic varieties, it is preferrable to have a single template which can be adjusted to fit the editor's wishes.
 
  
==Usage==
+
{{tl|Alphanumeric TOC}} is a customizable substitute for the (formerly) growing zoo of variants of {{tl|Compact ToC}}. Rather than have dozens of stylistic varieties, it is preferable to have a single template which can be adjusted to fit the editor's wishes.
Insert <code><nowiki>{{AlphanumericTOC}}</nowiki></code> at the point in the article where you want the TOC to appear. If using with a list, many editors have found it helpful to insert a TOC at both the beginning and end of the list.
 
  
===Parameters===
+
== Usage ==
Toggling the style and display of elements within the TOC is accomplished by adding parameters with a null value (in the form <code>|''parameter''=|</code>).  This is a short list which will be expanded upon further in the following text:
+
Insert the following at the point in the article where you want the TOC to appear: If using with a list, many editors have found it helpful to insert a TOC at both the beginning and end of the list (remember to add <code>|top=yes</code> to the bottom template to quickly get back to the top).
*block v. inline formatting: <code>multiline</code>, <code>nobreak</code>;
 
*table alignment: <code>align</code>;
 
*addition of prefixes to the links: <code>prefixLink</code>, <code>prefixDesc</code>;
 
*suppressing the automatic table of contents: <code>notoc</code>; and,
 
*each of the links also has its own parameter which when used suppresses the display of the link.
 
  
===Block and inline formatting===
 
When the template is used without any parameters, it appears as:
 
{{AlphanumericTOC}}
 
This replicates what you would see with a template like <code>{{[[:Template:CompactTOCrefs|CompactTOCrefs]]}}</code>.  The templates <code>{{[[:Template:CompactTOC2|CompactTOC2]]}}</code>, <code>{{[[:Template:CompactTOC5T|CompactTOC5T]]}}</code>, and <code>{{[[:Template:CompactTOCrefs2|CompactTOCrefs2]]}}</code> display the text in a single inline list.  To accomplish this, add the parameter <code>nobreak</code> to the template:
 
 
<pre>
 
<pre>
{{AlphanumericTOC|
+
{{alphanumeric TOC}}
    nobreak=|}}
 
 
</pre>
 
</pre>
{{AlphanumericTOC|nobreak=|}}
 
  
For a TOC which displays in a block format, like <code>{{[[:Template:CompactTOC4|CompactTOC4]]}}</code> and <code>{{[[:Template:CompactTOC5|CompactTOC5]]}}</code>, add the parameter <code>multiline</code>:
+
Whenever multiple TOCs will be used on a page, and this template will '''not''' be the primary one at the top of the page, add <code><nowiki>|primary=false</nowiki></code> (this prevents multiple TOCs from showing up in each other's listings):
 +
 
 
<pre>
 
<pre>
{{AlphanumericTOC|
+
{{alphanumeric TOC
    multiline=|}}
+
|primary=false
 +
}}
 
</pre>
 
</pre>
{{AlphanumericTOC|multiline=|}}
 
  
'''Note:''' If these parameters are used in combination, <code>multiline</code> will always override any effects from <code>nobreak</code>.
+
== Options ==
 +
=== Alignment ===
 +
The natural state of the TOC is to appear along the left side of the page without any alignment.  To align to the center of the page, add the parameter <code>align</code> with a value of 'center':
  
===Aligning the TOC===
 
As is apparent from the examples already given, the natural state of the TOC is to appear along the left side of the page without any alignment.  Some of the existing TOCs, including <code>{{[[:Template:CompactTOC|CompactTOC]]}}</code>, <code>{{[[:Template:CompactTOC3|CompactTOC3]]}}</code>, and <code>{{[[:Template:CompactTOCrefs|CompactTOCrefs]]}}</code>, are aligned to the center of the page.  This can be replicated by adding the parameter <code>align</code> with a value of 'center':
 
 
<pre>
 
<pre>
{{AlphanumericTOC|
+
{{alphanumeric TOC|align=center}}
    align=center|}}
 
 
</pre>
 
</pre>
{{AlphanumericTOC|align=center|}}
 
The TOC may also be aligned to the right or the left, causing the article text to wrap around it, but floating the TOC is generally discouraged.  Guidelines may be found at [[Wikipedia:Section#Floating the TOC]].
 
  
===Prefixing links or link descriptions===
+
{{alphanumeric TOC|align=center}}
The TOC templates <code>{{[[:Template:CompactTOCprefix|CompactTOCprefix]]}}</code> and <code>{{[[:Template:CompactTOC2wprefix|CompactTOC2wprefix]]}}</code> include the ability to add a prefix to the link with or without displaying it in the TOC. This can also be accomplished with this template by using the parameters <code>prefixLink</code> and <code>prefixDesc</code>; the former adds the prefix to the actual link, and the latter adds the prefix to the text displayed on the page. Examples:
+
 
 +
The TOC may also be aligned to the right or the left, causing the article text to wrap around it, but floating the TOC is generally discouraged.  Guidelines may be found at [[Help:Section#Floating the TOC]].
 +
 
 +
=== Prefixing or suffixing links or link descriptions ===
 +
The template includes the ability to add a prefix to the link with or without displaying it in the TOC. This can also be accomplished with this template by using the parameters <code>prefixLink</code> and <code>prefixDesc</code>; the former adds the prefix to the actual link, and the latter adds the prefix to the text displayed on the page. The <code>suffixLink</code> and <code>suffixDesc</code> parameters work the same way. Examples:
 +
 
 
<pre>
 
<pre>
{{AlphanumericTOC|
+
{{alphanumeric TOC|prefixLink=1.}}
    prefixLink=1.|}}
 
 
</pre>
 
</pre>
{{AlphanumericTOC|prefixLink=1.|}}
+
 
 +
{{alphanumeric TOC|prefixLink=1.}}
 +
 
 
<pre>
 
<pre>
{{AlphanumericTOC|
+
{{alphanumeric TOC|prefixLink=hidden|prefixDesc=visible}}
    prefixLink=hidden|
 
    prefixDesc=visible|}}
 
 
</pre>
 
</pre>
{{AlphanumericTOC|prefixLink=hidden|prefixDesc=visible|}}
+
 
 +
{{alphanumeric TOC|prefixLink=hidden|prefixDesc=visible}}
 +
 
 
<pre>
 
<pre>
{{AlphanumericTOC|
+
{{alphanumeric TOC|prefixDesc=+}}
    prefixDesc=+ |}}
 
 
</pre>
 
</pre>
{{AlphanumericTOC|prefixDesc=+ |}}
 
  
===Suppression of the normal TOC===
+
{{alphanumeric TOC|prefixDesc=+}}
By default this template suppresses the generation of the normal table of contents because it assumes that this is to be replaced by the alphanumericalTOC.  However, in certain situations a TOC may be desirable in addition to the alphanumericalTOC, for example: where the alphanumericalTOC applies to only a section of the article and there are more than two sections.
+
 
If you want to overide the TOC suppression and allow the software to generate a table of contents in the normal way, use the parameter <code>notoc</code> as follows:
 
 
<pre>
 
<pre>
{{AlphanumericTOC|
+
{{alphanumeric TOC|suffixDesc=+}}
    notoc=|}}
 
 
</pre>
 
</pre>
  
===Selective link removal===
+
{{alphanumeric TOC|suffixDesc=+}}
One of the reasons for having so many different versions of CompactTOC has been that some articles do not have a 'References' section, or the TOC is being used for a list contained within a larger article.  This template solves the problem by providing a parameter for each link to be removed. They are as follows:
+
 
*<code>numbers</code>: removes the numbers link
+
=== Standard and custom sections ===
*<code>a</code>, <code>b</code>, etc.: removes the link for that letter; alternatively it can be used to create unlinked letters (see example below)
+
One of the reasons for having so many different versions of CompactTOC has been that some articles do not have a 'References' section, or the TOC is being used for a list contained within a larger article.  This template solves the problem by providing a parameter for each link to be shown. They are as follows:
*<code>sections</code>: removes all links appearing after the letters
+
 
*<code>top</code>: removes the link to the 'Top of Page'
+
; <code>|numbers=yes</code>: shows the numbers link
*<code>seealso</code>: removes the link to the 'See also' section
+
; <code>|a=</code>, <code>|b=</code>, etc.: shows the link for that letter; alternatively it can be used to create unlinked letters (see example below)
*<code>references</code>: removes the link to the 'References' section
+
; <code>|top=yes</code>: shows the link to the 'Top of Page'
*<code>externallinks</code>: removes the link to the 'External links' section
+
; <code>|seealso=yes</code>: shows the link to the 'See also' section
 +
; <code>|references=yes</code>: shows the link to the 'References' section
 +
; <code>|externallinks=yes</code>: shows the link to the 'External links' section
  
 
Some examples:
 
Some examples:
 +
 
<pre>
 
<pre>
{{AlphanumericTOC|
+
{{alphanumeric TOC|numbers=yes|i=|n=|x=|z=|references=yes}}
    numbers=|
 
    sections=|}}
 
 
</pre>
 
</pre>
{{AlphanumericTOC|numbers=|sections=|}}
+
 
 +
{{alphanumeric TOC|numbers=yes|i=|n=|x=|z=|references=yes}}
 +
 
 
<pre>
 
<pre>
{{AlphanumericTOC|
+
{{alphanumeric TOC|numbers=yes|i=I|j=J|v=V|x=X|top=yes}}
    numbers=|
 
    i=|
 
    n=|
 
    x=|
 
    z=|
 
    references=|}}
 
 
</pre>
 
</pre>
{{AlphanumericTOC|numbers=|i=|n=|x=|z=|references=|}}
+
 
 +
{{alphanumeric TOC|numbers=yes|i=I|j=J|v=V|x=X|top=yes}}
 +
 
 
<pre>
 
<pre>
{{AlphanumericTOC|
+
{{alphanumeric TOC| style="text-align:center;" |g=|seealso=yes|externallinks=yes}}
    numbers=|
 
    i=I|
 
    j=J|
 
    v=V|
 
    x=X|
 
    nobreak=|
 
    top=|}}
 
 
</pre>
 
</pre>
{{AlphanumericTOC|numbers=|i=I|j=J|v=V|x=X|nobreak=|top=|}}
 
<pre>
 
{{AlphanumericTOC|
 
    multiline=|
 
    align=center|
 
    g=|
 
    seealso=|
 
    externallinks=|}}
 
</pre>
 
{{AlphanumericTOC|multiline=|align=center|g=|seealso=|externallinks=|}}
 
  
===Optional user defined section links===
+
{{alphanumeric TOC| style="text-align:center;" |g=|seealso=yes|externallinks=yes}}
Optional section links may be defined using the parameters <code>sec1</code>, <code>sec2</code>, <code>sec3</code>, <code>sec4</code>, and <code>sec5</code>, as follows:
+
 
 +
=== Optional user defined section links ===
 +
Optional section links may be defined using the parameters <code>|sec1=</code>, <code>|sec2=</code>, <code>|sec3=</code>, <code>|sec4=</code>, and <code>|sec5=</code>, as follows:
  
 
<pre>
 
<pre>
{{AlphanumericTOC|
+
{{alphanumeric TOC|numbers=yes|seealso=yes|externallinks=yes|sec1=Added section|sec2=Plus one}}
    numbers=|
 
    seealso=|
 
    externallinks=|
 
    sec1=Added section|
 
    sec2=Plus one|}}
 
 
</pre>
 
</pre>
{{AlphanumericTOC|numbers=|seealso=|externallinks=|sec1=Added section|sec2=Plus one|}}
 
  
==History==
+
{{alphanumeric TOC|numbers=yes|seealso=yes|externallinks=yes|sec1=Added section|sec2=Plus one}}
Major revisions:
 
*Created & documented March 4, 2006 by [[User:Moverton|Moverton]]
 
*Changed to use #if [[m:ParserFunctions|ParserFunctions]] June 17, 2006 by [[User:Moverton|Moverton]] — This change should not impact the function or appearance of any existing usage.
 
*Added optional user defined section links November 17, 2006 by [[User:Moverton|Moverton]] — This change should not impact the function or appearance of any existing usage.
 
*Added optional <code>top</code> parameter December 27, 2006 by [[User:Moverton|Moverton]] — This allows for optional removal of the link to the 'Top of Page'; it should not impact the function of any existing usage.
 
<noinclude>[[Category:Template documentation|{{PAGENAME}}]]</noinclude><includeonly>
 
  
 +
<includeonly>
 
<!-- ADD CATEGORIES BELOW THIS LINE -->
 
<!-- ADD CATEGORIES BELOW THIS LINE -->
[[Category:TOC templates|{{PAGENAME}}]]
+
[[Category:Wikipedia table of contents templates]]
  
 
<!-- ADD INTERWIKIS BELOW THIS LINE -->
 
<!-- ADD INTERWIKIS BELOW THIS LINE -->
[[eu:Txantiloi:Aurkibide alfabetikoa]]
+
[[ca:Plantilla:Índex i taula de contingut opcional]]
[[fr:Modèle:Sommaire compact]]
+
[[ka:თარგი:საძიებელი]]
 
</includeonly>
 
</includeonly>

Latest revision as of 16:47, 17 July 2015

Template:Mbox

{{Alphanumeric TOC}} is a customizable substitute for the (formerly) growing zoo of variants of {{Compact ToC}}. Rather than have dozens of stylistic varieties, it is preferable to have a single template which can be adjusted to fit the editor's wishes.

Usage

Insert the following at the point in the article where you want the TOC to appear: If using with a list, many editors have found it helpful to insert a TOC at both the beginning and end of the list (remember to add |top=yes to the bottom template to quickly get back to the top).

{{alphanumeric TOC}}

Whenever multiple TOCs will be used on a page, and this template will not be the primary one at the top of the page, add |primary=false (this prevents multiple TOCs from showing up in each other's listings):

{{alphanumeric TOC
|primary=false
}}

Options

Alignment

The natural state of the TOC is to appear along the left side of the page without any alignment. To align to the center of the page, add the parameter align with a value of 'center':

{{alphanumeric TOC|align=center}}

The TOC may also be aligned to the right or the left, causing the article text to wrap around it, but floating the TOC is generally discouraged. Guidelines may be found at Help:Section#Floating the TOC.

Prefixing or suffixing links or link descriptions

The template includes the ability to add a prefix to the link with or without displaying it in the TOC. This can also be accomplished with this template by using the parameters prefixLink and prefixDesc; the former adds the prefix to the actual link, and the latter adds the prefix to the text displayed on the page. The suffixLink and suffixDesc parameters work the same way. Examples:

{{alphanumeric TOC|prefixLink=1.}}
{{alphanumeric TOC|prefixLink=hidden|prefixDesc=visible}}
{{alphanumeric TOC|prefixDesc=+}}
{{alphanumeric TOC|suffixDesc=+}}

Standard and custom sections

One of the reasons for having so many different versions of CompactTOC has been that some articles do not have a 'References' section, or the TOC is being used for a list contained within a larger article. This template solves the problem by providing a parameter for each link to be shown. They are as follows:

|numbers=yes
shows the numbers link
|a=, |b=, etc.
shows the link for that letter; alternatively it can be used to create unlinked letters (see example below)
|top=yes
shows the link to the 'Top of Page'
|seealso=yes
shows the link to the 'See also' section
|references=yes
shows the link to the 'References' section
|externallinks=yes
shows the link to the 'External links' section

Some examples:

{{alphanumeric TOC|numbers=yes|i=|n=|x=|z=|references=yes}}
{{alphanumeric TOC|numbers=yes|i=I|j=J|v=V|x=X|top=yes}}
{{alphanumeric TOC| style="text-align:center;" |g=|seealso=yes|externallinks=yes}}

Optional user defined section links

Optional section links may be defined using the parameters |sec1=, |sec2=, |sec3=, |sec4=, and |sec5=, as follows:

{{alphanumeric TOC|numbers=yes|seealso=yes|externallinks=yes|sec1=Added section|sec2=Plus one}}