View source for Template:Harvc/doc

{{Documentation subpage}}
<!-- Place categories where indicated at the bottom of this page and interwikis at Wikidata (see [[Wikipedia:Wikidata]]) -->
{{lua|Module:Harvc}}
{{uses TemplateStyles|Module:Citation/CS1/styles.css|noprotcat=yes}}
This template is a citation hybrid that has characteristics of the long-form [[Help:Citation Style 1|cs1]] and [[Help:Citation Style 2|cs2]] and characteristics of short-form {{tlx|sfn}} and the {{tlx|harv}} 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.  {{tld|harvc}} is not a substitute for a properly constructed citation.

Short-form templates {{tld|sfn}} and {{tld|harv}} are often used to link from an article's references section to a long-form cs1|2 template in a bibliography section:
:{{tld|sfn}} → {{tlx|cite book}}
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.  {{tld|harvc}} 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:
:{{tld|sfn}} → {{tld|harvc}} → {{tld|cite book}}

== Usage ==
The minimal form is:
:<code><nowiki>{{harvc |last=contributor name |year=publication year |c=contribution title |in=source editor/author name}}</nowiki></code>

According to the comments in [[Module:Harvc]], mistaken {{red|Harvc error: no target:}} error messages may be produced when the template is nested in other templates as on documentation pages. The otherwise undocumented parameter, {{para|ignore-err|yes}}, can be added to prevent this.

===Parameters===
{{tld|harvc}} creates a <code>CITEREF</code> anchor from one to four contribution or chapter author surnames ({{para|last''n''}}) and the value in {{para|year}}. This allows {{tld|harvc}} to be the target of a link created by {{tlx|sfn}} or {{tld|harv}} family templates.  From {{para|in{{var|n}}}} and {{para|year}}, {{tld|harvc}} creates a CITEREF link similar to those created by {{tlx|harvnb}} and {{tlx|sfn}}

: '''|anchor-year=''' – optional, for use for author(s) with more than one contribution to the work; requires CITEREF disambiguator; see [[#More than one contribution|Examples]]
: '''|author-link=''' – optional, title of existing Wikipedia article about the first contributor—not the contributor's website; do not wikilink; alias: '''|author-link1='''
:: '''|author-link''n''=''' – optional, title of existing Wikipedia article about contributor''n''; choose ''n'' to match ''n'' in '''|last''n''='''
: '''|author-mask=''m''''' – optional, replaces name of the first contributor with ''m'' (commonly 2) em dashes; alias: '''|author-mask1='''
:: '''|author-mask''n''=''m''''' – optional, replaces name of contributor''n'' with ''m'' em dashes; choose ''n'' to match ''n'' in '''|last''n''='''
:: '''|author-mask{{var|n}}=&lt;{{var|text}}>''' – optional, replaces name of contributor''n'' with &lt;{{var|text}}>
: '''|c=''' – required, the title of chapter or contribution; rendered quoted in upright font; aliases: '''|chapter=''', '''|contribution='''
: '''|display-authors=''' – optional, defines how {{tld|harvc}} displays the contributor list; ignored when '''|name-list-style=harv''':
:: {{para|display-authors}} – when empty or omitted, displays all contributor names in last/first format
:: {{para|display-authors|{{var|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
:: {{para|display-authors|etal}} – displays all contributor names in last/first format and appends et al.
: '''|first=''' – optional, first contributor's given or first name; alias: '''|first1='''
:: '''|first''n''=''' – optional, contributor''n'' given or first name; ''n'' begins at 2 and increases by 1 for each additional '''|first''n''='''
: '''|id=''' – required when {{para|last1}}-{{para|last4}} are the same as {{para|in1}}-{{para|in4}}; otherwise optional.  See [[#Avoiding circular reference|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='''
:: '''|last''n''=''' – optional, contributor''n'' surname or last name; ''n'' begins at 2 and increases by 1 for each additional '''|last''n''=''';
: '''|loc=''' – optional, other location identifier, displays after {{para|p}} or {{para|pp}}
: '''|mode=''' – controls rendered display to match that of adjacent CS1 or CS2 citations; defaults to CS1 style
:: '''|mode=cs2''' – mimic {{tlx|citation}} style (comma separators, no terminal punctuation, static text not capitalized)
: '''|name-list-style=''' – optional, controls contributor name list display style
:: '''|name-list-style=harv''' – mimic {{tld|sfn}} or {{tld|harv}} format (one to four last names); overrides '''|display-authors='''
:: '''|name-list-style=amp''' – inserts an ampersand between the last two contributor names
: '''|nb=''' – optional, when set to <code>yes</code>, instructs {{tld|harvc}} to render source link without parentheses around the year; same format as that produced by {{tlx|harvnb}}
: '''|p=''' – optional, single page number where cited material can be found; aliases: '''|page='''
: '''|pp=''' – optional, multiple page numbers, page ranges, etc where cited material can be found; aliases: '''|pages='''
: '''|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'''
: '''|url-access=''' – optional, use when URL links to a source behind a registration barrier or paywall; inserts [[Help:Citation_Style_1#Registration_or_subscription_required|cs1{{pipe}}2 access icon]]; accepted values are: <code>limited</code>, <code>registration</code>, <code>subscription</code>
: '''|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:

* {{cite book |last=George |first=Ernest J. |last2=Read |first2=Ralph A. |last3=Johnson |first3=R. W. |last4=Ferber |first4=A. E. |title=Soil: The Yearbook of Agriculture 1957 |chapter=Shelterbelts and Windbreaks |editor-last=Stefferud |editor-first=Alfred |year=1957 |publisher=United States Department of Agriculture |chapter-url=//archive.org/stream/yoa1957#page/n785/mode/1up |oclc=704186906}}
* {{cite book |last=Harper |first=V. L. |last2=Frank |first2=Bernard |last3=McQuilkin |first3=W. E. |title=Soil: The Yearbook of Agriculture 1957 |chapter=Forest Practices and Productivity |editor-last=Stefferud |editor-first=Alfred |year=1957 |publisher=United States Department of Agriculture |chapter-url=//archive.org/stream/yoa1957#page/n803/mode/1up |oclc=704186906}}
* {{cite book |last=Stout |first=P. R. |last2=Johnson |first2=C. M. |title=Soil: The Yearbook of Agriculture 1957 |chapter=Trace Elements |editor-last=Stefferud |editor-first=Alfred |year=1957 |publisher=United States Department of Agriculture |chapter-url=//archive.org/stream/yoa1957#page/n167/mode/1up |oclc=704186906}}
* {{cite book |last=Wadleigh |first=C. H. |title=Soil: The Yearbook of Agriculture 1957 |chapter=Growth of Plants |editor-last=Stefferud |editor-first=Alfred |year=1957 |publisher=United States Department of Agriculture |chapter-url=//archive.org/stream/yoa1957#page/n57/mode/1up |oclc=704186906}}

As the list grows longer, the look becomes more cluttered with the unnecessarily repeated detail of full-length citations.  With {{tld|harvc}} editors can link to shorter, less detailed contribution citations using standard implementations of {{tlx|sfn}} templates{{sfn|George|Read|Johnson|Ferber|1957}} and {{tlx|harv}} templates (like this: {{harv|Harper|Frank|McQuilkin|1957}} and also wrapped in {{tag|ref}} tags<ref>{{harvnb|Stout|Johnson|1957}}</ref>). {{tld|harvc}} may also be wrapped in {{tag|ref}} tags so that it becomes part of the article's References section.<ref>{{harvc|last=Benson|first=Ezra Taft|year=1957|chapter=Foreword|url=//archive.org/stream/yoa1957#page/n5/mode/1up|in=Stefferud|p=vi |loc=§2 |ignore-err=yes}}</ref>{{sfn|Wadleigh|1957}}

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

For example, to reference an editor's preface from article text, create a wikilink inside {{tag|ref}} tags:<ref>[[#Stefferud preface|Stefferud 1957]]</ref>
:<code><nowiki><ref>[[#Stefferud preface|Stefferud 1957]]</ref></nowiki></code>
Write a {{tld|harvc}} template with {{para|id|Stefferud preface}} 
:<code><nowiki>{{harvc |last=Stefferud |first=A.|year=1957 |id=Stefferud preface |c=Preface |url=//archive.org/stream/yoa1957#page/n7/mode/1up |in=Stefferud}}</nowiki></code>

====Example references section====
{{reflist}}

====Example bibliography section====
* {{cite book |title=Soil: The Yearbook of Agriculture 1957 |editor-last=Stefferud |editor-first=Alfred |year=1957 |publisher=United States Department of Agriculture |url=//archive.org/stream/yoa1957#page/n2/mode/1up |oclc=704186906 }}
** {{harvc |last=George |first=Ernest J. |last2=Read |last3=Johnson |last4=Ferber |year=1957 |contribution=Shelterbelts and Windbreaks |url=//archive.org/stream/yoa1957#page/n785/mode/1up  |in=Stefferud |ignore-err=yes}}
** {{harvc |last=Harper |first=V. L. |last2=Frank |last3=McQuilkin |year=1957 |contribution=Forest Practices and Productivity |url=//archive.org/stream/yoa1957#page/n803/mode/1up |in=Stefferud |ignore-err=yes}}
** {{harvc |last=Stefferud |first=A.|year=1957 |id=Stefferud preface |c=Preface |url=//archive.org/stream/yoa1957#page/n7/mode/1up |in=Stefferud |ignore-err=yes}}
** {{harvc |last=Stout |first=P. R. |last2=Johnson |year=1957 |c=Trace Elements |url=//archive.org/stream/yoa1957#page/n167/mode/1up |in=Stefferud |ignore-err=yes}}
** {{harvc |last=Wadleigh |first=C. H.|year=1957 |c=Growth of Plants |url=//archive.org/stream/yoa1957#page/n57/mode/1up |in=Stefferud |ignore-err=yes}}

====More than one contribution====
There are times when an author or authors will have contributed more than once to a work.  When this occurs, it is necessary to disambiguate the CITEREF links from the {{tld|harv}} or {{tld|sfn}} templates to the CITEREF id of the appropriate {{tld|harvc}} template.

:{{tld|harv|Author|YYYYa}} → {{tld|harvc|Author|Contribution 1|YYYYa}} → {{tld|citation|...}}}
:{{tld|harv|Author|YYYYb}} → {{tld|harvc|Author|Contribution 2|YYYYb}} ↑

In this example, author David Hunt contributed two appendices to ''Christmas Cacti: The Genus ''Schlumbergera'' and Its Hybrids''.

There are two {{tlx|harvnb}} templates that are disambiguated:
:<code><nowiki>{{harvnb |Hunt |1995a}}</nowiki></code> → {{harvnb |Hunt |1995a}}
:<code><nowiki>{{harvnb |Hunt |1995b}}</nowiki></code> → {{harvnb |Hunt |1995b}}
These link to two {{tld|harvc}} templates which use {{para|anchor-year}} for their CITEREF id and for the date in the {{tld|harvc}} rendering as a visual aid for readers:
*<code><nowiki>{{harvc |in=McMillan |in2=Horobin |last=Hunt |first=David |c=Appendix I Names and synonyms of the species, subspecies and interspecific hybrids |year=1995 |anchor-year=1995a |mode=cs2 |nb=yes}}</nowiki></code>
*:{{harvc |in=McMillan |in2=Horobin |last=Hunt |first=David |c=Appendix I Names and synonyms of the species, subspecies and interspecific hybrids |year=1995 |anchor-year=1995a |mode=cs2 |nb=yes |ignore-err=yes}}
*<code><nowiki>{{harvc |in=McMillan |in2=Horobin |last=Hunt |first=David |c=Appendix III Excerpts from a Brazilian diary |year=1995 |anchor-year=1995b |mode=cs2 |nb=yes}}</nowiki></code>
*:{{harvc |in=McMillan |in2=Horobin |last=Hunt |first=David |c=Appendix III Excerpts from a Brazilian diary |year=1995 |anchor-year=1995b |mode=cs2 |nb=yes |ignore-err=yes}}
and the single {{tld|citation}} template:
*<code><nowiki>{{Citation |last=McMillan |first=A. J. S. |last2=Horobin |first2=J. F. |year=1995 |title=Christmas Cacti: The Genus ''Schlumbergera'' and Its Hybrids |edition=p/b |publication-place=Sherbourne, Dorset, UK |publisher=David Hunt |isbn=978-0-9517234-6-3}}</nowiki></code>
*:{{Citation |last=McMillan |first=A. J. S. |last2=Horobin |first2=J. F. |year=1995 |title=Christmas Cacti: The Genus ''Schlumbergera'' and Its Hybrids |edition=p/b |publication-place=Sherbourne, Dorset, UK |publisher=David Hunt |isbn=978-0-9517234-6-3}}

==Error messages==
{{tld|harvc}} emits these error messages:<!-- 
:<span style="font-size:100%" class="error">harvc: {{para|anchor-year|plain=yes}} missing dab.</span>
::when used, {{para|anchor-year}} must include a single, lowercase letter disambiguator -->
:<span style="font-size:100%" class="error">harvc: author missing from source list.</span>
::the source list parameters {{para|in1}}, {{para|in2}}, {{para|in3}}, and {{para|in4}} form the template's <code>CITEREF</code> link to the full citation.  All are not required but must be used in order without numerical gaps.
:<span style="font-size:100%" class="error">harvc: invalid {{para|anchor-year|plain=yes}}.</span>
::when used, {{para|anchor-year}} must be a three- or four-digit number and must have a lowercase <code>CITEREF</code> disambiguator. When the source does not have an identifiable year, use {{para|anchor-year|n.d.{{var|l}}}} or {{para|anchor-year|nd{{var|l}}}} with lowercase <code>CITEREF</code> disambiguator.
:<span style="font-size:100%" class="error">harvc: invalid {{para|display-authors|plain=yes}}.</span>
::the value assigned to {{para|display-authors}} must be a number greater than 0 or the keyword <code>etal</code>
:<span style="font-size:100%" class="error">harvc: invalid {{para|year|plain=yes}}.</span>
::{{para|year}} is an integral part of the template's <code>CITEREF</code> anchor and link.  The value of {{para|year}} must be a three- or four-digit number with an optional lowercase <code>CITEREF</code> disambiguator. When the source does not have an identifiable year, use {{para|year|n.d.}} or {{para|year|nd}}.
:<span style="font-size:100%" class="error">harvc: missing {{para|year|plain=yes}}.</span>
::{{para|year}} is missing; the parameter is required.
:<span style="font-size:100%" class="error">harvc: no authors in contributor list.</span>
::this error message indicates that {{tld|harvc}} can't find any of {{para|last}}, {{para|last1}}, {{para|author}} or {{para|author1}} with an assigned value and so cannot make a usable <code>CITEREF</code> anchor.  Add at least one of the listed parameters.
:<span style="font-size:100%" class="error">harvc: required contribution is missing.</span>
::this error message indicates that {{tld|harvc}} can't find any of {{para|c}}, {{para|chapter}}, or {{para|contribution}} with an assigned value
:<span style="font-size:100%" class="error">harvc: required {{para|id|plain=yes}} parameter missing.</span>
::this error message is emitted when the {{tld|harvc}} template's <code>CITEREF</code> anchor identifier would conflict with the long-form citation's <code>CITEREF</code> anchor identifier.  See [[#Avoiding circular reference|Examples]]
:<span style="font-size:100%" class="error">harvc: {{para|year|plain=yes}} / {{para|anchor-year|plain=yes}} mismatch.</span>
::the year portion of {{para|anchor-year|YYYY{{var|l}}}} must match the year given in {{para|year|YYYY}}

<includeonly>{{Sandbox other||
<!-- Categories below this line, please; interwikis at Wikidata -->
[[Category:Citation utility templates]]
}}</includeonly>