Skip to content

Commit 20e9f38

Browse files
s-heppners-heppner
committed
Add documentation/best-practices for IEEEtran style
This adds a documentation folder in which we should put documentation and best-practices about the different citation styles in the future.
1 parent 2cd8b8b commit 20e9f38

File tree

2 files changed

+214
-2
lines changed

2 files changed

+214
-2
lines changed

‎README.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,8 +49,9 @@ The script will parse the file, perform the checks and print out the results.
4949
### Defined Rulesets
5050
Currently, the following rulesets are shipped with the `bibtex_linter`:
5151

52-
- `bibtex_linter path/to/refs.bib ieeetr` (default): Citation style of some IEEE conferences (needs `IEEEtran.cls`)
53-
- `bibtex_linter path/to/refs.bib IEEEtran`: LaTeX built-in IEEE citation style (via `\bibliographystyle{IEEEtran}`)
52+
- `bibtex_linter path/to/refs.bib ieeetr` (default): Citation style of some IEEE conferences (needs `IEEEtran.cls`).
53+
- `bibtex_linter path/to/refs.bib IEEEtran`: LaTeX built-in IEEE citation style (via `\bibliographystyle{IEEEtran}`).
54+
Check out [this cheatsheet](docs/IEEEtran_best_practices.md) for documentation of the rules.
5455

5556
If you want to define your own rules, see the next section on how to do this:
5657

‎docs/IEEEtran_best_practices.md‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
# Best Practices for the `IEEEtran` Citation Style
2+
This document is meant as a cheatsheet for how to set up your `refs.bib` file when using the `IEEEtran` citation style.
3+
4+
> [!warning]
5+
> Do not confuse the LaTeX built-in IEEE citation style (via `\bibliographystyle{IEEEtran}`) with the `ieeetr` style
6+
> from the conference paper template `IEEEtran.cls`.
7+
8+
## Contents
9+
10+
## Choosing an Entry Type
11+
- [`@article`](#article): Referencing an article in a journal.
12+
- [`@conference`](#conference): Referencing a conference paper.
13+
- [`@online`](#online): Referencing something on the internet.
14+
- [`@book`](#book): Referencing a whole book.
15+
- [`@inbook`](#inbook): Referencing a part of a book (chapters or pages).
16+
- [`@incollection`](#incollection): Referencing a part of a book that has its own name.
17+
- [`@standard`](#standard): Referencing proposed or formally published standards.
18+
- [`@misc`](#misc): Anything else that does not fit the above.
19+
20+
## Article
21+
- Entry name: `@article`
22+
- Usage: Referencing an article in a journal.
23+
- Mandatory fields:
24+
- `author`: The author(s) of the article
25+
- `title`: The title of the article
26+
- `journal`: The journal where the article is published
27+
- `year`: The year of publication
28+
- Optional fields:
29+
- `volume`: Groups all issues published in a year.
30+
- `number`: (sometimes called "Issue"), specific issue within a volume.
31+
- `pages`: On which pages is the article inside the journal
32+
- `month`: The month of publication
33+
- `note`: See special rule below
34+
- Disallowed fields:
35+
- `url`: See special rule below
36+
- Special rules:
37+
- `note` and `url` convention: Do not use `url`, rather format the `note` in the following pattern:
38+
`[ONLINE]. Available: \url{...}, Accessed: YYYY-mmm-dd`
39+
40+
## Conference
41+
- Entry names: `@conference`, `@inproceedings`
42+
- Usage: Referencing a conference paper.
43+
- Mandatory fields:
44+
- `author`: The author(s) of the conference paper
45+
- `title`: The title of the conference paper
46+
- `booktitle`: The **name of the conference**
47+
- `publisher`: The entity publishing the proceedings (e.g., `IEEE IES`)
48+
- `year`: The year of publication
49+
- `type`: The paper type (e.g., `"Conference Paper"`)
50+
- Optional fields:
51+
- `series`: For conferences published in a recurring series (e.g., "Lecture Notes in Computer Science")
52+
- `editor`: The people who compiled/edited the proceedings volume.
53+
- `volume`: If part of a multi-volume proceedings, uncommon
54+
- `number`: Usually the issue number in a journal. Rarely needed for conference proceedings.
55+
- `organization`: The body hosting the conference (e.g., `IEEE IES`), see rule below.
56+
- `address`: The address of the publishing entity, uncommon.
57+
- `month`: The month of publication
58+
- `pages`: The pages in the proceedings where the paper is located
59+
- `note`: See special rule below
60+
- Disallowed fields:
61+
- `paper`: Seems to be not standard, so avoid using it
62+
- `url`: See special rule below
63+
- Special rules:
64+
- `note` and `url` convention: Do not use `url`, rather format the `note` in the following pattern:
65+
`[ONLINE]. Available: \url{...}, Accessed: YYYY-mmm-dd`
66+
- If both `organization` and `publisher` have the exact same value, only use `publisher`.
67+
68+
## Online
69+
- Entry names: `@online`, `@electronic`
70+
- Usage: Referencing something on the internet.
71+
- Mandatory fields
72+
- `author`: The author(s) of the online resource
73+
- `year`: The year of publication
74+
- `title`: The title of the online resource
75+
- `howpublished`: (Something like: "White paper", "Blog post", "GitHub Repository", etc.)
76+
- Optional fields:
77+
- `month`: The month of publication
78+
- `organization`: The publishing organization, see rule below
79+
- `address`: The address of the `organization`, uncommon.
80+
- `note`: See special rule below
81+
- Disallowed fields:
82+
- `url`: See special rule below
83+
- Special rules:
84+
- `note` and `url` convention: Do not use `url`, rather format the `note` in the following pattern:
85+
`[ONLINE]. Available: \url{...}, Accessed: YYYY-mmm-dd`
86+
- If `organization` and `author` are the same, only use `author`
87+
88+
## Book
89+
- Entry name: `@book`
90+
- Usage: Referencing a whole book.
91+
- Mandatory fields:
92+
- `author`: The author(s) of the book
93+
- `title`: The title of the book
94+
- `publisher`: The publisher of the book
95+
- `year`: The year of publication
96+
- Optional fields:
97+
- `edition`: Edition of the book
98+
- `series`: Name of the series, if the book is part of one
99+
- `editor`: Editor of the book
100+
- `address`: Address of the `publisher`, uncommon
101+
- `month`: Month of publication
102+
- `volume`: Volume if part of a book series, if existing
103+
- `number`: Number/Issue of the book series, if existing
104+
- `note`: See special rule below
105+
- Disallowed fields:
106+
- `url`: See special rule below
107+
- Special rules:
108+
- `note` and `url` convention: Do not use `url`, rather format the `note` in the following pattern:
109+
`[ONLINE]. Available: \url{...}, Accessed: YYYY-mmm-dd`
110+
- If `editor` and `publisher` are the same, only use `publisher`.
111+
112+
## InBook
113+
- Entry name: `@inbook`
114+
- Usage: Referencing a part of a book (chapters or pages).
115+
- Mandatory fields:
116+
- `author`: Author(s) of the referred part of the book
117+
- `title`: Title of the book
118+
- `publisher`: Publisher of the book
119+
- `year`: Year of publication
120+
- Optional fields:
121+
- `edition`: Edition of the book
122+
- `series`: Series of the book, if existing
123+
- `address`: Address of the publisher, uncommon
124+
- `month`: Month of publciation
125+
- `volume`: Volume, if the book is part of a series
126+
- `number`: Number/Issue, if the book is part of a series
127+
- `type`: Should be one of: "Chapter", "Section", "Appendix", "Part" or similar
128+
- `chapter`: Chapter number of the referenced part of the book, if applicable
129+
- `pages`: Pages of the referenced part in the book, if applicable
130+
- `note`: See special rule below
131+
- Disallowed fields:
132+
- `url`: See special rule below
133+
- `editor`: Field is not rendered
134+
- Special rules:
135+
- `note` and `url` convention: Do not use `url`, rather format the `note` in the following pattern:
136+
`[ONLINE]. Available: \url{...}, Accessed: YYYY-mmm-dd`
137+
138+
## InCollection
139+
- Entry name: `@incollection`
140+
- Usage: Referencing a part of a book that has its own name.
141+
- Mandatory fields:
142+
- `author`: Author(s) of the referenced part
143+
- `title`: Title of the referenced part
144+
- `booktitle`: Title of the book/collection the referenced part is a part of
145+
- `publisher`: Publisher of the book/collection the referenced part is a part of
146+
- `year`: Year of publication
147+
- Optional fields:
148+
- `edition`: Edition of the book/collection the referenced part is a part of
149+
- `series`: Series of the book/collection the referenced part is a part of, if existing
150+
- `editor`: Editor of the book/collection the referenced part is a part of, if existing
151+
- `address`: Address of the `publisher`
152+
- `month`: Month of publication
153+
- `chapter`: Chapter of the referenced part in the book/collection, if applicable
154+
- `pages`: Pages of the referenced part in the book/collection, if applicable
155+
- `note`: See special rule below
156+
- Disallowed fields:
157+
- `url`: See special rule below
158+
- `type`: Disallowed, since if it was set to (Article, Paper, etc.), we should use the proper entry type instead.)
159+
- Special rules:
160+
- `note` and `url` convention: Do not use `url`, rather format the `note` in the following pattern:
161+
`[ONLINE]. Available: \url{...}, Accessed: YYYY-mmm-dd`
162+
- If `editor` and `publisher` are the same, use `publisher`.
163+
164+
## Standard
165+
- Entry name: `@standard`
166+
- Usage: Referencing proposed or formally published standards.
167+
- Mandatory fields:
168+
- `title`: Title of the standard
169+
- `organization`: The issuing body or standards organization
170+
- `type`: One of: Standard, Technical Report, Recommendation, Specification, Guideline, Draft Standard, etc.
171+
- `number`: Number of the standard
172+
- `year`: Year of publication
173+
- Optional fields:
174+
- `author`: Author(s) of the standard, only if differing from `organization`, see below
175+
- `howpublished`: (how the standard is delivered or accessed "Online", "Print", "PDF", "Available from IEEE Xplore")
176+
- `revision`: Revision of the standard
177+
- `month`: Month of publication
178+
- `note`: See special rule bewlo
179+
- Disallowed fields:
180+
- `url`: See special rule below
181+
- Special rules:
182+
- `note` and `url` convention: Do not use `url`, rather format the `note` in the following pattern:
183+
`[ONLINE]. Available: \url{...}, Accessed: YYYY-mmm-dd`
184+
- If `author` and `organization` are the same, use `organization`
185+
186+
> [!note]
187+
> I advise against using `techreport`. Rather use `standard` instead.
188+
189+
## Misc
190+
- Entry name: `@misc`
191+
- Usage: Anything else that does not fit the above.
192+
- Mandatory fields:
193+
- `author`: Author(s) of the referenced object
194+
- `title`: Title of the referenced object
195+
- `howpublished`: How the referenced object is published
196+
- `year`: Year of publication
197+
- Optional fields:
198+
- `organization`: Publishing organization, only use if not equal to `author`
199+
- `address`: Address of the publishing organization, uncommon
200+
- `pages`: Pages, seems nonsensible to use
201+
- `month`: Month of publication
202+
- `note`: See special rule below
203+
- Disallowed fields:
204+
- `url`: See special rule below
205+
- Special rules:
206+
- `note` and `url` convention: Do not use `url`, rather format the `note` in the following pattern:
207+
`[ONLINE]. Available: \url{...}, Accessed: YYYY-mmm-dd`
208+
209+
> [!note]
210+
> Try using the other entry types instead of this one, if possible.
211+

0 commit comments

Comments
 (0)