Skip to content
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

Suggested CSL Style changes by Sebastian Karcher #219

Merged
merged 3 commits into from May 14, 2019

Conversation

Projects
None yet
4 participants
@dhimmel
Copy link
Member

commented May 6, 2019

This PR is based on the commit dhimmel@12b4783, which was suggested to me by @adam3smith at the FORCE 2019 conference. The original commit message is:

Suggested by Sebastian Karcher to Daniel Himmelstein at the FORCE2018 Conference. Not yet tested. The changes focus on dealing with the missing space when authors are missing and showing editors.

I think it is possible these changes will resolve #218. However, I want to test them some and read more of the CSL doc to understand what they do.

Suggested CSL Style changes by Sebastian Karcher
Suggested by Sebastian Karcher to Daniel Himmelstein at the
FORCE2018 Conference. Not yet tested.

The changes focus on dealing with the missing space when authors
are missing and showing editors.
@dhimmel

This comment has been minimized.

Copy link
Member Author

commented May 6, 2019

greenelab/meta-review#216 applied the <substitute> portion of this PR but not the <label> part. The resulting diff of the HTML outputs is available at greenelab/meta-review@8be2fc7. It seems that the <substitute> portion alone was sufficient to correct both the missing newline and to use editor names when no authors are available.

So not quite sure was label does here.

@dhimmel

This comment has been minimized.

Copy link
Member Author

commented May 6, 2019

Below I test that 4e966da fixes the missing newline between title and venue reported in #218.

The reason why this change works is explained by

If cs:substitute contains multiple child elements, the first element to return a non-empty result is used for substitution. Substituted variables are suppressed in the rest of the output to prevent duplication. An example, where an empty “author” name variable is substituted by the “editor” name variable, or, when no editors exist, by the “title” macro:

Basically, the "venue" macros is being substituted for the "author" macros. This suppresses the subsequent insertion of the "venue" macros that was not properly surrounded by spaces.

New behavior

Command:

manubot cite --render \
  --csl=https://github.com/manubot/rootstock/raw/4e966dac46ea008c2944db6943b31973daec27a8/build/assets/style.csl \
  url:https://github.com/manubot/rootstock/pull/219

Ouput:

1. Suggested CSL Style changes by Sebastian Karcher by dhimmel · Pull Request #219 · manubot/rootstock
GitHub
https://github.com/manubot/rootstock/pull/219

Old behavior

Command:

manubot cite --render \
  url:https://github.com/manubot/rootstock/pull/219

Output:

1. Suggested CSL Style changes by Sebastian Karcher by dhimmel · Pull Request #219 · manubot/rootstockGitHub https://github.com/manubot/rootstock/pull/219
@dhimmel

This comment has been minimized.

Copy link
Member Author

commented May 6, 2019

Effect of 4e966da on editors:

manubot cite --render \
  --csl=https://github.com/manubot/rootstock/raw/4e966dac46ea008c2944db6943b31973daec27a8/build/assets/style.csl \
  doi:10.1007/978-3-319-00026-8
1. Opening Science
Sönke Bartling, Sascha Friesike, eds.
Springer International Publishing (2014) https://doi.org/gdqbzz
DOI: 10.1007/978-3-319-00026-8

Previously, the authors line was omitted. The CSL label element documented here:

The optional cs:label element (see label) must be included after the cs:name and cs:et-al elements, but before the cs:substitute element. When used as a child element of cs:names, cs:label does not carry the variable attribute; it uses the variable(s) set on the parent cs:names element instead. A second difference is that the form attribute may also be set to “verb” or “verb-short”, so that the allowed values are:

  • “long” - (default), e.g. “editor” and “editors” for the “editor” term
  • “short” - e.g. “ed.” and “eds.” for the term “editor”
  • “verb” - e.g. “edited by” for the term “editor”
  • “verb-short” - e.g. “ed.” for the term “editor”
  • “symbol” - e.g. “§” and “§§” for the term “section”
@dhimmel

This comment has been minimized.

Copy link
Member Author

commented May 6, 2019

With 79f2d75. , eds. is no longer appended to the editors. See

manubot cite --render \
  --csl=https://github.com/manubot/rootstock/raw/79f2d75a345b5b032bb3892465a7fe631963ffa2/build/assets/style.csl \
  doi:10.1007/978-3-319-00026-8
1. Opening Science
Sönke Bartling, Sascha Friesike
Springer International Publishing (2014) https://doi.org/gdqbzz
DOI: 10.1007/978-3-319-00026-8

I think this is my preference, since our style is never really clear about what type of author a name is. In addition, we only show editors when the metadata has no authors, so in essence we're treating editors as authors.

Another two options would be "Edited by Sönke Bartling, Sascha Friesike" or "Sönke Bartling, Sascha Friesike (editors)". @agitter and @slochower do you have a preference between the three options.

@slochower

This comment has been minimized.

Copy link
Collaborator

commented May 6, 2019

Another two options would be "Edited by Sönke Bartling, Sascha Friesike" or "Sönke Bartling, Sascha Friesike (editors)".

I think I prefer the second version, with (editors) appended. This can be important, I think, when citing book chapters which have both chapter authors and book editors.

@agitter

This comment has been minimized.

Copy link
Member

commented May 7, 2019

I think I prefer the second version, with (editors) appended.

Same here

Update label to parenthetical long form
To make author line like:
Sönke Bartling, Sascha Friesike (editors)

@dhimmel dhimmel force-pushed the dhimmel:csl-style-force-2 branch from 5bd4b04 to a7e831a May 7, 2019

@dhimmel

This comment has been minimized.

Copy link
Member Author

commented May 7, 2019

As of a7e831a

manubot cite --render \
  --csl=https://github.com/manubot/rootstock/raw/a7e831afdbe4a0b5b4115ca66249ef70503cc429/build/assets/style.csl \
  doi:10.1007/978-3-319-00026-8
1. Opening Science
Sönke Bartling, Sascha Friesike (editors)
Springer International Publishing (2014) https://doi.org/gdqbzz
DOI: 10.1007/978-3-319-00026-8

@slochower / @agitter does this PR look good to you now?

@dhimmel

This comment has been minimized.

Copy link
Member Author

commented May 7, 2019

Draft commit message:

CSL author macro: substitute editor/venue

Merges https://github.com/manubot/rootstock/pull/219

Ensures there is a newline between the title and venue,
when authors are missing.
Closes https://github.com/manubot/rootstock/issues/218

Substitutes editors for authors when authors are missing.
Editors are labeled like "Sönke Bartling, Sascha Friesike (editors)".
@agitter
Copy link
Member

left a comment

These changes look good to me. Does this make #158 obsolete?

@dhimmel

This comment has been minimized.

Copy link
Member Author

commented May 14, 2019

Does this make #158 obsolete?

Yes, at least for the instances of missing newlines that we're currently aware of. In case any type of missing newline or space occurs in the future, we can look into #158 compared to the <substitute> approach used here.

@dhimmel dhimmel merged commit 5da1d32 into manubot:master May 14, 2019

1 check passed

Travis CI - Pull Request Build Passed
Details

@dhimmel dhimmel deleted the dhimmel:csl-style-force-2 branch May 14, 2019

dhimmel added a commit that referenced this pull request May 14, 2019

CSL author macro: substitute editor/venue
This build is based on
5da1d32.

This commit was created by the following Travis CI build and job:
https://travis-ci.com/manubot/rootstock/builds/111763307
https://travis-ci.com/manubot/rootstock/jobs/200071500

[ci skip]

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

CSL author macro: substitute editor/venue

Merges #219

Ensures there is a newline between the title and venue,
when authors are missing.
Closes #218
Supersedes #158

Substitutes editors for authors when authors are missing.
Editors are labeled like "Sönke Bartling, Sascha Friesike (editors)".

dhimmel added a commit that referenced this pull request May 14, 2019

CSL author macro: substitute editor/venue
This build is based on
5da1d32.

This commit was created by the following Travis CI build and job:
https://travis-ci.com/manubot/rootstock/builds/111763307
https://travis-ci.com/manubot/rootstock/jobs/200071500

[ci skip]

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

CSL author macro: substitute editor/venue

Merges #219

Ensures there is a newline between the title and venue,
when authors are missing.
Closes #218
Supersedes #158

Substitutes editors for authors when authors are missing.
Editors are labeled like "Sönke Bartling, Sascha Friesike (editors)".

slochower added a commit to slochower/smirnoff-host-guest-manuscript that referenced this pull request May 15, 2019

Rootstock 2019 05 15 (#36)
* webpage.py: note to ignore error in versions checkout

Merges manubot/rootstock#211
Closes manubot/rootstock#183

* Use Athena to build PDF, if Docker installed

Merges manubot/rootstock#210
Closes manubot/rootstock#170

More information about Athena is available at
https://github.com/arachnys/athenapdf

Based on meta-review commit:
greenelab/meta-review@cffcfea

* Add meta review link to readme

Merges manubot/rootstock#217
Closes manubot/rootstock#216

* Increase shared memory of athenapdf container

Merges manubot/rootstock#220
Closes arachnys/athenapdf#195

Increase --shm-size from the default value of 64m to 1g when
running the athenapdf Docker image. Resolves athena issue:
`The renderer process has crashed`

Switch to using equal sign to separate Docker arguments
and values for consistency.
https://stackoverflow.com/q/50319060/4651668

* CSL author macro: substitute editor/venue

Merges manubot/rootstock#219

Ensures there is a newline between the title and venue,
when authors are missing.
Closes manubot/rootstock#218
Supersedes manubot/rootstock#158

Substitutes editors for authors when authors are missing.
Editors are labeled like "Sönke Bartling, Sascha Friesike (editors)".

slochower added a commit to slochower/smirnoff-host-guest-manuscript that referenced this pull request May 15, 2019

Rootstock 2019 05 15 (#36)
This build is based on
d62afc4.

This commit was created by the following Travis CI build and job:
https://travis-ci.com/slochower/smirnoff-host-guest-manuscript/builds/532938787
https://travis-ci.com/slochower/smirnoff-host-guest-manuscript/jobs/532938788

[ci skip]

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

Rootstock 2019 05 15 (#36)

* webpage.py: note to ignore error in versions checkout

Merges manubot/rootstock#211
Closes manubot/rootstock#183

* Use Athena to build PDF, if Docker installed

Merges manubot/rootstock#210
Closes manubot/rootstock#170

More information about Athena is available at
https://github.com/arachnys/athenapdf

Based on meta-review commit:
greenelab/meta-review@cffcfea

* Add meta review link to readme

Merges manubot/rootstock#217
Closes manubot/rootstock#216

* Increase shared memory of athenapdf container

Merges manubot/rootstock#220
Closes arachnys/athenapdf#195

Increase --shm-size from the default value of 64m to 1g when
running the athenapdf Docker image. Resolves athena issue:
`The renderer process has crashed`

Switch to using equal sign to separate Docker arguments
and values for consistency.
https://stackoverflow.com/q/50319060/4651668

* CSL author macro: substitute editor/venue

Merges manubot/rootstock#219

Ensures there is a newline between the title and venue,
when authors are missing.
Closes manubot/rootstock#218
Supersedes manubot/rootstock#158

Substitutes editors for authors when authors are missing.
Editors are labeled like "Sönke Bartling, Sascha Friesike (editors)".

slochower added a commit to slochower/smirnoff-host-guest-manuscript that referenced this pull request May 15, 2019

Rootstock 2019 05 15 (#36)
This build is based on
d62afc4.

This commit was created by the following Travis CI build and job:
https://travis-ci.com/slochower/smirnoff-host-guest-manuscript/builds/532938787
https://travis-ci.com/slochower/smirnoff-host-guest-manuscript/jobs/532938788

[ci skip]

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

Rootstock 2019 05 15 (#36)

* webpage.py: note to ignore error in versions checkout

Merges manubot/rootstock#211
Closes manubot/rootstock#183

* Use Athena to build PDF, if Docker installed

Merges manubot/rootstock#210
Closes manubot/rootstock#170

More information about Athena is available at
https://github.com/arachnys/athenapdf

Based on meta-review commit:
greenelab/meta-review@cffcfea

* Add meta review link to readme

Merges manubot/rootstock#217
Closes manubot/rootstock#216

* Increase shared memory of athenapdf container

Merges manubot/rootstock#220
Closes arachnys/athenapdf#195

Increase --shm-size from the default value of 64m to 1g when
running the athenapdf Docker image. Resolves athena issue:
`The renderer process has crashed`

Switch to using equal sign to separate Docker arguments
and values for consistency.
https://stackoverflow.com/q/50319060/4651668

* CSL author macro: substitute editor/venue

Merges manubot/rootstock#219

Ensures there is a newline between the title and venue,
when authors are missing.
Closes manubot/rootstock#218
Supersedes manubot/rootstock#158

Substitutes editors for authors when authors are missing.
Editors are labeled like "Sönke Bartling, Sascha Friesike (editors)".
@slochower

This comment has been minimized.

Copy link
Collaborator

commented May 18, 2019

To get around manubot/manubot#109 (and possible failures of caching), I added a manual reference formatted like so:

[
  {
    "type": "webpage",
    "standard_citation": "url:http://www.ambermd.org",
    "URL": "http://www.ambermd.org",
    "title": "The Amber Molecular Dynamics Package",
    "issued": {
      "date-parts": [
        [
          2019
        ]
      ]
    }
  },

The citation is rendered as:
image

I didn't know what to put in the author field, so I decided to leave it blank and omit it. (To be more correct, I could have listed the actual authors of the software package, but I didn't.) We should probably have a space between the title and the date. I think all fields should default to a space delimiter. What do you think?

@dhimmel

This comment has been minimized.

Copy link
Member Author

commented May 18, 2019

@slochower I think the issue is that both the authors and venue are missing. Let me look into this. I think the intended behavior here is:

  1. Title
    (2019) URL
@slochower

This comment has been minimized.

Copy link
Collaborator

commented May 18, 2019

@dhimmel

This comment has been minimized.

Copy link
Member Author

commented May 21, 2019

Is there a suggested venue for websites?

If there is an organization behind the website, I would usually set that as the publisher. Or sometimes as the author.

To make sure these formatting issues don't keep slipping through the cracks, in manubot/manubot#110 I'm generating all possible combinations of CSL JSON fields, so we can more exhaustively examine the behavior of our CSL style.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.