Support import/export of Bib(La)TeX software entries

[rdicosmo]

Support for software in bibliographies is finally available, and it would be great if Zotero could import software Bib(La)TeX entries.

The biblatex-software style with the full specification of the software specific entries is available at https://www.ctan.org/tex-archive/macros/latex/contrib/biblatex-contrib/biblatex-software

biblatex-software introduces four specific bibliographic entries for describing respectively software, software versions, software modules and code fragments.

Full documentation and examples are included in the package, see in particular

• the style documentation http://mirrors.ctan.org/macros/latex/contrib/biblatex-contrib/biblatex-software/software-biblatex.pdf
• an example document using this style http://mirrors.ctan.org/macros/latex/contrib/biblatex-contrib/biblatex-software/sample-use-sty.pdf
• an example BibTeX file showcasing the four entries http://mirrors.ctan.org/macros/latex/contrib/biblatex-contrib/biblatex-software/biblio.bib

[label-gun[bot]]

It looks like you did not upload an debug report. The debug report is important; it gives @retorquere your current BBT settings and a copy of the problematic reference as a test case so he can best replicate your problem. Without it, @retorquere is effectively blind. Debug reports are useful for both bug analysis and enhancement requests; in the case of export enhancements, I need the copy of the references you have in mind.

1. If your issue relates to how BBT behaves around a specific reference(s), such as citekey generation or export, select at least one of the problematic reference(s), right-click it, and submit an BBT debug report from that popup menu. If the problem is with export, please do include a sample of what you see exported, and what you expected to see exported for these references.

2. If the issue does not relate to references and is of a more general nature, generate an debug report by restarting Zotero with debugging enabled (Help -> Debug Output Logging -> Restart with logging enabled), reproducing your problem, and selecting "Send Better BibTeX debug report..." from the help menu.

Once done, you will see a debug ID in red. Please post that debug id in the issue here.

Thank you!

[retorquere]

I'd be happy to work on that but I'll need the debug log as described by point 1.

[retorquere]

@rdicosmo I still need your help here. I need sample items from Zotero that you think should be transformed to such entries.

Can I expect these packages to be widely installed? Does overleaf have them for example? Should this sit behind a preference like the extended name format?

@njbart, any ideas on these?

[rdicosmo]

Yes, this is on my TODO list, will get there soon :-) This is a very recent package, but we can expect quick uptake in the community, as it fills a need that has been there for decades.

[retorquere]

If you can get me Zotero items in a debug log for all four variants you'd like to see exported (or as many of those four as you think makes sense), I'll see how far I can get.

[retorquere]

For biblatex export I use the BCF file from https://sourceforge.net/projects/biblatex-biber/files/biblatex-biber/testfiles to put together the quality report. Would you be able to get (or make) a BCF file that includes the rules about @software entries?

[retorquere]

Strange BTW -- the sample entries use year and month instead of date -- those are legacy fields for biblatex.

[rdicosmo]

Strange BTW -- the sample entries use year and month instead of date -- those are legacy fields for biblatex.

BibLaTeX supports year and month on top of date for compatibility with BibTex, and so does the biblatex-software package; the sample entries use these legacy fields as they are more familiar to long time users of BibTeX, but entries with just date will work perfectly well. For export from Zotero, you can ignore the legacy entries and use just the date field.

[retorquere]

I mean yeah, I know, but it seems strange to introduce something new that will only work with biblatex, and to present that in a legacy format to accommodate bibtex.

[rdicosmo]

For biblatex export I use the BCF file from https://sourceforge.net/projects/biblatex-biber/files/biblatex-biber/testfiles to put together the quality report. Would you be able to get (or make) a BCF file that includes the rules about @software entries?

I would definitely be able to look into this, but we need first to ensure that Zotero supports all the fields needed for the four entries in biblatex-software: @software, @softwareversion, @softwaremodule and @codefragment.

To this end, it's better to start the other way around and make sure Zotero can faithfully import entries that conform to the biblatex-software style.

As a first step, I had a quick look at the software entry in Zotero, and there is some work to do: on the one hand Zotero needs to add several of the fields from biblatex-software; on the other hand there are fields in Zotero that are really surprising for a software entry: Series Title, Place, ISBN, Short Title, Archive, Loc. in Archive, Library Catalog, Call Number. I suppose Accessed corresponds to urldate and Extra to `notes.

What is the best way to add to Zotero the fields missing with respect to the ones listed in the biblatex-software style?

A second issue will be to decide how to represent the four software related entries in Zotero: the best way to ensure that import/export are idempotent would be to have four corresponding Zotero entries, the existing one, and the new softwareversion, softwaremodule and codefragment.

[retorquere]

I would definitely be able to look into this, but we need first to ensure that Zotero supports all the fields needed for the four entries in biblatex-software: @software, @softwareversion, @softwaremodule and @codefragment.

Even if Zotero doesn't, BBT can accommodate that. tex.referencetype: softwaremodule would write it out as @softwaremodule.

To this end, it's better to start the other way around and make sure Zotero can faithfully import entries that conform to the biblatex-software style.

And that would work the same way; when I import items I can't map to Zotero, I'd pick the closest match, and note the referencetype in the extra field.

As a first step, I had a quick look at the software entry in Zotero, and there is some work to do: on the one hand Zotero needs to add several of the fields from biblatex-software;

That's going to take a while. Adding doesn't happen as fast as even the Zotero devs would want.

on the other hand there are fields in Zotero that are really surprising for a software entry: Series Title, Place, ISBN, Short Title, Archive, Loc. in Archive, Library Catalog, Call Number.

No idea why those are there TBH.

I suppose Accessed corresponds to urldate

That is correct

and Extra to `notes.

That is usually correct. "Fields" such as tex.referencetype: are removed before writing it out as a note. The extra field isn't actually meant for notes from the looks of it; notes are for notes, extra was supposed to be for "extra-fields" I think. But I often put notes there too.

What is the best way to add to Zotero the fields missing with respect to the ones listed in the biblatex-software style?

https://retorque.re/zotero-better-bibtex/exporting/extra-fields/

A second issue will be to decide how to represent the four software related entries in Zotero: the best way to ensure that import/export are idempotent would be to have four corresponding Zotero entries, the existing one, and the new softwareversion, softwaremodule and codefragment.

That too is going to take a while. New item types are seldomly added to Zotero, as it's mostly CSL-oriented, and the current range seems to cover its needs, by and large. But the extra field can do that job. Requests for new item types are usually fielded on https://forums.zotero.org.

[rdicosmo]

Thanks for these precious pointers. If I understand well, it seems that the extra field may be the way to go if we want to get import/export up and running quickly. Would this be problematic if/when a proposal for an extension to the Zotero blessed fields/entry types goes through later on?

[retorquere]

Thanks for these precious pointers. If I understand well, it seems that the extra field may be the way to go if we want to get import/export up and running quickly.

Yes.

Would this be problematic if/when a proposal for an extension to the Zotero blessed fields/entry types goes through later on?

No. The fields will be automatically migrated by either Zotero or BBT when new fields become available. But even when not, both Zotero and BBT have backwards compatibility; even fields in extra that are supported on all types are still picked up from extra.

[njbart]

@retorquere - Since you asked: Honestly, I have no idea how popular the biblatex-software package is or is likely to become. My main concern is rather that BBT should not break existing widely used styles such as the various (vanilla) biblatex styles and biblatex-chicago (which seem to work rather well with the current BBT biblatex export of @software entries, in particular when adding DOI, number, or type as needed via the cheater syntax) as well as biblatex-apa (where currently some rather straightforward remapping is required; mainly type → entrysubtype and organization → publisher).

Hence I would indeed prefer any export functions specifically tailored to meet biblatex-software’s requirements and incompatible with the styles listed above to sit behind a preference.

[retorquere]

Wait -- something in my understanding of how biblatex styles work must be wrong. I thought biblatex provided the "plumbing" but that in the end each individual style decides what fields are taken into account when assembling a bibliography? If that is (close enough to) correct, how does biblatex-software even work? Does it augment any style you happen to have loaded? Is it a style of its own?

[rdicosmo]

Let me clarify, following the above questions and remarks. biblatex-software is designed as a "style extension" that adds to any existing biblatex style support for the four new entries @software, @softwareversion, @softwaremodule and @codefragment. It does so precisely by using the beautiful modular architecture of biblatex. It is not intended as a style by its own, and will inherit the general behaviour of the style it extends (e.g. author/editor/organization typesetting or abbreviation etc.).

I do not foresee any comptibility issue precisely because of this:

• the handling of non-software related entries by the parent style is not changed in any way
• the only software related entry in biblatex is @software and is treated like @misc in all style

Full details are in the documentation (README.md and software-biblatex.pdf) on https://www.ctan.org/tex-archive/macros/latex/contrib/biblatex-contrib/biblatex-software

[rdicosmo]

there are fields in Zotero that are really surprising for a software entry: Series Title, Place, ISBN, Short Title, Archive, Loc. in Archive, Library Catalog, Call Number.

No idea why those are there TBH.

For biblatex-software the structure of the software related entries is the outcome of a working group of software experts whose outcome is available at https://gitlab.inria.fr/gt-sw-citation/bibtex-sw-entry

Is there a document where one can find a rationale for the structure of the Software entry in Zotero? We would be happy to provide input to the working group behind it.

[retorquere]

If this would only have BBT export fields that would be otherwise ignored by styles, I can consider that. I'd still need a debug log as explained in point 1 above for the entries you want exported this way, and a constructed biblatex file that shows what the desired output is for those entries.

If existing fields would change meaning, that'd be a problem.

[retorquere]

Is there a document where one can find a rationale for the structure of the Software entry in Zotero?

If it does exist, I would not know where. Zotero existed for quite a while before I got involved. Asking on https://forums.zotero.org/ is most likely to get you answers.

[rdicosmo]

If this would only have BBT export fields that would be otherwise ignored by styles, I can consider that. I'd still need a debug log as explained in point 1 above for the entries you want exported this way, and a constructed biblatex file that shows what the desired output is for those entries.

If existing fields would change meaning, that'd be a problem.

Ok, I do not foresee any problem then: all existing fields keep their meaning, and we introduced only the following new, software-specific fields:

• hal_id [not in biblatex standard styles] :: field (verbatim). A digital identifier for the
• hal_version [not in biblatex standard styles] :: field (verbatim). The version of the HAL software record designated by hal_id.
• license [not in biblatex standard styles] :: list (literal). The license/s of the title
• introducedin [not in biblatex standard styles] :: field (literal). If this is a software module or fragment,
• repository [not in biblatex standard styles] :: field (uri). The url of the code repository (e.g on GitHub, GitLab).
• swhid [not in biblatex standard styles] :: field (verbatim). The identifier of the digital object (a.k.a the software artifact itself).

I'll look into what's needed to make this work with Zotero/BBT, thanks again for the prompt feedback and precious information.

[retorquere]

This wouldn't help for #907 then btw, so that would require separate action.

[rdicosmo]

This wouldn't help for #907 then btw, so that would require separate action.

I added a reply there :-)

[letmejustputthishere]

I'd be really happy to have this feature, right now bibtex complains about the missing author/key when I'm trying to export a Software item from Zotero to a .bib file ... This means I need to add them manually for the moment

[retorquere]

If you get me a support log ID and a desired output, I can still have a look.

[rdicosmo]

Brief update: biblatex-software is now included in the latest official release of the ACM LaTeX class

[retorquere]

Cool. If either of you could get me a support log and a corresponding biblatex export modified to look like you think it should, I can have a look.

[retorquere]

closing for inactivity