New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Creating a Manubot CSL that perfects the format of bibliographic entries #53

Open
dhimmel opened this Issue Aug 12, 2017 · 6 comments

Comments

Projects
None yet
2 participants
@dhimmel
Member

dhimmel commented Aug 12, 2017

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

This comment has been minimized.

Collaborator

agitter commented Aug 12, 2017

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.

dhimmel added a commit to dhimmel/manubot-rootstock that referenced this issue Sep 4, 2017

Customize Manubot citation style
Simplify the CSL specification as per
greenelab#53

dhimmel added a commit to dhimmel/rephetio-manuscript that referenced this issue Sep 4, 2017

CSL: customize citation style
Simplifies CSL as well as fixes an issue where Thinklab, Zenodo,
and Figshare records do not have container-title set. Now, the
style falls back on publisher when container-title is not
available. This should make the bibliography less confusing.

Refs greenelab/manubot-rootstock#68
Refs greenelab/manubot-rootstock#53

dhimmel added a commit to dhimmel/rephetio-manuscript that referenced this issue Sep 4, 2017

CSL: customize citation style
This build is based on
6e5bd32.

This commit was created by the following Travis CI build and job:
https://travis-ci.org/dhimmel/rephetio-manuscript/builds/271857498
https://travis-ci.org/dhimmel/rephetio-manuscript/jobs/271857499

[ci skip]

The full commit message that triggered this build is copied below:

CSL: customize citation style

Simplifies CSL as well as fixes an issue where Thinklab, Zenodo,
and Figshare records do not have container-title set. Now, the
style falls back on publisher when container-title is not
available. This should make the bibliography less confusing.

Refs greenelab/manubot-rootstock#68
Refs greenelab/manubot-rootstock#53

dhimmel added a commit to dhimmel/rephetio-manuscript that referenced this issue Sep 4, 2017

CSL: customize citation style
This build is based on
6e5bd32.

This commit was created by the following Travis CI build and job:
https://travis-ci.org/dhimmel/rephetio-manuscript/builds/271857498
https://travis-ci.org/dhimmel/rephetio-manuscript/jobs/271857499

[ci skip]

The full commit message that triggered this build is copied below:

CSL: customize citation style

Simplifies CSL as well as fixes an issue where Thinklab, Zenodo,
and Figshare records do not have container-title set. Now, the
style falls back on publisher when container-title is not
available. This should make the bibliography less confusing.

Refs greenelab/manubot-rootstock#68
Refs greenelab/manubot-rootstock#53

dhimmel added a commit that referenced this issue Sep 6, 2017

Customize Manubot citation style (#68)
Simplify the CSL specification as per
#53

dhimmel added a commit that referenced this issue Sep 6, 2017

Customize Manubot citation style (#68)
This build is based on
b5644db.

This commit was created by the following Travis CI build and job:
https://travis-ci.org/greenelab/manubot-rootstock/builds/272297708
https://travis-ci.org/greenelab/manubot-rootstock/jobs/272297709

[ci skip]

The full commit message that triggered this build is copied below:

Customize Manubot citation style (#68)

Simplify the CSL specification as per
#53

dhimmel added a commit that referenced this issue Sep 6, 2017

Customize Manubot citation style (#68)
This build is based on
b5644db.

This commit was created by the following Travis CI build and job:
https://travis-ci.org/greenelab/manubot-rootstock/builds/272297708
https://travis-ci.org/greenelab/manubot-rootstock/jobs/272297709

[ci skip]

The full commit message that triggered this build is copied below:

Customize Manubot citation style (#68)

Simplify the CSL specification as per
#53
@agitter

This comment has been minimized.

Collaborator

agitter commented Oct 18, 2017

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

This comment has been minimized.

Member

dhimmel commented Oct 19, 2017

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

This comment has been minimized.

Collaborator

agitter commented Oct 19, 2017

"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

This comment has been minimized.

Collaborator

agitter commented Jul 13, 2018

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

@agitter

This comment has been minimized.

Collaborator

agitter commented Aug 31, 2018

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment