Template:TOC link/doc

Short usage summary:

About
This template create a link depending on the context of transclusion. It should be used only in a Page:*. It creates either a link to a given page number (in Page:* numbering) passed in parameter 1, or a link (parameter 3) to a subpage name (parameter 2) of a book. This template can also be used outside tables of contents (e.g. "See p. 243").

The process of adding such templates has pretty much been abandoned as it is of low value in the production space (see talk).

Example: Take the book whose title is Transactions of the Geological Society, 1st series, vol. 1 in the main space, the corresponding page names are Page:Transactions of the Geological Society, 1st series, vol. 1.djvu/xxxx where xxxx is the page number in the djvu file;  these pages may have a different number on the scanned book, for instance page #203 in the djvu file may be the scan of p. 191 in the scanned book; so in order to show 191 you write this:


 * 1) In Page:Transactions of the Geological Society, 1st series, vol. 1.djvu/425 the created link is 191.
 * 2) When this page is transcluded in main namespace, the created link is 191 . (see Transactions of the Geological Society, 1st series, vol. 1/Index).
 * 3) Transclusion of a page using this template work also from an Index: page but only if the name of the index is identical to the name of the djvu file, in this case the created link is identical to #1.
 * 4) Parameter 3 is used as anchor, typically this is used in context like (see p. 123) to allow links with anchor from a book to itself.
 * If you would like a link with complex formatting like italics, which cannot be used in links, the optional parameter 4 is used. Parameter 4 will function as the link text, and parameter 3 will function as the link target (i.e. parameter 3 does not have the italic text, and parameter 4 does). An example of this is here, for Chapters 4 & 16, where some words are italic.


 * Notes:
 * that the name of an index must always be the same as the name of the corresponding djvu file; a renaming will be necessary if the names are different, though this is only needed if you want to link from a transcluded Page: in an Index:
 * formatting of text style, eg. small capitals, needs to wrap around the outside of the template, not be placed inside the template

Rationale

 * 1) Using relative links allow to rename works without creating link through redirect, both page in main (top-level page and sub-page should be renamed as a whole) or the djvu and its subpages can be renamed without maintenance burden
 * 2) Avoiding relative links directly in Page:, which create a blue link when transcluded in main but a red link in Page:
 * 3) It avoids a link to Page: in main which can confuse readers if they don't understand what namespace and transclusion are.
 * 4) It allows a short way to express a link from a work to itself.