View source for h-cite

<dfn style="font-style:normal;font-weight:bold">h-cite</dfn> is a simple, open format for publishing citations and references to online and other publications. h-cite is one of several open [[microformats|microformat]] draft standards suitable for embedding data in HTML/HTML5.

;<span id="Status">Status</span>
:This is a '''Draft Specification'''
;Participate
:[[IRC]]: [irc://irc.libera.chat/microformats #microformats on Libera]
;Editor
:<span class="h-card vcard"><span class="p-name fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="p-role role">Editor</span>)</span>
;License
:{{cc0-owfa-license}}
<span style="float:right">__TOC__</span>

== Example ==
Here is a simple minimal abstract web citation example:
<syntaxhighlight lang="html">
<span class="h-cite">
  <time class="dt-published">YYYY-MM-DD</time> 
  <span class="p-author h-card">AUTHOR</span>: 
  <cite><a class="u-url p-name" href="URL">TITLE</a></cite>
</span>
</syntaxhighlight>

=== Get started ===
The class '''<code>h-cite</code>''' is a ''root class name'' that indicates the presence of an h-cite.

The classes '''<code>dt-published</code>''', '''<code>p-author</code>''', '''<code>p-name</code>''', and '''<code>u-url</code>''' define  ''properties'' of the h-cite. 

The class '''<code>h-card</code>''' on the same <code>&lt;span&gt;</code> as '''<code>p-author</code>''' indicates the presence of a nested [[h-card]] microformat as the '''author''' of the h-cite.

== Properties ==
h-cite properties (inside class <code>'''h-cite'''</code>)

* '''<code>p-name</code>''' - name of the work
* '''<code>dt-published</code>''' - date (and optionally time) of publication
* '''<code>p-author</code>''' - author of publication, with optional nested [[h-card]]
* '''<code>u-url</code>''' - a URL to access the cited work
* '''<code>u-uid</code>''' - a URL/URI that uniquely/canonically identifies the cited work, canonical permalink.
* '''<code>p-publication</code>''' - for citing articles in publications with more than one author, or perhaps when the author has a specific publication vehicle for the cited work. Also works when the publication is known, but the authorship information is either unknown, ambiguous, unclear, or collaboratively complex enough to be unable to list explicit author(s), e.g. like with many wiki pages.
* '''<code>dt-accessed</code>''' - date the cited work was accessed for whatever reason it is being cited. Useful in case online work changes and it's possible to access the dt-accessed datetimestamped version in particular, e.g. via the Internet Archive.
* '''<code>p-content</code>''' for when the citation includes the content itself, like when citing short text notes (e.g. tweets).

== Status ==
'''h-cite''' is a microformats.org draft specification. Public discussion on h-cite takes place on [[h-cite-feedback]] and the #microformats [[irc]] channel linked in the [[#Status|Status section]].

== Property Details ==
(stub, to be expanded)

All web citation properties are derived from those implied in [[citation-formats#styles|existing citation styling guides]] for citing permalinks to articles and short text notes online.

Date-time properties (dt-published, dt-accessed) may optionally include time information in addition to the date if relevant to the citation (e.g. when citing short text notes (tweets) of which there may be several in a single day).

To be added:
* for each property, what equivalent TCMOS, APA, MLA terms/vocabulary is being expressed/captured as researched in the [[citation-formats#styles|citation formats styles]] section.
* transforms from the web citations proposal properties into each of those citation styles.
** for citations of blog posts / articles 
** for citations of text notes / tweets
** see examples in wild below for markup samples to style in each of the TCMOS/APA/MLA styles for blog/note citations.

== Offline Citations ==
The web citation proposal can be used for simple web-to-off-web citation use cases. As suggested by Ed Summers, dropping the hyperlink to the cited web article provides a simple off-web citation, e.g. a citation of a physical book:

<syntaxhighlight lang="html">
<span class="h-cite">
  <time class="dt-published">YYYY-MM-DD</time> 
  <span class="p-author h-card">AUTHOR</span>: 
  <cite class="p-name">TITLE</cite>
</span>
</syntaxhighlight>

Note: physical books typically only provide the YYYY (year) published, not the precise date.

Next steps: 
* Try such markup with actual content being published on the web (perhaps a bibliography, list of papers in a resume, etc.)
* See how it works/feels there
* Determine what seems to be missing. 
* See if the "p-publisher" property helps in some web-to-off-web citation use cases.

== Examples in the wild ==
Real world in the wild examples:
* ... add uses of h-cite you see in the wild here.

* <cite class="h-cite">[http://christopheducamp.com/blog/test-indieweb-parvenir-a-posser-un-article-vers-twitter/ Test #IndieWeb : Parvenir à « POSSEr » un article vers Twitter]</cite> ([http://web.archive.org/web/20130623202346/http://christopheducamp.com/blog/test-indieweb-parvenir-a-posser-un-article-vers-twitter/ archived]) has an h-cite of a short note:
<syntaxhighlight lang="html">
<blockquote><p>
  <cite class="h-cite">
    <a class="u-url p-name" href="http://tantek.com/2013/104/t2/urls-readable-speakable-listenable-retypable"> 
      URLs should be readable, speakable, listenable, and unambiguously 
retypable, e.g. from print: tantek.com/w/ShortURLPrintExample #UX 
    </a> 
   (<abbr class="p-author h-card" title="Tantek Çelik">Çelik</abbr> 
    <time class="dt-published">2013-04-14</time>)
  </cite>
</p></blockquote>
</syntaxhighlight>

* Mastodon uses h-cite by default to show threads and replies to posts [https://github.com/tootsuite/mastodon/pull/1063 added in 2017]

See also examples documented here:
* https://indieweb.org/h-cite#Indieweb_Examples

Real but not quite wild (used by the specification author)
* Every blog post on http://tantek.com has a text field for copying h-cite markup for that blog post.
* <cite class="h-cite">[http://tantek.com/2012/353/b1/why-html-classes-css-class-selectors Why you should say HTML classes, CSS class selectors, or CSS pseudo-classes, but not CSS classes]</cite> has a couple of interesting uses of h-cite:
** properties used: p-name, u-url, p-author, p-publication, dt-published, dt-accessed (basically all proposed properties except p-content!)
** additional experimental property: p-x-translation - which refers to a nested h-cite with its own implied p-name and implied u-url.

== Background ==
This work is based on how existing [[citation-formats#styles|citation format ''styles'']] (APA, MLA, TCMOS) represent references to articles on the web, and is designed to match the implied schema of those styles. The web citations proposal defines how to markup such reference representation styles in order to satisfy the use-cases above.

=== Goal ===
A primary goal of the web citation effort is to both start small, and always "make small possible", that is, no matter how it is extended, continue permitting very small meaningful citations with perhaps only 2-3 properties (e.g. date published, author, name of work).

=== Previous Proposals ===
The biggest problem with all previous proposals is that they tried to do too much. They didn't design a citation ''micro''format that could be used as a building block, but rather, erred on the side of attempting to describe the myriad types of references to dead-tree resources. They were so over-designed that their authors didn't even dogfood them on their own sites. -- [[User:Tantek|Tantek]] 00:56, 7 August 2012 (UTC)

== FAQ ==
=== Why ===
''Why markup web citations? What problem does it solve?''

A: In the simplest form, marking up a web citation URL, name, date published, author etc. allow for processing of web citations into whatever "style" or "format" (MLA vs APA etc.) a user wishes to publish them themselves.

=== Why not just a href ===
''Doesn't <code>&lt;a href&gt;</code> solve the problem of marking up citations in an article on the web that refers to other articles on the web?''

A: No, <code>&lt;a href&gt;</code> is necessary but insufficient for marking up <em>citations</em> to articles on the web. 

* '''Insufficient semantic.''' <code>&lt;a href&gt;</code> is sufficient only for providing a hyperlink (which may or may not be a citation, e.g. it may be a "see also" link rather than link to a source being cited for particular assertion or fact).
* '''A href only marks up article link and name''' An <code>&lt;a href&gt;</code> can only represent the "url" and "name" of a citation. Where as [[citation-formats#styles|published web citations]] typically also include:
** article author name (sometimes author photo and URL)
** article publication date
** article publication name
** article access date (sometimes, e.g. Wikipedia citations)

== Design Principles ==
Principles driving this proposal:
* '''solve a [[specific]] problem'''. In this case '''web citations''' seeks to solve a ''more'' specific problem than previous proposals, that of citations from the web to the web (more constrained than any publication to any publication).
* [[solve simpler problems first]]. Existing web-to-web citations contain very little information compared to generalized academic citations, thus '''web citations''' is greatly simplified compared to previous proposals by only starting with a handful of properties.
* [[humans first]] - '''web citations''' focuses on the human readability and writability aspects of citations in articles first and foremost, and only secondarily considers the machine readability/reusability of the data contained therein.
* [[reuse]] building blocks - by re-using the better designed aspects of [[citation-formats#styles|existing citation conventions]] for web resources, '''web citations''' builds on top of previous work to make citations human readable/writable, as well as what implied properties are commonly expressed by such previous work.
=== Focus ===
The <dfn>web citations</dfn> proposal uses a smaller, [[simpler]] set of only ''eight'' properties to solve the [[specific]] problem of how to markup citations in an article <em>on the web</em> that refers to other articles <em>on the web</em>. Offline to offline, and online to offline references were specifically not explicitly addressed in initial design.

== First Proposal ==
This design was first publicly proposed as the result of an interactive web citation design discussion during IndieWebCamp2012:
* <span class="h-cite"><time class="dt-published">2012-07-01</time> <span class="p-publisher">IndieWebCamp2012</span>: <cite class="p-name">[http://indiewebcamp.com/2012/Academic_Citations_Web Academic Citations for the Web]</cite></span>


[[Category:Draft Specifications]]