ਫਰਮਾ:TOC templates/doc

This is a documentation subpage for e.g.TOC begin.
It contains usage information, categories and other content that is not part of the original ਫਰਮਾ page.

This template 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 {{TOC begin}} and are ended with {{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

align: alignment of the table on the page, defaults to central (optional)
width: table width (optional, any CSS units), | width = 100%
max-width: table max-width (optional, any CSS units), | max-width = 35em
sc: applies small-caps to the entire table (optional), | sc = yes
asc: applies all-small-caps to the entire table (optional), | asc = yes
style: applies any other free-form style to the entire table (optional/no default), | style = line-height:1
plus: allows addition of separate code (optional), e.g. to set table attributes | plus = id {{=}} "example-table" (see mw:Help:Extension:ParserFunctions#Raw_equal_signs)
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 {{TOC row 1-1-1}}, and a row with a colspan-2 cell followed by a single cell is {{TOC row 2-1}}. If a cell has no colspan but a salient feature, the "1" from that cell is omitted: {{TOC row 1-out-1}}

Parameters

The positional parameters 1, 2, etc, contain the contents of the first, second, etc. table cells.
most row templates have an optional class parameter that can be used to target additional Page styles CSS to that row.
- The class wst-toc-aux 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.

Special cases

{{TOC row l}}: a single cell, text left-aligned, with a colspan given in the first parameter, and contents in the second.
{{TOC row c}}: a single cell, text centred, with a colspan given in the first parameter, and contents in the second.
{{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.

{{TOC row 1-1-1}}: three single cells, right-left-right aligned, respectively
{{TOC row 2-1}}: a colspan=2 cell and a normal cell. Left and right aligned respectively.

Hanging indents

{{TOC row 1-out-1}}: three single cells, but the middle cell has a {{hanging indent}} applied.
{{TOC row 2out-1}}: same as "2-1", but the first cell has a hanging indent.
{{TOC row 1-dot-1}}: same as "1-out-1", but the middle cell also has a dot-leader
- Optional: use symbol to set dot character(s) and spaces to set number of spaces (default: one dot and 5 spaces)
{{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

{{TOC row 1-r-1}}: three single cells, left-right-right aligned, respectively.
{{TOC row 1-c-1}}: three single cells, left-center-right aligned, respectively.

Example

ਫਰਮਾ:TOC row c

ਫਰਮਾ:TOC row r ਫਰਮਾ:TOC row 1-out-1 ਫਰਮਾ:TOC row 2out-1 ਫਰਮਾ:TOC row 1-dot-1

This is the caption
Introduction, Preface and Other Front Matter : {{TOC row 2-1}}		1
{{TOC row 2dot-1}} Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. ਫਰਮਾ:Dotted TOC page listing/5		7

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.

{{TOC row 1-1-1-1}}
{{TOC row 2-1-1}}
{{TOC row 1-2-1}}
{{TOC row 1-2dot-1}}
{{TOC row 3-1}}
{{TOC row 1-1-dot-1}}
{{TOC row 3dot-1}}
{{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)

ਫਰਮਾ:TOC row c ਫਰਮਾ:TOC row 3-1 ਫਰਮਾ:TOC row 2-1-1 ਫਰਮਾ:TOC row 1-2-1 ਫਰਮਾ:TOC row 1-2dot-1 ਫਰਮਾ:TOC row 3-1 ਫਰਮਾ:TOC row 3dot-1

1	a	Section 1: {{TOC row 1-1-1-1}}	2
	b	Section 2: {{TOC row 1-1-1-1}} Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.	3

ਫਰਮਾ:TOC row c ਫਰਮਾ:TOC row 2dot-1-1

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.

{{TOC row ragged}}:
- 1 is the left-aligned main content
- 2 is the right "column".
- 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 {{TOC row 1-1-1}}, for example).
- margin is the size of the inset of the entry from left. Default is 2em.
- indent is the size of the overhang of the first line. Default is 2em.

ਫਰਮਾ:TOC row ragged ਫਰਮਾ:TOC row ragged

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

{{TOC row dotragged}}: dotted version

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 exporter can pick it up and include it in the output. The wst-toc-aux class allows you to visually (and semantically) mark any row as "auxiliary content". You may wish to add text to explain this clearly.

Example: Marking auxiliary content

{{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}}
}}

CONTENTS
Preface (not in original TOC)
Chapter 1		1
...

Page breaking

If a table is broken across multiple pages, as is common for long TOCs, you need to add a {{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 {{TOC begin}} in the header of the page to make it render properly in the Page: namespace, and you should close the table in the footer of every page except the last:

First page body

{{TOC begin}}
{{TOC row.....}}

First page footer

{{TOC end}}

Middle page header

{{TOC begin}}

Middle pages body

{{nop}}
{{TOC row.......}}
{{TOC row.......}}

Middle pages footer

{{TOC end}}

Last page header

{{TOC begin}}

Last page body

{{nop}}
{{TOC row....}}
{{TOC end}}

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, {{TOCstyle}})
The CSS is designed to enable reasonably responsive design compared to "minimally-styled" tables. For example:
- A max-width:100%; 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 style parameter contains quotes (this is likely a mistake)
Category:TOC begin usage with widths in px or percent: setting width in units of percent or px is likely to be better expressed in a text-relative unit like em (see also H:PXWIDTH)