Update / Improve IEEE Support

[ocouch]

I've just been reviewing IEEE.csl, the IEEE referencing guide, and the Zotero/CSL TypeMap (see #5365 ).

Edit: I see there is some coverage of this in the zotero-bits repository, and some changes have already been implemented in 1.0.2. Maybe the zotero-bits repository is a better location for this issue? Either way, it'd be good to consolidate the efforts into one place with a grand plan.

IEEE support is relatively incomplete at present, and the existing csl could do with an overhaul. However, it's a major style with a lot of dependent styles (220!), so changes will need to be considered carefully, and may require additional csl variables/types. I've analysed the reference guide and extracted a list of "IEEE variables." (First pass so needs refinement).

Process to update

1. Identify all information required by the IEEE reference guide
2. Cross reference with the CSL schema to identify any missing variables
3. Add missing variables to CSL schema
4. Update proc-js (if required) to handle new types
5. Update clients (zotero, Mendeley etc.) to provide end user access to the features.

Progress on 1 and 2:

I've matched these up to existing CSL variables as much as possible, and matched up the IEEE types to CSL types as much as possible, as per the giant mess of tables below. A blank cell indicates I thought there was no apparent suitable match.

Note that there are a few oddball IEEE Types, like Handbooks and Online Patents which do not list an author first. There are also a few minor inconsistencies in the guide.

I strongly recommend renaming IEEE.csl and IEEE-with-URL.csl to IEEE-without-URL.csl and IEEE.csl, respectively. The reference guide clearly indicates URLs should always be included when available, unless there is also a DOI for the citation (in which case it's up to the author whether they include either or both).

The point of a reference is to enable a reader to be able to access and verify an author's claims - excluding URLs for content sourced online goes against that fundamental purpose.

Note that the IEEE referencing guide is missing some basic, essential engineering document types: Technical Datasheets, however, I believe this style should simply aim to reproduce the Referencing Guide as faithfully as possible, and leave the addition of other types to dependent styles.

IEEE Variable List

IEEE Variables	Example Value	Format/Rules
Author	L. S. Carmichael,	An individual. Up to 6 must be listed, after which use et al. (Italicised).Use commas around Jr., Sr., and III in names
Chapter/Section/Paper Title	"Title of chapter in the book,"	In quotations
Title/Conference Proceedings Title	Title of Published Book,	In Italic
Edition	10th ed.	lower case
Publisher City	New York
Publisher State	NY	Only for US States
Country	USA:	followed by colon
Publisher	McGraw-Hill,	Also includes company names
Year	2021
Chapter Num	ch. 2
Section Num	sec. 3
Page Range	pp. 47–160	Dash separated
URL/Available	"Available: http://press-pubs.uchicago.edu/founders/ Available: LEXIS Library: GENFED File: BILLS"	Does not end in a full-stop
Editor/Translator	P. G. Harper and B. S. Wherret, Eds.
Series Title	"(Applied Mathematics Series 55) in Computational Electrodynamics II"	Follows Title, two formatting options
Volume Number	vol. 4
Conference Name	Presented at the Proc. 1996 Robot. Automat. Conf.	There's a prescribed list of abbreviations to use. Articles and prepositions (eg. "of the", "on") are omitted from the name
Physical location (City)	Dallas
Physical State	NY	US States only
Physical Location (Country)	Japan
Month	Jun.
day(s)	12–16
Paper Number	Paper 70 CP 637
DOI	doi: 10.1145/2333660.2333752.
Medium	[Online]	Surrounded by brackets
Accessed time/date	Accessed: Jun. 19, 2014	short date
Language	(in Japanese)	Follows the Publisher name
Semester	(2014, Winter)
Comment,/case	"(Justice Brandeis, dissenting) (U.S. Court of Appeals for the First Circuit)
Supplement"
Patent No
Periodical no.	no. 6
Not yet published	"to be published submitted for publication
early access"	3 distinct types
Aricle Number	Art. No. 061103
Report Number	Rep. TR-0200
Version Number
Description
Repository/Location or Archive
Department	Dept. Elect. Eng.
University	Harvard Univ.
Legislative body
Number of Congress
Session
Website Title

IEEE Variables to CSL Variables

IEEE Variable	CSL variable	Description
	abstract	[standard] abstract of the item (e.g. the abstract of a journal article)
Accessed date	accessed	[date] date the item has been accessed
	annote*	[standard] reader’s notes about the item content
	archive	[standard] archive storing the item
Repository/Location or Archive	archive_location	[standard] storage location within an archive (e.g. a box and folder number)
	archive-place*	[standard] geographic location of the archive
Author	author	[name] author
Legislative body	authority	[standard] issuing or judicial authority (e.g. “USPTO” for a patent, “Fairfax Circuit Court” for a legal case)
	call-number	[standard] call number (to locate the item in a library)
Chapter Num	chapter-number	[number] chapter number
	citation-label*	[standard] label identifying the item in in-text citations of label styles (e.g. “Ferr78”). May be assigned by the CSL processor based on item metadata.
	citation-number*	[standard] index (starting at 1) of the cited reference in the bibliography (generated by the CSL processor)
	collection-editor	[name] editor of the collection holding the item (e.g. the series editor for a book)
	collection-number	[number] number identifying the collection holding the item (e.g. the series number for a book)
Series Title	collection-title	[standard] title of the collection holding the item (e.g. the series title for a book)
	composer	[name] composer (e.g. of a musical score)
	container*	[date] ?
	container-author	[name] author of the container holding the item (e.g. the book author for a book chapter)
"Title/Conference Proceedings Title Website Title"	container-title	[standard] title of the container holding the item (e.g. the book title for a book chapter, the journal title for a journal article)
	container-title-short	[standard] short/abbreviated form of “container-title” (also accessible through the “short” form of the “container-title” variable)
	dimensions	[standard] physical (e.g. size) or temporal (e.g. running time) dimensions of the item
	director	[name] director (e.g. of a film)
DOI	DOI	[standard] Digital Object Identifier (e.g. “10.1128/AEM.02591-07”)
Edition	edition	[number] (container) edition holding the item (e.g. “3” when citing a chapter in the third edition of a book)
Editor	editor	[name] editor
	editorial-director*	[name] managing editor (“Directeur de la Publication” in French)
Conference Name	event	[standard] name of the related event (e.g. the conference name when citing a conference paper)
	event-date*	[date] date the related event took place
"City State
Country"	event-place	[standard] geographic location of the related event (e.g. “Amsterdam, the Netherlands”)
	first-reference-note-number*	[standard] number of a preceding note containing the first reference to the item. Assigned by the CSL processor. The variable holds no value for non-note-based styles, or when the item hasn’t been cited in any preceding notes.
	genre	[standard] class, type or genre of the item (e.g. “adventure” for an adventure movie, “PhD dissertation” for a PhD thesis)
	illustrator*	[name] illustrator (e.g. of a children’s book)
	interviewer	[name] interviewer (e.g. of an interview)
	ISBN	[standard] International Standard Book Number
	ISSN	[standard] International Standard Serial Number
Paper Number	issue	[number] (container) issue holding the item (e.g. “5” when citing a journal article from journal volume 2, issue 5)
"Month Day
Year"	issued	[date] date the item was issued/published
	jurisdiction*	[standard] geographic scope of relevance (e.g. “US” for a US patent)
	keyword*	[standard] keyword(s) or tag(s) attached to the item
Language	language	[standard] Language code. Not intended for display purposes.
	locator*	[standard] a cite-specific pinpointer within the item (e.g. a page number within a book, or a volume in a multi-volume work). Must be accompanied in the input data by a label indicating the locator type (see the Locators term list), which determines which term is rendered by cs:label when the “locator” variable is selected.
Medium	medium	[standard] medium description (e.g. “CD”, “DVD”, etc.)
Comment,/case	note	[standard] (short) inline note giving additional item details (e.g. a concise summary or commentary)
	number	[number] number identifying the item (e.g. a report number)
	number-of-pages	[number] total number of pages of the cited item
	number-of-volumes	[number] total number of volumes, usable for citing multi-volume books and such
	original-author*	[name] ?
	original-date*	[date] (issue) date of the original version
	original-publisher*	[standard] original publisher, for items that have been republished by a different publisher
	original-publisher-place*	[standard] geographic location of the original publisher (e.g. “London, UK”)
	original-title*	[standard] title of the original version (e.g. “Война и мир”, the untranslated Russian title of “War and Peace”)
Page Range	page	[standard] range of pages the item (e.g. a journal article) covers in a container (e.g. a journal issue)
	page-first*	[standard] first page of the range of pages the item (e.g. a journal article) covers in a container (e.g. a journal issue)
	PMCID*	[standard] PubMed Central reference number
	PMID*	[standard] PubMed reference number
Publisher	publisher	[standard] publisher
"Publisher City Publisher StatePublisher Country"	publisher-place	[standard] geographic location of the publisher
	recipient	[name] recipient (e.g. of a letter)
	references	[standard] resources related to the procedural history of a legal case
	reviewed-author	[name] author of the item reviewed by the current item
	reviewed-title*	[standard] title of the item reviewed by the current item
	scale	[standard] scale of e.g. a map
Section Num	section	[standard] container section holding the item (e.g. “politics” for a newspaper article)
	source	[standard] from whence the item originates (e.g. a library catalog or database)
Status/Unpublished	status	[standard] (publication) status of the item (e.g. “forthcoming”)
	submitted	[date] date the item (e.g. a manuscript) has been submitted for publication
"Chapter/Section/Paper Title Title/Conference Proceedings Title"	title	[standard] primary title of the item
	title-short	[standard] short/abbreviated form of “title” (also accessible through the “short” form of the “title” variable)
Translator	translator	[name] translator
URL/Available	URL	[standard] Uniform Resource Locator (e.g. “http://aem.asm.org/cgi/content/full/74/9/2766”)
"Patent Number Report Number Periodical Number Article Number Version Number"	version	[standard] version of the item (e.g. “2.0.9” for a software program)
Volume Number	volume	[number] (container) volume holding the item (e.g. “2” when citing a chapter from book volume 2)
	year-suffix*	[standard] disambiguating year suffix in author-date styles (e.g. “a” in “Doe, 1999a”)
University Semester
Department
University
Number of Congress

IEEE Types to CSL and Zotero Types

Zotero type	CSL type	IEEE Type
artwork	graphic
attachment	article
audioRecording	song
bill	bill	Government Documents
blogPost	post-weblog
book	book	Book
bookSection	chapter
case	legal_case	Court Decision
computerProgram	book
conferencePaper	paper-conference	Conferences and Conference Proceedings
dictionaryEntry	entry-dictionary
document	article
email	personal_communication	Unpublished
encyclopediaArticle	entry-encyclopedia
film	motion_picture
forumPost	post
hearing	bill
instantMessage	personal_communication
interview	interview
journalArticle	article-journal	Periodical
letter	personal_communication
magazineArticle	article-magazine
manuscript	manuscript
map	map
newspaperArticle	article-newspaper
note	article
patent	patent	Patent
podcast	song
presentation	speech	Lecture
radioBroadcast	broadcast
report	report	Report
statute	legislation	Law/Legislation
thesis	thesis	Theses and Dissertations
tvBroadcast	broadcast
videoRecording	motion_picture	Online Video
webpage	webpage	Websites
	dataset	Datasets
	entry
	figure
	musical_score
	pamphlet
	review
	review-book
	treaty
		Course
		CoursePack
		Handbook
		Manual
		Software
		Standards

[jounathaen]

One thing I noted from this style is, that the et-al-min is not set for citations (https://github.com/citation-style-language/styles/blob/40e5e02f422f48ae703269e60b00d94def5d6e33/ieee.csl#L310). The referenced style guide states:

Use “et al.” when three or more names are given for a reference cited in the text.

[adam3smith]

The citation for IEEE is a number. et al isn't relevant (the author names can be used in the article text, hence the instructions, but that's not something the CSL would be involved in)

[jounathaen]

Ok, I'm not very familiar with CSL, but I assumed that it also contains information on how to cite the authors correctly (like with LaTeX's \citeauthor). But if that's not the case, please ignore my comment.