Template:Harvc/doc

This template is a citation hybrid that has characteristics of the long-form cs1 and cs2 and characteristics of short-form and the  families of templates. Its purpose is to provide a method that allows editors to refer to a contribution or chapter in a larger work when more than a few such referrals are required. is not a substitute for a properly constructed citation.

Short-form templates and  are often used to link from an article's references section to a long-form cs1|2 template in a bibliography section:

It is not uncommon for a source have multiple contributors. When it is necessary to refer to multiple contributions in the same source, repeating all of the bibliographic details in multiple long-form citation templates adds to references-section clutter. is designed to hold only the detail necessary to identify a contribution and link to the enclosing work's long-form citation where all of the bibliographic detail can be found:

Usage
The minimal form is:

Parameters
creates a  anchor from one to four contribution or chapter author surnames (lastn) and the value in year. This allows to be the target of a link created by  or  family templates. From inn and year, creates a CITEREF link similar to those created by  and


 * |author-link= – optional, title of existing Wikipedia article about the first contributor—not the contributor's website; do not wikilink; alias: |author-link1=
 * |author-linkn= – optional, title of existing Wikipedia article about contributorn; choose n to match n in |lastn=
 * |author-mask=m – optional, replaces name of the first contributor with m (commonly 2) em dashes; alias: |author-mask1=
 * |author-maskn=m – optional, replaces name of contributorn with m em dashes; choose n to match n in |lastn=
 * |c= – required, the title of chapter or contribution; rendered quoted in upright font; aliases: |chapter=, |contribution=
 * |display-authors= – optional, defines how displays the contributor list; ignored when |name-list-format=harv:
 * display-authors – when empty or omitted, displays all contributor names in last/first format
 * n – displays n contributor names in last/first format; appends et al. when n is less than the number of contributors included in the template
 * etal – displays all contributor names in last/first format and appends et al.
 * |first= – optional, first contributor's given or first name; alias: |first1=
 * |firstn= – optional, contributorn given or first name; n begins at 2 and increases by 1 for each additional |firstn=
 * |id= – required when last1-last4 are the same as in1-in4; otherwise optional. See Examples
 * |in= – required, surname or last name of first editor or author of the work that includes the contribution; aliases: |in1=
 * |in2= – optional, surname or last name of second editor or author
 * |in3= – optional, surname or last name of third editor or author
 * |in4= – optional, surname or last name of fourth editor or author
 * |last= – required, surname or last name of first author; aliases: |last1=
 * |lastn= – optional, contributorn surname or last name; n begins at 2 and increases by 1 for each additional |lastn=;
 * |last-author-amp=: – optional, when set to yes, inserts an ampersand between the last two contributor names
 * |loc= – optional, other location identifier, displays after p or pp
 * |mode= – controls rendered display to match that of adjacent CS1 or CS2 citations; defaults to CS1 style
 * |mode=cs2 – mimic style (comma separators, no terminal punctuation, static text not capitalized)
 * |name-list-format= – optional, controls contributor name list display style
 * |name-list-format=harv – mimic or  format (one to four last names); overrides |display-authors=
 * |p= – optional, single page number where cited material can be found
 * |pp= – optional, multiple page numbers, page ranges, etc where cited material can be found
 * |ps= – optional, sets terminal punctuation; default is full stop; overrides |mode=cs2; aliases: |postscript=
 * |ps=none – renders output without terminal punctuation
 * |url= – optional, URL of an online location where the text of the contribution can be found; aliases: |chapter-url, |contribution-url
 * |year= – required, publication year of the work that includes the contribution

Examples
When a Wikipedia article makes reference to a work that contains multiple chapters by different authors, bibliographies and reference sections can look rather cluttered:



As the list grows longer, the look becomes more cluttered with the unnecessarily repeated detail of full-length citations. With editors can link to shorter, less detailed contribution citations using standard implementations of  templates and  templates (like this:  and also wrapped in  tags ). may also be wrapped in  tags so that it becomes part of the article's References section.

Avoiding circular reference
It may sometimes be necessary to cite a contribution of a source's editor or author such that last1 through last4 are the same as in1 through in4, an editor's preface for example. Such citations can, depending on placement, cause or -family references to link directly to the citation instead of to the  template, or cause circular links ( linking to itself because its   anchor identifier is the same as the citation's   anchor identifier). If id is set, will use it as an anchor identifier; if id is not set,  will emit an error message when last1 through last4 are the same as in1 through in4.

For example, to reference an editor's preface from article text, create a wikilink inside  tags:

Write a template with Stefferud preface

Error messages
emits these error messages:
 * harvc: author missing from source list.
 * the source list parameters in1, in2, in3, and in4 form the template's  link to the full citation.  All are not required but must be used in order without numerical gaps.
 * harvc: invalid |display-authors=.
 * the value assigned to display-authors must be a number greater than 0 or the keyword
 * harvc: invalid or missing year.
 * year is an integral part of the template's  anchor and link.  The value of year must be a three- or four-digit number with an optional lowercase   disambiguator. When the source does not have an identifiable year, use n.d. or nd.
 * harvc: no authors in contributor list.
 * this error message indicates that can't find last or last1 with an assigned value and so cannot make a usable   anchor without contributors.  Add at least one lastn parameter.
 * harvc: required contribution is missing.
 * this error message indicates that can't find any of c, chapter, or contribution with an assigned value
 * harvc: required &#124;id= parameter missing.
 * this error message is emitted when the template's   anchor identifier would conflict with the long-form citation's   anchor identifier.  See Examples

TemplateData
{ "description": "A method for referring to a contribution or chapter in a larger work when more than a few such referrals are required. harvc is not a substitute for a properly constructed citation.", "params": { "author-link": { "aliases": ["author-link1"], "description": "title of existing Wikipedia article about the contributor—not the contributor's website; do not wikilink", "type": "string" },	"author-linkn": { "description": "title of existing Wikipedia article about contributor n; n begins at 2 and increases by 1 for each additional |author-linkn=", "type": "string" },	"author-mask1": { "aliases": ["author-mask1"], "description": "replaces name of the first contributor with m (commonly 2) em dashes", "type": "string" },	"author-maskn": { "description": "replaces name of contributor n with m em dashes; n begins at 2 and increases by 1 for each additional |author-maskn=", "type": "string" },	"c": { "aliases": ["chapter", " contribution"], "description": "the title of chapter or contribution; rendered quoted in upright font", "type": "string", "required": true },	"display-authors": { "description": "defines how harvc displays the contributor list. When empty or omitted, contributor list mimics the style of cs1 and cs2 templates. When set to number n, displays n contributor first and last names; appends et al. when the template displays fewer contributors than are included in the template. When set to 'etal', displays all of the included contributor first and last names and appends et al.", "type": "string" },	"first": { "aliases": ["first1"], "description": "given or first name of the contribution's first author; requires |display-authors=", "type": "string" },	"firstn": { "description": "contributor's given or first name; n begins at 2 and increases by 1 for each additional |firstn=", "type": "string" },	"id": { "description": "required when |last1=-|last4= are the same as |in1=-|in4=; otherwise optional", "type": "string" },	"in": { "aliases": ["in1"], "description": "surname or last name of primary editor or author of the work that includes the contribution", "type": "string", "required": true },	"in2": { "description": "surname or last name of second editor or author", "type": "string" },	"in3": { "description": "surname or last name of third editor or author", "type": "string" },	"in4": { "description": "surname or last name of fourth editor or author", "type": "string" },	"last": { "aliases": ["last1"], "description": "surname or last name of primary author", "type": "string", "required": true },	"lastn": { "description": "contributor's surname or last name; n begins at 2 and increases by 1 for each additional |lastn=", "type": "string", },	"loc": { "description": "other in-source location identifier, displays after |p= or |pp=", "type": "string" },	"mode": { "description": "controls rendered display to match that of adjacent cs1 or cs2 citations; defaults to cs1 style; set |mode=cs2 to mimic citation template style", "type": "string" },	"p": { "description": "single page number where cited material can be found", "type": "string" },	"pp": { "description": "multiple page numbers, page ranges, etc where cited material can be found", "type": "string" },	"ps": { "aliases": ["postscript"], "description": "sets terminal punctuation; default is full stop for cs1 style, defaults to no punctuation when |mode=cs2; for no terminal punctuation use |ps=none", "type": "string" },	"url": { "description": "URL of an online location where the text of the contribution can be found", "type": "string" },	"year": { "description": "publication year of the work that includes the contribution", "type": "date", "required": true } } }