வார்ப்புரு:TOC templates/doc என்பதற்கான மூலத்தைப் பார்

<templatestyles src="TOC templates/doc/styles.css" />
{{documentation subpage|e.g.[[Template:TOC begin|TOC begin]]}}
{{uses TemplateStyles|Template:TOC templates/styles.css}}

==Usage==
These templates are designed to aid in producing tables of contents (TOCs) using a standardised set of table sections. They are begun with a {{tl|TOC begin}} and are ended with {{tl|TOC end}}.

The aim of these templates is to divorce the TOC from the underlying code. If you have a new circumstance to format, perhaps the best option is to make a new template, rather than hack an old one to fit.

===TOC begin===

;Parameters
* {{parameter|align}}: alignment of the table on the page, defaults to central (optional)
* {{parameter|width}}: table width (optional, any CSS units), <code>| width = 100%</code>
* {{parameter|max-width}}: table max-width (optional, any CSS units), <code>| max-width = 35em</code>
* {{parameter|sc}}: applies small-caps to the entire table (optional), <code>| sc = yes</code>
* {{parameter|asc}}: applies all-small-caps to the entire table (optional), <code>| asc = yes</code>
* {{parameter|style}}: applies any other free-form style to the entire table (optional/no default), <code>| style = line-height:1</code>
* {{parameter|plus}}: allows addition of separate code (optional), e.g. to set table attributes <syntaxhighlight lang="wikitext" inline="true">| plus = id {{=}} "example-table"</syntaxhighlight> {{fine|(see [[mw:Help:Extension:ParserFunctions#Raw_equal_signs]])}}
* {{parameter|caption}}: Add a table caption

===Naming convention===

Templates are named by the colspan of their cells (in order) and the salient feature of any cells that are not "normal".

For example, a row of three single cells is {{tl|TOC row 1-1-1}}, and a row with a colspan-2 cell followed by a single cell is {{tl|TOC row 2-1}}. If a cell has no colspan but a salient feature, the "1" from that cell is omitted: {{tl|TOC row 1-out-1}}

=== Parameters ===

* The positional parameters {{parameter|1}}, {{parameter|2}}, etc, contain the contents of the first, second, etc. table cells.
* most row templates have an optional {{parameter|class}} parameter that can be used to target additional [[Help:Page styles|Page styles]] CSS to that row.
** The class <code>wst-toc-aux</code> formats the row with a green background to indicate that the row is a Wikisource addition, e.g. for a preface that wasn't in the original TOC.
<!-- please don't add a style parameter unless you are really really sure it absolutely can't use index CSS -->

===Special cases===
* {{tl|TOC row l}}: a single cell, text left-aligned, with a colspan given in the first parameter, and contents in the second.
* {{tl|TOC row c}}: a single cell, text centred, with a colspan given in the first parameter, and contents in the second.
* {{tl|TOC row r}}: a single cell, text right-aligned, with a colspan given in the first parameter, and contents in the second.

===3-column tables===

3-column tables are perhaps the most common type. The "normal" condition is for the first and last columns to be right-aligned, and the middle column to be left aligned.

* {{tl|TOC row 1-1-1}}: three single cells, right-left-right aligned, respectively
* {{tl|TOC row 2-1}}: a <code>colspan=2</code> cell and a normal cell. Left and right aligned respectively.

;Hanging indents
* {{tl|TOC row 1-out-1}}: three single cells, but the middle cell has a {{tl|hanging indent}} applied.
* {{tl|TOC row 2out-1}}: same as "2-1", but the first cell has a hanging indent.
* {{tl|TOC row 1-dot-1}}: same as "1-out-1", but the middle cell also has a dot-leader
** Optional: use {{parameter|symbol}} to set dot character(s) and {{parameter|spaces}} to set number of spaces (default: one dot and 5 spaces)
* {{tl|TOC row 2dot-1}}: same as "2out-1", but the first cell is the "main" cell and has a dot-leader appended.

;Different alignment of the main cell
* {{tl|TOC row 1-r-1}}: three single cells, left-right-right aligned, respectively.
* {{tl|TOC row 1-c-1}}: three single cells, left-center-right aligned, respectively.

====Example====
{{TOC begin|width=60em|caption=This is the caption}}
{{TOC row c | 3  | {{x-larger|Table of Contents: {{tl|TOC row c}}}} }}
{{TOC row 2-1    | Introduction, Preface and Other Front Matter : {{tl|TOC row 2-1}}|1}}
{{TOC row 1-1-1  | 1 |Chapter 1: {{tl|TOC row 1-1-1}}|2}}
{{TOC row 1-1-1  | 2 |Chapter 2: {{tl|TOC row 1-1-1}} {{lorem ipsum}}|3}} 
{{TOC row r | 3  | {{tl|TOC row r}} Plates illustrating various things }}
{{TOC row 1-out-1 |3 |Chapter 3: {{tl|TOC row 1-out-1}} {{lorem ipsum}}|4}} 
{{TOC row 2out-1  | {{tl|TOC row 2out-1}} {{lorem ipsum}}|5}}
{{TOC row 1-dot-1 |4 |Chapter 4: {{tl|TOC row 1-dot-1}} {{lorem ipsum}}|6}} 
{{TOC row 2dot-1  | {{tl|TOC row 2dot-1}} {{lorem ipsum}}|7}}
{{TOC end}}

===4-column tables===

The "normal" condition is for the first, second and last columns to be right-aligned, and the third column to be left aligned. The third column is usually (not always) the large "main" cell.

* {{tl|TOC row 1-1-1-1}}
* {{tl|TOC row 2-1-1}}
* {{tl|TOC row 1-2-1}}
* {{tl|TOC row 1-2dot-1}}
* {{tl|TOC row 1-2out-1}}
* {{tl|TOC row 3-1}}
* {{tl|TOC row 1-1-dot-1}}
* {{tl|TOC row 3dot-1}}
* {{tl|TOC row 2dot-1-1}} (uses the first, double, column as the main cell, so it's usually not compatible with rows that have "short" initial cells)
* {{tl|TOC row 2dot-dot-1}}

{{TOC begin|width=60em}}
{{TOC row c | 4  | {{x-larger|Table of Contents: {{tl|TOC row c}}}} }}
{{TOC row 3-1 | Prefatory Notice {{tl|TOC row 3-1}}|i}}
{{TOC row 2-1-1  | Introduction | {{tl|TOC row 2-1-1}}|1}}
{{TOC row 1-1-1-1| 1 | a |Section 1: {{tl|TOC row 1-1-1-1}}|2}}
{{TOC row 1-1-1-1|   | b |Section 2: {{tl|TOC row 1-1-1-1}} {{lorem ipsum}}|3}}
{{TOC row 1-2-1| 2 | {{tl|TOC row 1-2-1}} {{lorem ipsum}}|4}}
{{TOC row 1-2dot-1| 3 | {{tl|TOC row 1-2dot-1}} {{lorem ipsum}}|5}}
{{TOC row 1-2out-1| 3 | {{tl|TOC row 1-2out-1}} {{lorem ipsum}}|5}}
{{TOC row 3-1| {{tl|TOC row 3-1}} {{lorem ipsum}}|6}}
{{TOC row 3dot-1| {{tl|TOC row 3dot-1}} {{lorem ipsum}}|7}}
{{TOC end}}

{{TOC begin|width=60em}}
{{TOC row c | 4  | {{x-larger|Table of Contents: {{tl|TOC row c}}}} }}
{{TOC row 2dot-1-1|{{tl|TOC row 2dot-1-1}} {{lorem ipsum}} | 1 | 2}} 
{{TOC end}}

===Ragged-row tables===

Some works have TOCs which have a variably-sized right column, with the left column of other rows sometimes overlapping it. This is often found in periodicals where multiple parts of a serial work are listed on the same line.

* {{tl|TOC row ragged}}: 
** {{parameter|1}} is the left-aligned main content
** {{parameter|2}} is the right "column".
** {{parameter|colspan}} is the colspan of the whole row to allow it to work with other row templates. Default is 3 (so it will work by default with {{tl|TOC row 1-1-1}}, for example).
** {{parameter|margin}} is the size of the inset of the entry from left. Default is 2em.
** {{parameter|indent}} is the size of the overhang of the first line. Default is 2em.

{{TOC begin|width=25em}}
{{TOC row ragged|Letter to the Editor respecting the New Monthly Magazine|1}}
{{TOC row ragged|Grimm's Ghost, Letter X.|38, XI. 199, XII. 365}}
{{TOC end}}

If a single ragged entry spans multiple pages, the templates {{tl|TOC row ragged/s}} and {{tl|TOC row ragged/e}} should be used, with the page numbers specified as parameter {{parameter|1}} of {{tl|TOC row ragged/e}}. The margin parameters of {{tl|TOC row ragged/e}} and {{tl|TOC row ragged/s}} should be the same.

*{{tl|TOC row dotragged}}: dotted version

=== Very long tables ===
For very long tables, the row class declarations make it all much too large. Instead, there are minimal templates that do not have the classes. A class of [[Template:TOC templates/styles.css]], such as __toc_row_1-m-1-1, should be added manually (and possibly overriden by the other TOC row's).

These templates are called TOC row min-[col], where [col] is the number of columns. There are currently from 1 to 5 columns.

=== Auxiliary (added) content ===

Sometimes, the original TOC does not include content such as a preface. This has to be linked to somewhere on the work's main page so that the [[Help:Preparing for export|exporter]] can pick it up and include it in the output. The <code>wst-toc-aux</code> class allows you to visually (and semantically) mark any row as "auxiliary content". You may wish to add text to explain this clearly.

{{Doc example|margin-left=4em|title=Marking auxiliary content|content=
<pre>
{{TOC begin|width=35em}}
|+ CONTENTS
{{TOC row 2-1|class=wst-toc-aux|Preface {{Smaller|(not in original TOC)}}}}
{{TOC row 2-1|Chapter 1 | 1}}
{{TOC row 2-1|...}}
{{TOC end}}
}}
</pre>
{{TOC begin|width=35em}}
{{!}}+ CONTENTS
{{TOC row 2-1|class=wst-toc-aux|Preface {{Smaller|(not in original TOC)}}}}
{{TOC row 2-1|Chapter 1 | 1}}
{{TOC row 2-1|...}}
{{TOC end}}
}}

==Page breaking==

If a table is broken across multiple pages, as is common for long TOCs, you need to add a {{tl|nop}} to the top of every page body, to prevent the transclusion running the last line of the previous page into the first line of that page. You also need to put a {{tl|TOC begin}} in the header of the page to make it render properly in the Page: [[H:NS|namespace]], and you should close the table in the footer of every page except the last:

;First page body
<pre>
{{TOC begin}}
{{TOC row.....}}
</pre>

;First page footer
<pre>
{{TOC end}}
</pre>

;Middle page header
<pre>{{TOC begin}}</pre>

;Middle pages body
<pre>
{{nop}}
{{TOC row.......}}
{{TOC row.......}}
</pre>

;Middle pages footer
<pre>{{TOC end}}</pre>

;Last page header
<pre>{{TOC begin}}</pre>

;Last page body
<pre>
{{nop}}
{{TOC row....}}
{{TOC end}}
</pre>

== Exporting ==

These templates should export well:

* They produce a single contiguous table, which means alignment should be maintained even in simple HTML engines (unlike, for example, {{tl|TOCstyle}})
* The CSS is designed to enable reasonably responsive design compared to "minimally-styled" tables. For example:
** A <code>max-width:100%;</code> is applied to prevent the table extending off the right of a narrow page.
** Vertical alignments are set to avoid "middle-floating" cells when one cell wraps. Many TOCs will start wrapping on Mobile or e-reader screens when they do not on the desktop web interface.
** Text wrapping is disabled by default for the "small" cells: some engines will attempt to hyphenate longer numbers like "1234" or "xxxviii" otherwise. This may happen anyway on some devices.

Dot-leaders are disabled on export, as in the other dot-leader templates, because no known e-reader engine displays anything other than a field of dots. However, the table will otherwise export correctly.

== Tracking ==

Some common issues are tracked by special categories:

* [[:Category:TOC begin usage with errors]]: when the {{parameter|style}} parameter contains quotes (this is likely a mistake)
* [[:Category:TOC begin usage with widths in px or percent]]: setting {{parameter|width}} in units of percent or px is likely to be better expressed in a text-relative unit like ''em'' (see also [[H:PXWIDTH]])

==See also==
{{#lst:Help:Templates|navigation templates}}

<!-- template categories and interwiki links -->
<includeonly>{{sandbox other||
[[Category:TOC templates]]
}}</includeonly>