Creating a Manubot CSL that perfects the format of bibliographic entries

[dhimmel]

Currently, Manubot uses style.csl a slightly modified version of proceedings-of-the-royal-society-b.csl. While this style is decent, I have some ideas for an optimal style. And of course, authors can always switch the style to that of whatever journal they'd like.

The style I envision uses numbers for citations, i.e. renders likeblah blah [1-5,7].. Non bracketed citations could show author name like: Pippi, Hippi, et al [7] wrote.

Bibliographic entries would look something like:

1. Sci-Hub provides access to nearly all scholarly literature
   _{^{Daniel S Himmelstein​, Ariel R Romero, Stephen R McLaughlin, Bastian Greshake Tzovaras, Casey S Greene}}
   PeerJ Preprints (2017-07-20) _{^{DOI: 10.7287/peerj.preprints.3100v1}}

Ideally, author names would be in smaller text and hyperlink to ORCID records when available. The smallness of text here is an exaggeration (limited formatting options).

Compared to historical bibliographic formats, the following points are stressed:

1. Unique identification is the most important aspect of a reference. A hyperlink or DOI is the single most important piece of information.
2. The title is the most salient human-readable piece of information
3. Just having a year for the date is too imprecise. The month and day are important for placing works in the proper historical context.
4. Authorship information is important, but often takes up too much of a reference. Having authorship information in smaller or lighter text would be nice.
5. Unless a reference is only available in a physical format, the volume / issue / page information is irrelevant.
6. Historical reference styles adopt vastly different styles based on the type of record (article, interview, etcetera). This is largely unnecessary. If anything, a badge can display the type of record.

There's a webapp to generate a custom CSL style. I've found it a bit difficult to use, but its probably the way to go.

One question is whether to print out the URL rather than hyperlink the title. The benefit of showing the URL would be for readers who have printed the PDF. However, if a reader is at a computer, they could always go back to the digital version with the hyperlink.

Suggestions welcome.

[agitter]

I like the idea of a custom CSL style. We should emphasize what we think is important and not be beholden to tradition.

I generally agree with your points above. Alternative viewpoints on the following:

Just having a year for the date is too imprecise.

True, but we can't always reliably get more precise information. Metadata for some older manuscripts includes placeholder days and months in some cases (e.g. January 1 of the year). For some URLs, I doubt our ability to automatically retrieve accurate date stamps.

Authorship information is important, but often takes up too much of a reference.

This may be reader-dependent. I personally remember more past literature based on authors and dates than titles. Author X 2011 may mean something to me even though This is the title of my important paper does not.

I don't see a need to print the URL. As a reader, I find it easier to search for the title than to type in a URL in most cases.

[agitter]

I noticed in the meta review manuscript that some of the reference whitespace was missing when CSL fields were absent. See references 19 and 21 for examples in this version of the pdf.

Is that controlled by or fixable in the CSL file? It may only affect references that do not have a date.

Edit: It may be the lack of authors that is the problem, not the lack of date.

[dhimmel]

Is that controlled by or fixable in the CSL file? It may only affect references that do not have a date.

Yeah this bugged me too when I was created the revised CSL. I played around a bunch and couldn't find a solution that would always perform appropriate newlines. I can look into a solution. We may have to print "No date", "Date missing", or "In press" as a workaround. Is that acceptable?

In general, when there's no date or other missing metadata, it's because the CSL is incomplete. So generally you should manually override this metadata. But yes, I agree that even with incompete metadata we should provide an aesthetic display.

[agitter]

"In press" seems journal-specific, and not a good match for some of the resources we may link to. "No date" sounds better to me. Or can we use " " as the default?

Coming up with a placeholder for missing authors is even harder. It's not that content has "No authors", but rather that we don't know the specific author(s) to attribute sometimes.

[agitter]

In the future, we may update the CSL to list book editors when there are no book authors. See greenelab/meta-review#74

[agitter]

Another CSL suggestion from #132 (comment) is to add a default value when there is no author:

See meta-review for an example reference without an author. The title and venue are concatenated without whitespace.

The possible solution in #132 (comment) requires further testing.

[dhimmel]

I think we did a good first pass at making an optimal CSL style for modern scholarly publishing. So will close this issue.

There are still some spacing issues which were exposed by looking at all metadata combinations in manubot/manubot#110.