Tomorrow's Citations
Preliminary Guide for Content Creators

J. WILLIAMS, Ph.D. | BIO | UPDATED date

This guide presents a broadly applicable citation architecture that promotes credibility assessment for online documents. Assessing credibility is essential because online documents are often posted without prepublication review. They violate traditional conventions of the ink-and-paper world and are subject to revision, replacement, and deletion.

Regarding architecture, providers of online content write citations and references in a convenient style dubbed the author view. Their writings are then transformed in real-time to a reader view that is convenient to read.

In the reader view, an in-text citation has the form of a hyperlinked dagger. Mousing over the dagger brings up the citation's corresponding reference.

The guidance presented here is a refnement of that developed in Tomorrow's Citations: Architecture Developmment and illustrated in Tomorrow's Citations: Reference Examples.

General Guidance  

This guide is silent on some topics that are variously covered in other style guides Consistent choices are requiered, but in some cases, particular choices are not required.

Dates. Some authors prefer the conventional "month dd, yyyy" format, while others may prefer the IEEE "yyyy-mm-dd" format. The only requirement is that all dates follow the same format.

Abbreviations. There are no required abbreviations. This convention differs from the ink-and-paper world, where there is a need to conserve paper. As an example, the JASIST might be better expressed as the Journal of the Association for Information Science and Technology.

Capitalization. Capitalizing the first letter of principal words in a title is a pleasant option consistent with AP guidance[ap-guide]. For example, John Berendt's Midnight in the Garden of Good and Evil[jim]. Sentence casing of titles in which only the first letter of the first word is capitalized is also acceptable and may be preferrable if mulrtiple styles are in use.

Ordering of citations and periods. When a citation comes at the end of a clause or sentence, use consistent punctuation. For example, always place the citation before the period or other end punctuation.

Terminology  

Contributors are people involved in the creation, presentation, and maintenance of content, including any research involved in creating content. Contributors are conveniently divided into content creators and secondary contributors. Authors are content creators who accept responsibility for content.

In this guide, the citing document is the work whose citations and references are under discussion. The citations (in-text citations) occur in the citing document's main text, and its references occur in its reference section (works cited section).

Each citation points to a reference that in turn points to cited content. The same content can have multiple representations. It can appear in several different places and in multiple formats. It can appear in multiple languages. It can appear both online and offline. Commonly, the cited content occurs on a web page that also contains uncited content.

This guide is mainly about the author view. Examples are typically given in this format, but with a button to press to see the transformed reader view.

Citations  

Citations can point to references in one of two ways.

A root citation identifies content that, within the context of the citing document, is not part of some larger cited body of work.

A subsidiary citation identifies content that is logically subsidiary to content that is identified by a root citation.

The organization of cited content into root content and subsidiary content is performed at the discretion of the content creators. The subsidiary content may be found in a section of the cited root document, another document, or a section of another document. The subsidiary document may have an unrelated URL.

In the author view, a root citation has the form \[root], where the root identifier is chosen at the convenience of the content creator. A subsidiary citation has the form \[root, part-name], where the part-name is a short name for the subsidiary content. To prevent a  bracketed passage from being treated as a citation, precede its left bracket with a backslash, like so: \\[ protected passage ].

In principle, content creators may use any convenient convention for specifying root identifiers. The provider-to-reader transformation buries root identifiers by replacing each citation with a hyperlinked dagger (†). However, there is an advantage in always using the same convention. The traditional convention for root identifiers is to use the form auth_date, giving the primary author's surname and the publication year, but this is not a requirement.

A citation documents an idea by pointing to a supporting cited work. A citation may also be used to acknowledge or credit an author. In this case, an annotated citation is needed because, in the reader style, the citations all look like daggers. Here is an example:

Reference Sections  

The citing document's reference section is a list of references. Each reference is a seven-sentence paragraph. References may be listed in any order because the provider-to-reader transformation sorts them.

The transformation algorithm sorts root references according to their citations' order of occurrence in the main text. Under each root reference, the algorithm gathers related subsidiary references and sorts them according to their titles. The sorting process has the effect of organizing the reference section into segments with each segment headed by a root reference. Numbered subsidiary titles are sorted properly, as in the following example:

9.8 Format of the Author Element

9.10 Identification of Specialized Roles

Reference Structure

The reference design extends the format used by search engines in that the first two core elements are the title and links to the referenced work. Very briefly, the elements of a root reference in the author view are,

• optional indicated favicon
• reference identifier
• title and related information
• links to referenced content
• contributors
• publishing entities
• date published or updated

Each reference element other than the favicon ends with sentence-ending punctuation followed by white space. If a period, question mark, or exclamation point followed by white space is necessary inside a particular reference element, escape it with a backslash. For example, "Yo\! Yes?" transforms to Chris Raschka's story, Yo! Yes?[yo-yes] in the reader view. This approach to punctuating references suggests avoiding unnecessary periods — for example, using J R R Tolkien instead of J. R. R. Tolkien.

Here are some citations and accompanying references — a root reference and two subsidiary references. Press the blue button to see how they are transformed and hyperlinked.

Reference Elements

Let us now consider each of the seven reference elements. After that, we will take up some additional considerations that apply to subsidiary references.

Favicon for Root Citations

By default, the algorithm gets the icon from the reference's first linked web page. This default can be overridden by explicitly specifying the icon, like this: icon image-path. The algorithm then uses the provided image path.

In the following examples, the top three icons were automatically scraped from well-known websites, and the bottom three were contributor-provided.

Reference Identifier

Reference identifiers are modeled directly after the citations. For example, the reference identifier for the citation \[George, cherry] is George, cherry. None of this shows in the reader view. The transformation changes the citation to a hyperlinked dagger and buries the reference identifier in the HTML source.

Title Element

Provide a preferred title, an optional alternative title, any needed title appendages, and optional title clarifications.

A reference can have more than one title. If the title is in a foreign language, there is both a foreign title and a translated title. For the sake of reader convenience, when there are two titles, the first title should be the one readers are more likely to appreciate. Typically, the second title is the document's original title. The second title is set off with parentheses.

A title appendage is anything needed to clarify which document the title refers to. For example, version, volume, issue, build, release, edition, supplement. The title appendage follows the title. It is set off by a comma or semicolon as appropriate.

A title clarification is set off with square brackets. Common clarifications include a "book review," "clinical trial," "consensus document," "exposition," "large-scale study," "literature review," and "news article." In the provider version of the reference, the title clarification is not preceded by a backslash because the reference section is not parsed for citations.

The provider-to-reader transformation italicizes the titles of root references by default. An author who wishes to override the default can do so by making explicit use of italics. The use of italics in titles is essentially a matter of taste.

The title element can turn up in various places. Typically, it is on a web page's face. Often, it is in the page's HTML source, in the <title> element. These titles may be different, in which case the one on the document face is probably more recognizable. In the rare case where a page has no title, make up a titular description and wrap it in parentheses. Alternatively, use the first few words of the referenced document and enclose them in quotes.

Title examples

Consider the following title elements given in the author's view:

Yo! Yes?  is a single illustrated story that has been presented in 21 editions. To see the 21 editions, follow the hyperlink.

The second and third titles show that the need for alternative titles isn't just due to language barriers. The Analects has been pre-italicized to keep the format transformation from italicizing the following Chinese title.

Here are three more examples:

These titles illustrate the following:

Link Element

How the citing document handles a reference to a cited document depends on whether the cited document is directly available to its intended audience, that is, has an advertised URL that the citing document's intended readers can access. eBooks, which are generally available online, need not be directly available — they need not have advertised URLs.

The link element provides a list of one or more links to representations of referenced content. The representations are of two kinds: presentations of directly available online content and portrayals of related information. An eBook that is not directly available may still have a linkable online presence. There may be portrayal links to an abstract or a review or there may be a link to an online vendor.

A link's clickable anchor is responsible for distinguishing between presentations and portrayals. Anchors for presentations include the terms "article," "blog post," "conversation, "email," "English translation," "full text, "online book," "image," and "PDFl." Anchors for portrayals include "abstract," "comment," "commentary," "errata," "related text," "review," "condensed," and "vendor." Put presentations before portrayals. Put more credible representations before less credible representations. 

Links for Directly Available Online Documents

A presentation link is a hyperlink that goes directly to an online presentation of available referenced content. Consider the Cherry Tree reference in Example 1. Its first link, image, goes to a digitized presentation of an engraving . In addition, this reference also has two portrayal links, namely explanation and history.

A presentation link to a linkable fragment in a containing online document uses a fragment URL. Consider the reference,

Classification \[of lung cancers]. Article section. WikiProject Medicine. Wikipedia. Updated 2021 September 28[lung-cancer]

The link's fragment URL is https://en.wikipedia.org/wiki/Lung_cancer#Classification.

For a subsidiary reference to a non-linkable portion of a directly available document, the link target is a containing portion that does have a link. Consider the reference,

"'What's to-day, my fine fellow?' said Scrooge". Page 110. ~. ~. ~[dickens, Christmas].

Page 110 contains the referenced subsidiary fragment; the page number is given relative to its containing root document.

Here is an example of a subsidiary reference from Example 1 that is not for a portion of the root document:

George, child. Childhood Stories of George Washington. PDF,  pages 3-6. Harriet G Reiter (storyteller), Katherine Follett (editor), Tad Butler (illustrator). Reading A-Z. 1906.

The subsidiary link, PDF, pages 3-6, includes a description of the root document, namely "PDF." Since the URL for the link points to the entire document rather than the specific portion being referenced, the page range is appended unlinked to the link's URL.

Links for Documents that are not Directly Available

The links for a document that is not directly available describe offline presentations and online portrayals such as an available vendor, synopsis, or review. Consider the following example,

Midnight in the Garden of Good and Evil. Kindle eBoo, vendor, book review, synopsis. John Berendt (bio). Random House. Published 1994 January 13[jim].

In this reference, vendor, book review, and synopsis are online portrayals. "Kindle eBook" is an optional offline link; think of it as a presentation link with a missing URL.

For a subsidiary reference to a portion of an unavailable document, the name of the portion is appended to the link anchor. Consider the following example:

9.4 Four Elements of a Reference.  APA article , page 283. ~. ~. ~[APA, elements].

The link, page 283, is offline. It points to the page containing the APA guide's Section 9.4. The  APA article is an online link to a portrayal of the content of Section 9.4.

Links for Non-linkable Portions of Documents

The page range is appended unlinked to the reference's link. The format is largely independent of whether the document is directly linkable.

Caraway \[in The Encyclopedia of Essential Oils]. Kindle eBook, pages 97-98. Julia Lawless. Red Wheel. 2013 June 1.

Title \[in Associated Press Style: Quick Reference Guide]. PDF, page 7. Unattributed. Colorado Department of Health and Environment. Undated.

Link Quality

Try to choose URLs that qualify as permalinks.

To get the permalink for a Facebook post, click on the post's date. The permalink will appear in the browser's address bar.

To get the permalink for a Twitter tweet, click on the tweet. To get the permalink for an Instagram picture or video, click on that.

Translate a DOI (Document Object Identifier) to a permalink by prefixing "https://oi.org/" to the DOI.

If a reference has no hyperlinks, use "Unlinked" for the link element. The provider-to-reader transformation sets such references in a gray color.

Contributor Element

List key contributors with authors and content creators listed first. A contributor's name may include honorific titles, for example, LCSW, RN, MD, PhD. A contributor can be an individual, a group, or an organization.

The number of contributors to list depends on the likely audience for the citing document. For example, if the potential audience consists mainly of authors of the referenced works, list as many contributors as possible. When not listing all contributors, end the contributor element with "and others." If no person or organization acknowledges responsibility for creating the work's content, use "unattributed" for the contributor element.

In the case of a group author, list the group's leaders, if available. The same goes for organizational authors.

Each contributor's name is optionally followed by a parenthesized list of credibility-related attributes such as the contributor's role, author bio, or organizational affiliation.

Give enough role information to distinguish content creators from other contributors. The default role is "author." An included biography, history, or about page can be given using a hyperlink. If a contributor is provided as a Twitter handle, link it to the associated Twitter account.

The recipient of a personal communication may be treated as a secondary contributor.

Here is a list of common contributor roles[cr, MLA]  [cr, casrai]  [cr, IOPScience]  [cr, ICMJE]  [cr, Childers]  [cr, patents]  [cr, schema-roles]  [cr, zotero].

Some contributors with associated credibility data:

Publishing Element

Give the organization or organizations involved in publishing activities such as review, acceptance, final editing, marketing, and distribution to an intended audience. Likely examples include traditional publishers or their independently operating imprints, newspapers, journals, and websites. In each case, the title of the publishing entity suffices. If a work was published before 1900, include the publisher's city. In many cases, the cited content is contemporary with the web page on which it appears, and the likely publisher is the page's website. A website's title is the title of its home page.

If there are several publishers, use the publishers of the first link in the link element or use 'multiple publishers' for the publishing element.

A web page's publisher will often appear at the top of the web page along with the publisher's logo. Alternatively, it may appear in the page source, often in the title element.

Some publishers:

Date Element

Say how and when the content was created or placed online. Regarding how, there are several possibilities:

Posted: Posted without significant publishing activities.

Published: Established as part of a publishing process.

Online: Published online

Updated: Modified and reposted.

Use of the choice "posted" implies that the publisher listed in the reference has not performed all of the normal publishing activities.

It is acceptable to use more than one of the above choices. For example, a document may have been posted online before being officially published. In the event that content has both online and offline publication dates, the earlier date is more appropriate. In  the event that the "how" information is omitted, the default is "published."

Several dates are typically not included in a reference because they are not properties of the cited content: a document review date, dates of comments on the cited content, the date on which a content creator last accessed the cited content, the date on which a website posted the content.

For non-document materials, the word "created" may be appropriate. If using a copyright date, the word "copyright" is appropriate. Copyright dates are inaccurate estimates of publication or posting dates.

Finding the date may require some detective work. The date may appear prominently on the face of a web page. However, the date may appear only in the page's HTML source code: Search for "date." Some HTML editors will automatically include, in the page's source, the date the page was saved. If no suitable date can be found, use "undated" or "no date" for the date element.

The date needs to be in a format that makes sense for an international audience. For example, 4/3/21 means April 3, 2021 in some countries and March 4, 2021 in others.

Some publication dates:

Subsidiary References

Subsidiary references are like root references but with a few key differences.

A subsidiary reference omits the favicon.

Subsidiary references may omit redundant information.

References may be subsidiary to a concept rather than another reference.

Redundant Information

Because subsidiary references are attached to a corresponding root reference by the provider-to-reader transformation, it may improve readability of the reference section to use tildes in place of information that appears already in the root reference, as in the following example.

In the reference section, root references provide needed context for subsidiary references. The mouseover notes in the main text also provide this context by including the favicon and title of the corresponding root reference in the note for the subsidiary reference.

Reference Segment Titles

The organization of references into segments is further supported by allowing reference segment titles. These consist simply of a root identifier and a title. Optionally, a segment title may be provided with a favicon in the same way as with references. Here is an example.

Provider-to-Reader Transformation  

As already mentioned, the transformation algorithm hyperlinks each citation to its corresponding reference and adds a mouseover note containing the reference.

The algorithm sorts the transformed root references into ascending order according to their order of appearance in the main text. The subsidiary references with a given root are collected under the root reference and sorted by title.

In the transformed reference section, titles of root references are italicized by default.

The last step in the transformation is to check that each reference has the correct number of elements and is the target of an in-text citation. Also, that each citation links to precisely one reference. Passing this last check ensures that the entire reference section can be proofread while mousing over the citation daggers to ensure they are correct.

Required Document Structure  

A typical document structure is depicted below. The References heading separates the main text from the reference section and also shows where these entities fit into the overall document structure. The actively processed portion is at the same level as the References heading, which may be tagged with any of the tags H1 through H6. There can be other headings and unprocessed material following the references.

  ...
  <div ...>
    ... main text ...
    <h*>References*</h*> ...
    ... references ...
    <h*>following heading</h*>...
    ...
  </div>
  ...

Copy the following material into the document's <head> section:

<script type='text/javascript'
    src="http://pagenotes.com/reference/scripts/citationsOnline.js"></script>
    <link rel="stylesheet" type="text/css" href="styles/providerToReader.css">

Implementation Notes  

Diagnostic Messages

The provider-to-reader transformation counts periods in a reference and reports a wrong count by appending one of these messages:

Reference has n missing element(s).
Reference has n too many element(s).

If a citation doesn't have an associated reference, the transformation algorithm adds an error reference in one of these forms:

Missing reference for \[root]
Missing reference for \[root, part-name]

If two or more references have the same reference ID, each reference is appended with the appropriate message:

\[root] cites duplicate references
\[root, part-name] cites duplicate references

If no citation cites a given reference, that is announced with

\[identifier] citation not found

Protected Passages in the Main Text

It is possible to prevent the provider-to-reader transformation from processing certain portions of the main text. A bracketed passage can be protected by escaping its left bracket, like so: \\[ protected passage ]. Larger portions can be protected by wrapping them in a div, like this:

<div class="skip-transform">
        ∙  ∙  ∙  ∙  ∙  ∙
</div> 

Known Bugs

If there is an extra <div> tag hiding in the HTML source of the main text, the provider-to-reader transformation will think that that is the start of the main text. The symptom is that citations before the <div> don't get processed.

If there is a period in a reference whose HTML source surreptitiously looks like this: <i>.</i> , the transformation will say that the reference has too few elements. Another example occurs when the period following a link is included in the link itself. The HTML source looks like .</a> when it should look like </a>. Yet another example occurs with escaped brackets. If the HTML source looks like this: \</em>\[<em> instead of this: </em>\\[<em>, the transformation tries to treat the bracketed passage as a citation.

If no citation cites a given reference, that is announced with an incorrect error message to the effect that the missing citation cites duplicate references.

Segment titles must have favicons. Otherwise, references are displayed in the wrong order.

HTML comments work correctly when applied to an entire paragraph but not if applied to a portion of a paragraph.

References  

cr, casrai. CRediT — Contributor Roles Taxonomy. Original article, NISO presentation, Cell Press PDF summary, Elsevier summary. Liz Allen (cochair), Alison McGonagle-O’Connell (cochair). casrai.org. Updated 2020 April 3.

icon icons/cherryTree.png.  George.  Cherry Tree Myth. Article. Jay Richardson, Charles Greco. mountvernon.org. updated October 4, 2023.

cr, schema-roles. Role: A Schema.org Type. Web page. Multiple corporate contributors. w3.org. Updated 2021 July 7.

cr, ICMJE. Defining the Role of Authors and Contributors. Recommendation. International Committee of Medical Journal Editors. icmje.org. Undated.

jim. Midnight in the Garden of Good and Evil. Kindle eBook; vendor, book review, synopsis. John Berendt (bio). Random House. Published 1994 January 13.

russo. Taming THC: potential cannabis synergy and phytocannabinoid-terpenoid entourage effects [literature review]. Article, PDF version. Ethan B Russo, MD (bio). British Journal of Pharmacology. Published 2011 August.

monkey. "I am who I am". Post. Post Planner. Facebook. Posted 2014 August 10.

cr, MLA. MLA Handbook 9th. Kindle eBook. The Modern Language Association of America. Self-published. Published 2021 April 22.

cr, patents. Patent Basics. Introduction. Unattributed. United States Patent Office. Undated.

cr, IOPScience. Author roles and responsibilities. Opinion. Unattributed. IOP Science. Undated.

cr, zotero. [Zotero] Item Creators. List. Unattributed. Corporation for Digital Scholarship. Undated.

cr, Childers. Different Roles in Comic Books. Resource. Matthew Childers (author, illustrator, writer, bio). matthewchilders.com. Updated 2020 November 4.

yo-yes. Yo\! Yes?, multiple editions. Boardbook, hardcover, review. Chris Raschka (author, illustrator, bio). Multiple publishers. Published 1993 March 1 through 2020 April 21.

ap-guide. Title [in Associated Press Style: Quick Reference Guide]. PDF file page 7. Unattributed. Colorado Department of Health and Environment. Undated.

icon icons/dickens.png. dickens. A Christmas Carol. Online book. Charles Dickens (bio), Arthur C Michael (illustrator). Hodder and Stoughton, Library of Congress. Published 1911, posted 2019 December 23.

dickens, Christmas. "'What's to-day, my fine fellow?' said Scrooge ...". Page 110. ~. ~. ~.

macbeth. Macbeth (The Tragedy of Macbeth). Playscript. William Shakespeare (bio), Kenneth Muir (editor). Globe Theatre, London, Arden Shakespeare. Performed 1606, second Arden series published 1997 January 31.

lung-cancer. Classification [of lung cancers]. Article section.. WikiProject Medicine (supervising project). Wikipedia. Updated 2021 September 28.

badlands. Badlands [review of the film Badlands by Terrence Malick]. Article. Peter Bradshaw (@PeterBradshaw1). The Guardian. Published 2008 August 28.

secret. The Analects [of Confucius] (论语). Chinese and English text.  Disciples of Confucius, James Legge (translator). Chinese Text Project. Written 475–221 BC, translated 1861.

APA. APA Style Guide (Publication Manual of the American Psychological Association, 7th edition). eBook, vendors. American Psychological Association (about). Self-published. Published 2019 October 1, copyright 2020.

APA, elements. 9.4 Four Elements of a Reference. Page 283; APA article. ~. ~. ~.

NLM. NLM Style Guide (Citing Medicine: the NLM style guide for authors, editors, and publishers), 2nd edition. Online book. Karen Patrias, Dan Wendling (technical editor). National Library of Medicine (US). Published 2007, updated 2020 August 5.

NLM, box-67. Multiple Book URLs (Box 67 Multiple URLs). Chapter 22 breakout. ~. ~. ~.

icon icons/contributor-roles.png. cr. Contributor Roles.

icon icons/globeIcon.png. season. After the Season [in The Poem Tree anthology]. Poem. Kate Light (bio). poemtree.com. Copyright 1997.