Wikipedia:Specific-source Template System

Specific-source Template System (SSTS) is for creating and using Category:specific-source templates. It offers a standard interface for multiple host providers (Internet Archive, HathiTrust, Project Gutenberg, Wikisource, Google Books) unifying the features available at each into easily understood and recognizable Wikipedia templates.

Example: {{Cite AIA5 |page=42, 52-60}}

Produces: White, Norval; Willensky, Elliot; Leadon, Fran (2010). AIA Guide to New York City (5th ed.). New York: Oxford University Press. pp. 42, 52-60. ISBN 978-0-19538-386-7.

Note the "42" and "52-60" are automatically linked. This and many other features are available.

There are thousands of specific-source templates (SST) scattered across Wikipedia, listed under Category:Specific-source templates and other places. They are individually built wrapper templates (such as {{Stewart Calculus}} or {{Acad}}) that hardcode CS1/CS2 parameters like the author, title, and publisher so editors do not have to retype them repeatedly. Each template is its own custom-made island of code, often using advanced wikitext programming methods (eg. {{{{1}}}}}}|{{{{}}}). There is no standard for how they work and they often each have peculiarities unique to that one SST.

The Specific-Source Template System (SSTS) is designed specifically for these templates. Driven by Module:SST, it provides SSTs with powerful new features while normalizing their setup and maintenance. The SST System supports commonly linked external services (ie. "hosts") including HathiTrust, Internet Archive, Google Books, Project Gutenberg and Wikisource. It can also support random web links such as a university-hosted PDF file.

Instead of hardcoding book data directly into the individual templates, SSTS stores specific book information in alphabetized files or "shards."

By moving to this system, Wikipedia gains several major advantages:

• Data vs. Programming: The programming and data elements are separated. Template creators do not need to program at all. No advanced wikitext, CS1|2 coding, etc.. new templates can be created by copy paste and data entry.
• Enhanced Features: Features include automatic linking page numbers or groups of numbers, search-inside books, full-screen mode, dummy-search to improve access, ID pooling to mitigate viewing limits, etc..
• Consistent Interface: You don't need to know the ins and outs of each service provider to create URLs. The SST System is a generic front end that hides the complexity behind each hosting provider using a consistent system that works for any host provider.
• Maintainability: If a host changes their URL schematic (like Project Gutenberg did in 2020) you only need to update the SSTS Gutenberg Engine, not 100s of individual URLs spread across 100s of templates.

• Rich page linking features:
  • Link URL(s) to a single page, a range of pages, or groupings of pages eg. 42-44, 64-65
  • Link a URL to Roman Numeral, photos, or any page with or without a printed page number.
  • Link a URL to a chapter or section with the custom |chapter-page= parameter in combination with |chapter=
• Search terms highlight text on the host book, and shows other pages with the same search terms.
  • Each page link can have its own search terms e.g search on "Atlantic" in pp. 42-44 and "Pacific" in pp. 64-65
  • Optional "Dummy search" feature (advantage explained)
• Optional full-screen mode for hosts that support it.
• A single URL to a group of books e.g. the multi-volume set of Encyclopaedia Britannica published in 1911.
• A single URL to multiple works by an author, or any custom combination, using the powerful search capabilities of IA's logical operators e.g. AND, OR, (), etc..
• Declare a book as a physical-only reference, preventing the system from attempting to generate external links.
• ID pooling. Multiple book IDs at the same host can be defined for the same book+edition. The IDs are randomly selected by the template mitigating the chances of host viewing limits.
• Competently handles:
  • Single and multiple volume works
  • Single and multiple edition works
  • Multiple edition + multiple volume works e.g. multiple editions of the multi-volume {{Porsche: Excellence Was Expected}}.
• Automatic optimized updates to Module:Footnotes/whitelist (every 12 hours)

If you are writing or editing an article, using an SSTS-powered template is nearly identical to using any standard citation template.

For example, to cite the book The Ottoman Empire, you would use:

{{The Ottoman Empire |page=45}}

This single line automatically generates a fully formatted citation with the author, title, publisher, and year, while linking to the correct destination URL at page 45.

You have the option to supplement or override parameters.

• Supplement: You can add additional parameters supported by standard citation templates (like {{cite book}} or {{cite encyclopedia}}) such as |quote=, |ref=, etc.
• Override: You can override parameters already defined by the template (for example, providing a custom |url= if you are citing a specific digital scan not mapped by the system).

Because texts have complex publication histories, digital availability may vary by volume. Some volumes may be physical-only, while others may be hosted digitally (e.g., on the Internet Archive, Google Books, or Wikisource). If a specific volume is hosted digitally, the underlying SST Module will automatically generate the correct links and activate the relevant digital features below.

Many historical works span multiple volumes or have been printed in various editions. SSTS templates are built to handle these variations natively. You can pass the |volume= or |edition= parameters exactly as you would in standard wikitext.

Edition:

{{The Ottoman Empire |edition=Second |page=112}}

Volume:

{{The Ottoman Empire |volume=2 |page=112}}

SSTS uses a normalization module that understands that "Second", "2nd", and "2" all mean the same thing, or "Vol. 1", "Volume 1", and "1".

To link to a specific chapter, use |chapter= and |chapter-page=.

{{The Cambridge History of Iran |volume=1 |chapter=Introduction |chapter-page=12}}

The system supports page number formatting of various types:

• |page=42 - single page
• |pages=42-50 - page ranges
• |pages=42, 50, 60 - multiple pages
• |pages=42-49, 50-59, 60-69 - multiple page range groups

All of these will get automatically linked to the specific page numbers.

Because the page number printed on the physical page (e.g., Roman numeral "xii") might not match the digital file's "leaf" or "sequence" number (e.g., scan #7), SSTS uses a special display@machine syntax within the |page= or |pages= parameters to bridge this gap.

• Left of the @: The page number as it is printed in the physical book. This is what readers will see in the citation text.
• Right of the @: The machine code instructing the URL how to find that exact page in the digital archive.

Different digital libraries require slightly different machine codes.

Use the format display@<host code><leaf #>.

• Example Internet Archive: xiii@n7 means printed page "xiii" is located at Internet Archive leaf number 7 (e.g. the URL ../page/n7). Thus, |page=xiii@n7
• Example Google Books: xiii@gPR13 means printed page "xiii" is located at Google Books leaf number 13 (e.g. the URL ...&pg=PR13).

Many digital libraries support a "search inside" feature that automatically highlights a specific word or phrase on the page when the reader opens the link. SSTS allows you to trigger this feature directly from the citation by enclosing your search term in square brackets [] within the |page= or |pages= parameter.

This syntax can be used on its own, or appended to the @ linking syntax.

• Basic search:

  {{The Ottoman Empire |page=42 [Suleiman]}}
  

  Result: Links to printed page 42 and searches the text for the word "Suleiman", highlighting it on the digital scan.

• Combined with leaf linking:

  {{The Ottoman Empire |page=xii@n7 [Constantinople]}}
  

  Result: Displays printed page "xii" in the citation, routes the reader to machine leaf "n7", and searches the page for "Constantinople".

• Multiple terms:

  {{The Ottoman Empire |page=45 [military reform], 57-60 [justinian] }}
  

  Result: You can include multiple search terms one for each page grouping separated by a comma.

Please note that this feature relies on the destination host's capabilities. Based on current engine configurations, search-highlighting is supported by:

• Internet Archive
• HathiTrust
• Google Books

A core feature of this module is its handling of the Internet Archive's restricted viewing modes.

If an editor provides a page number, the module automatically appends that number as a "dummy" search string (e.g., ?q=42). This is a necessary architectural workaround: supplying a search string forces the IA viewer to open and highlight specific pages that might be blocked due to restrictions (similar to Google Books snippet view with search strings).

Creating a new specific-source template requires two steps: creating the front-end template, and adding the book's data to the correct alphabetized "shard."

The front-end template (e.g., {{The Ottoman Empire}}) is a lightweight wrapper that routes the user's input to Module:SST.

Single-book (example template)

<includeonly>{{#invoke:SST|single|id=HISTORY_OF_YOLO_COUNTY}}</includeonly><noinclude>
{{Documentation}}
</noinclude>

• id: The unique base identifier for the book located in the data shard.

If the book has multiple volumes or editions, replace single with set. You can combine it with a {{#switch}} statement and {{Normalize volume and edition}} to route to the correct data block within the book's standalone shard.

Three editions (example template)

<includeonly>{{#invoke:SST|set
| id = IMBER_THE_OTTOMAN_EMPIRE
| key = {{#switch:{{#invoke:Normalize volume and edition|edition|{{{edition|}}}}}
  | 3 | 2019 = 2019
  | 2 | 2009 = 2009
  | 1 | 2002 | #default = 2002
}}
}}</includeonly><noinclude>
{{Documentation}}
</noinclude>

7 volume set (example template)

<includeonly>{{#invoke:SST|set
| id = BYZANTINE_SEALS
| key = {{#switch:{{#invoke:Normalize volume and edition|volume|{{{volume|}}}}}
  | 1 | I = 1
  | 2 | II = 2
  | 3 | III = 3
  | 4 | IV = 4
  | 5 | V = 5
  | 6 | VI = 6
  | 7 | VII = 7
  | all | ALL | #default = ALL
}}
}}</includeonly><noinclude>
{{Documentation}}
</noinclude>

• id: The base identifier for the entire set (maps to the shard filename).
• key: The specific variant key (e.g., 1, 2, ALL) to append to the base ID.

All book metadata is stored in "shards" which are Lua Modules that contain simple tables.

There are two types of shards:

• Single - A single book. They share shard files. For example, all single books that start with "A" are in Module:SST/shards/A
• Sets - Works that have multiple volumes or editions e.g. an Encyclopedia or a 3-edition book. Each one has their own private shard file stored in Module:SST/shards/sets for example Module:SST/shards/sets/THE_CAMBRIDGE_HISTORY_OF_IRAN.

To add a new book, navigate to the correct shard and add a new table. The template documentation page will show where the shard is located.

When creating a new table, use a unique, recognizable book key in ALL CAPS, with spaces converted to underscores. For single shards it must start with the letter of the shard it is placed in. Generally a good idea to start with the author's last name then a short version of the title.

• Example: library['IMBER_THE_OTTOMAN_EMPIRE'] = { ... }

When creating a multi-edition or volume set of books, name each book followed by a number for volumes e.g. _1 and _2 .. or by a year of publication e.g. _1990 and _2002 for editions.

• Example single edition

BOWEN_THE_LIFE_AND_TIMES_OF_AL_IBN_ISA

• Example multi-edition set

IMBER_THE_OTTOMAN_EMPIRE_2002

IMBER_THE_OTTOMAN_EMPIRE_2009

• Example multi-volume set

BYZANTINE_SEALS_1

BYZANTINE_SEALS_2

The |host= sets which digital library the citation will link to.

library['IMBER_THE_OTTOMAN_EMPIRE'] = {
    ['host'] = "ia",
    ['cite_params'] = {
    .....
    }

Valid values for |host= are "ia", "guten", "hathi", "wikisrc", "gbook", "web" and "physical" (not online). These map to a corresponding |id= in the |hosts= entry (see below). Improper values or lack of a host will default to "physical" (no external links).

If a |host= is changed (e.g. from "hathi" to "ia") this will impact the Leaf page designations for every template on Wikipedia. For example Hathi uses 42@s54 while IA uses 42@n34. A change of |host= is disruptive, causing URLs to land on the wrong page. Tools will be in development to make |host= changes easier by automating the update of templates. Until then, it is better to consider the host "locked".

A table of CS1 parameters displayed by default. (Users can override these within the invoking templates.)

• |_template=: Optional. Defaults to cite book, can also be set to cite encyclopedia (more template support in future).
• |last=, |first=, |quote=, |ref=, etc. = Standard CS1 parameters.

    ['host'] = "ia",
    ['cite_params'] = {
        ['_template'] = 'cite book',
        ['last'] = "Birtchnell",
        ['first'] = "Percy Charles",
        ['author-link'] = "Percy Birtchnell",
        ['title'] = "A Short History of Berkhamsted",
        ['year'] = "1972",
        ['edition'] = "Revised",
        ['publisher'] = "Privately printed",
        ['place'] = "Berkhamsted",
        ['oclc'] = "737328"
    },

A nested table defining where the book can be found online and how the routing engines should handle it. Supported host keys are |ia= (Internet Archive), |hathi= (HathiTrust), |guten= (Project Gutenberg), |wikisrc= (Wikisource), |gbook= (Google Books), |web= (Other website), and |physical= (No digital host). You can add multiple hosts for each book, which one is used is defined by |host= (see above).

• |id= = The host-specific identifier.
  • IA: The ID from the URL. Multiple IDs for the same edition can be defined see Example setup.
  • Hathi: The handle ID
  • GBook: The 12-character ID
  • Wikisource: The full Page namespace name, including extension
  • Web: For a web host, omit id. See Example setup.

• Physical: A physical copy only - for books without a digital host. See Example setup.

    ['hosts'] = {
        ['ia'] = {
            ['id'] = "encyclopaediabrit01chisrich",
        }
    }

    ['hosts'] = {
        ['ia'] = {
            ['id'] = { 
                "nebraskaplacenam00fitz", 
                "nebraskaplacenam0000fitz" 
            }
        }
    }

    ['hosts'] = {
        ['hathi'] = {
            ['id'] = "iau.31858015245842",
        }
    }

    ['hosts'] = {
        ['gbook'] = {
            ['id'] = "-CNkywAACAAJ",
        }
    }

    ['hosts'] = {
        ['wikisrc'] = {
            ['id'] = "Page:The Fun of It.pdf",
        }
    }

    ['hosts'] = {
        ['web'] = {
            ['url'] = "http://www.uscoldwar.com/overview.htm",
        }
    }

    ['hosts'] = {
        ['physical'] = {}
    }

• Internet Archive Options:

• query = (Internet Archive only). Optional. Use instead of `id` for multi-volume works. Links the main title to an IA search page. Page linking will output as unlinked plain text. (ex. `query = 'title:"Encyclopaedia Britannica" AND date:1911'`)
• iadisplay = "full screen" (Internet Archive only). Optional. Opens the book in full-screen mode instead of the default 2-up view.
• iasearch = "none" or "pagenum" (Internet Archive only). Optional. Set to "none" to disable the dummy search for PD books.

    ['hosts'] = {
        ['ia'] = {
            ['query'] = "title:Britannica AND year:1911",
        }
    }

    ['hosts'] = {
        ['ia'] = {
            ['id'] = "encyclopaediabrit01chisrich",
            ['iasearch'] = "none",
            ['iadisplay'] = "full screen"
        }
    }

Some hosts have multiple copies of the same book+edition. This can be useful to mitigate viewing limits. Many hosts only allow X number of views per day per book. By including multiple IDs, you can spread the load across multiple IDs. Because the template randomly chooses real-time, it is important each book be identical ie. published in the same year, same publisher, each open to the same page 42 etc.. How to add multiple identical books:

    ['hosts'] = {
        ['ia'] = {
            ['id'] = { 
                "nebraskaplacenam00fitz", 
                "nebraskaplacenam0000fitz" 
            }
        }
    }

Load sharing is not available across hosts (inter-host), only within hosts (intra-host).

SSTS is built on a modular architecture to ensure scalability and ease of maintenance. When an editor invokes a template, the data flows through four layers:

• Front-End Template: (e.g., {{The Ottoman Empire}}) This is the user-facing layer. It captures the editor's parameters (like |page= or |edition=) and calls the router.
• The Router: (Module:SST) The core traffic controller. It validates the request, determines which alphabetized shard to load based on the Book Key, and calls the appropriate host engine.
• The Data Shards: (e.g., singles at Module:SST/shards/B and sets at Module:SST/shards/sets/BYZANTINE_SEALS) These files act as the system's database. They store the CS1/CS2 parameters and the host-specific IDs for each book.
• The Host Engines: (Module:SST/hosts) This module contains the specific URL-building logic for each digital library (Internet Archive, HathiTrust, etc.). It parses the @ and [] syntax, calculates the final URLs, formats the deep-links, and assembles the final citation.

To ensure the system remains robust and that broken links do not linger in articles, SSTS includes built-in error handling.

If a template is configured incorrectly or calls missing data, the router will output a bold, red error message directly in the citation to alert the editor. Common errors include:

• SST Error: Unsupported host '...'
• SST Error: Book key '...' not found in shard '...'

The module utilizes tracking categories.

• Fatal Execution Errors: If the module encounters a system failure (e.g., an unsupported host engine) or a native CS1 red error, it outputs a bold red error message in the citation and categorizes the page into Category:SSTS errors.
• Missing Records: If a citation requests a book key, shard, or volume that does not exist in the database, it outputs a visible error and categorizes the page into Category:SSTS missing records.
• Parameter Logic Faults: If an editor uses an invalid combination of parameters that conflicts with the shard's architecture (e.g., adding |title= or |article= to a {{cite encyclopedia}}), the module will attempt to silently resolve the citation to prevent a red error, but will flag the page in the hidden category Category:SSTS parameter logic faults.

• {{Location map}} - uses a similar architecture of many sub-modules