5 ms·

What is the advantage of this format over CSL-JSON [1] or BibTeX, which are already supported by software like pandoc? There is even a standard YAML citation f

What is the advantage of this format over CSL-JSON [1] or BibTeX, which are already supported by software like pandoc? There is even a standard YAML citation format [2] used within YAML metadata for Markdown files, so I wonder why GitHub couldn't have chosen one of the existing options, lobbying the spec maintainers if any changes were needed. [1] https://citeproc-js.readthedocs.io/en/latest/csl-json/markup.html https://citeproc-js.readthedocs.io/en/latest/csl-json/markup... [2] https://ymlthis.r-lib.org/reference/yml_reference.html https://ymlthis.r-lib.org/reference/yml_reference.html [3] https://pandoc.org/MANUAL.html#citations https://pandoc.org/MANUAL.html#citations

cratermoon 5y ago
> What is the advantage of this Right? There's also RIS, EndNote, and a others. Did we really need ANOTHER format?
- cormacrelf 5y ago
  TLDR: Think of it like Zotero having field names that change depending on the item type. If you select "Journal Article", the CSL `container-title` field is displayed as "Publication", whereas for a book chapter, it's "Book Title". The `software` type in CSL gets a similar treatment in Zotero, and CFF is like that but as a YAML schema for writing by hand. Additionally, you get to give reference data for the dependencies or datasets you built the present one from. The main page for CFF does not argue for its existence very effectively. You're better off reading the schema (https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md https://github.com/citation-file-format/citation-file-format...). Two takeaways: 1. It is is specifically for citing software and datasets. Only those two things. The fields look useful for its intended purpose: You can have multiple dois, for different versions of the software as published. You can include a few more different URLs than most formats, like zipped repo contents for a version or a dataset download link (repository-artifact) etc. If you use the preferred-citation field to point people to a paper instead, then you are warned it is against the principle of citing software and datasets as if they are papers themselves. 2. Unfortunately, though, because the schema only has enough fields for citing those two, if your software is (e.g.) an implementation of an algorithm described in a paper, you cannot express that in CFF. There is a `references` field, but in reality it can only contain other software and datasets because CFF can't describe anything else. It would be better if there were separate fields for CFF software/dataset references and other kinds of reference data, the latter incorporating CSL-JSON by reference. CSL-JSON isn't really written by hand except by a handful of people making CSL tests (me!); the point of such a field would be a space to dump an export from your reference library. So in sum, what is the advantage of this? - Anything but JSON. People hate writing it by hand. - Software-specific field names, whereas if you used CSL-JSON directly `date-released` would be `issued`... who issues software? - Separates the "main" citation and the "references", whereas other formats are a flat dump of a reference library. It's got structure enough to produce different bibtex/etc for different versions of the code, selectable at conversion time. (Disclosure: I work for Zotero.)
  - sdruskat 5y ago
    Hi, and thanks for supporting CFF through the Zotero connector (for GitHub repos) now :). FYI, we're in the process of improving the website atm, including a Rationale section, etc. which will hopefully make it clearer why we think the format is a good idea, at least for the time being. As for your takeaway 2.: `references` can take all kinds of references, not just software and references, including articles, so a paper describing the algorithm implemented in the software that the CFF file describes is exactly in scope for that (the paper being, e.g., a prior work).
    - cormacrelf 5y ago
      Ah, I missed the fields that would help you define that info on “definition.reference”. https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md#definitionsreference https://github.com/citation-file-format/citation-file-format... Clearly I’m not the person who built the connector if I missed that :)
grenoire 5y ago
BibTeX might not be perfect, but damn do I love being able to copy-paste pre-generated entries from practically all journals on Earth.
- sdruskat 5y ago
  Now including GitHub, that gives you BibTeX generated from CFF files :).
  - xucheng 5y ago
    Since many papers have existing bibtex, it would be better if GitHub either provides tools to convert bibtex to CFF or supports bibtex directly. FWIW, bibtex is the de facto standard.
    - sdruskat 5y ago
      Not for providing citation metadata for software, where BibTeX misses important fields.
      - xucheng 5y ago
        May I ask what missing fields you are referring to? Why @online/@software/@dataset type in biblatex [1] cannot do the job? That being said, I think GitHub should acknowledge that it is common for authors to want people cite their paper (or multiple papers) rather than simply the source code. Because this is what counts to the citation in academic. At the same time, there is no reason to not support bibtex/biblatex in addition to the cff. [1]: See section 2.1.1 in http://mirrors.ibiblio.org/CTAN/macros/latex/contrib/biblatex/doc/biblatex.pdf http://mirrors.ibiblio.org/CTAN/macros/latex/contrib/biblate...
        sdruskat 5y ago
        @software is simply an alias for the fallback @misc, i.e., semantics are lost, no fields like different URLs for different software media (code, build artifacts, etc.), no software identifier support, etc. Also, you can have people cite your paper on GitHub by giving them it as a preferred citation in CFF, and GitHub will render that instead of the source code. Which is, btw, against the software citation principles [1], but caters to people who need time adapting and want traditional credit now. [1]: https://doi.org/10.7717/peerj-cs.86 https://doi.org/10.7717/peerj-cs.86
colonelxc 5y ago
CSL doesn't appear to support software as a 'type' of thing, which it has a hardcoded list of options[0]. Of course, maybe they should have just fixed an existing format instead of creating a new one. [0] https://github.com/citation-style-language/schema/blob/master/schemas/input/csl-citation.json#L43 https://github.com/citation-style-language/schema/blob/maste...
riedel 5y ago
I don't think this is anything chosen by GitHub . Seems like a random format endorsed by some German and Dutch research orgs. Having said that it would be cool to have a standard format/best practice that would also be picked up e.g. by Google scholar ( guess bibtex is the best bet). Like a CITEME.bib file, which would be pretty self-explanatory.
- riedel 5y ago
  I found the post now: https://news.ycombinator.com/item?id=28253293 https://news.ycombinator.com/item?id=28253293 So it seems to official. Strange things happen...
sdruskat 5y ago
Hi, co-lead of the CFF project here. One advantage I see is semantics, and that it's single-purpose. Downstream clients (archives, indexers, GitHub citation feature, etc.) know exactly what they're dealing with (citation information for software or datasets). Also has better support for software-related fields than BibTeX for example (@software being an alias for @misc).

cratermoon 5y ago

> What is the advantage of this Right? There's also RIS, EndNote, and a others. Did we really need ANOTHER format?

cormacrelf 5y ago
TLDR: Think of it like Zotero having field names that change depending on the item type. If you select "Journal Article", the CSL `container-title` field is displayed as "Publication", whereas for a book chapter, it's "Book Title". The `software` type in CSL gets a similar treatment in Zotero, and CFF is like that but as a YAML schema for writing by hand. Additionally, you get to give reference data for the dependencies or datasets you built the present one from. The main page for CFF does not argue for its existence very effectively. You're better off reading the schema (https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md https://github.com/citation-file-format/citation-file-format...). Two takeaways: 1. It is is specifically for citing software and datasets. Only those two things. The fields look useful for its intended purpose: You can have multiple dois, for different versions of the software as published. You can include a few more different URLs than most formats, like zipped repo contents for a version or a dataset download link (repository-artifact) etc. If you use the preferred-citation field to point people to a paper instead, then you are warned it is against the principle of citing software and datasets as if they are papers themselves. 2. Unfortunately, though, because the schema only has enough fields for citing those two, if your software is (e.g.) an implementation of an algorithm described in a paper, you cannot express that in CFF. There is a `references` field, but in reality it can only contain other software and datasets because CFF can't describe anything else. It would be better if there were separate fields for CFF software/dataset references and other kinds of reference data, the latter incorporating CSL-JSON by reference. CSL-JSON isn't really written by hand except by a handful of people making CSL tests (me!); the point of such a field would be a space to dump an export from your reference library. So in sum, what is the advantage of this? - Anything but JSON. People hate writing it by hand. - Software-specific field names, whereas if you used CSL-JSON directly `date-released` would be `issued`... who issues software? - Separates the "main" citation and the "references", whereas other formats are a flat dump of a reference library. It's got structure enough to produce different bibtex/etc for different versions of the code, selectable at conversion time. (Disclosure: I work for Zotero.)
- sdruskat 5y ago
  Hi, and thanks for supporting CFF through the Zotero connector (for GitHub repos) now :). FYI, we're in the process of improving the website atm, including a Rationale section, etc. which will hopefully make it clearer why we think the format is a good idea, at least for the time being. As for your takeaway 2.: `references` can take all kinds of references, not just software and references, including articles, so a paper describing the algorithm implemented in the software that the CFF file describes is exactly in scope for that (the paper being, e.g., a prior work).
  - cormacrelf 5y ago
    Ah, I missed the fields that would help you define that info on “definition.reference”. https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md#definitionsreference https://github.com/citation-file-format/citation-file-format... Clearly I’m not the person who built the connector if I missed that :)

grenoire 5y ago

BibTeX might not be perfect, but damn do I love being able to copy-paste pre-generated entries from practically all journals on Earth.

sdruskat 5y ago
Now including GitHub, that gives you BibTeX generated from CFF files :).
- xucheng 5y ago
  Since many papers have existing bibtex, it would be better if GitHub either provides tools to convert bibtex to CFF or supports bibtex directly. FWIW, bibtex is the de facto standard.
  - sdruskat 5y ago
    Not for providing citation metadata for software, where BibTeX misses important fields.
    - xucheng 5y ago
      May I ask what missing fields you are referring to? Why @online/@software/@dataset type in biblatex [1] cannot do the job? That being said, I think GitHub should acknowledge that it is common for authors to want people cite their paper (or multiple papers) rather than simply the source code. Because this is what counts to the citation in academic. At the same time, there is no reason to not support bibtex/biblatex in addition to the cff. [1]: See section 2.1.1 in http://mirrors.ibiblio.org/CTAN/macros/latex/contrib/biblatex/doc/biblatex.pdf http://mirrors.ibiblio.org/CTAN/macros/latex/contrib/biblate...
      - sdruskat 5y ago
        @software is simply an alias for the fallback @misc, i.e., semantics are lost, no fields like different URLs for different software media (code, build artifacts, etc.), no software identifier support, etc. Also, you can have people cite your paper on GitHub by giving them it as a preferred citation in CFF, and GitHub will render that instead of the source code. Which is, btw, against the software citation principles [1], but caters to people who need time adapting and want traditional credit now. [1]: https://doi.org/10.7717/peerj-cs.86 https://doi.org/10.7717/peerj-cs.86

colonelxc 5y ago

CSL doesn't appear to support software as a 'type' of thing, which it has a hardcoded list of options[0]. Of course, maybe they should have just fixed an existing format instead of creating a new one. [0] https://github.com/citation-style-language/schema/blob/master/schemas/input/csl-citation.json#L43 https://github.com/citation-style-language/schema/blob/maste...

riedel 5y ago

I don't think this is anything chosen by GitHub . Seems like a random format endorsed by some German and Dutch research orgs. Having said that it would be cool to have a standard format/best practice that would also be picked up e.g. by Google scholar ( guess bibtex is the best bet). Like a CITEME.bib file, which would be pretty self-explanatory.

riedel 5y ago
I found the post now: https://news.ycombinator.com/item?id=28253293 https://news.ycombinator.com/item?id=28253293 So it seems to official. Strange things happen...

sdruskat 5y ago

Hi, co-lead of the CFF project here. One advantage I see is semantics, and that it's single-purpose. Downstream clients (archives, indexers, GitHub citation feature, etc.) know exactly what they're dealing with (citation information for software or datasets). Also has better support for software-related fields than BibTeX for example (@software being an alias for @misc).