h-cite

From Microformats Wiki
Revision as of 21:14, 26 July 2023 by GRegorLove (talk | contribs) (s/<source>/<syntaxhighlight>/)
Jump to navigation Jump to search

h-cite is a simple, open format for publishing citations and references to online and other publications. h-cite is one of several open microformat draft standards suitable for embedding data in HTML/HTML5.

Status
This is a Draft Specification
Participate
IRC: #microformats on Libera
Editor
Tantek Çelik (Editor)
License
Per CC0, to the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work. In addition, as of 2024-12-03, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0.

Example

Here is a simple minimal abstract web citation example: 

<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>

Get started

The class h-cite is a root class name that indicates the presence of an h-cite.

The classes dt-published, p-author, p-name, and u-url define properties of the h-cite.

The class h-card on the same <span> as p-author indicates the presence of a nested h-card microformat as the author of the h-cite.

Properties

h-cite properties (inside class h-cite)

  • p-name - name of the work
  • dt-published - date (and optionally time) of publication
  • p-author - author of publication, with optional nested h-card
  • u-url - a URL to access the cited work
  • u-uid - a URL/URI that uniquely/canonically identifies the cited work, canonical permalink.
  • p-publication - 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.
  • dt-accessed - 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.
  • p-content 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 on irc.freenode.net.

Property Details

(stub, to be expanded)

All web citation properties are derived from those implied in 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 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: 

<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>

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.
<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>
  • Mastodon uses h-cite by default to show threads and replies to posts added in 2017

See also examples documented here:

Real but not quite wild (used by the specification author)

Background

This work is based on how existing 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 microformat 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. -- 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 <a href> solve the problem of marking up citations in an article on the web that refers to other articles on the web?

A: No, <a href> is necessary but insufficient for marking up citations to articles on the web.

  • Insufficient semantic. <a href> 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 <a href> can only represent the "url" and "name" of a citation. Where as 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 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 web citations proposal uses a smaller, simpler set of only eight properties to solve the specific problem of how to markup citations in an article on the web that refers to other articles on the web. 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:

Retrieved from "http://microformats.org/wiki/index.php?title=h-cite&oldid=70637"