Skip to content

Commit b9238c2

Browse files
s-heppners-heppner
authored
Add documentation/best-practices for IEEEtran style (#17)
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 b9238c2

File tree

2 files changed

+212
-2
lines changed

2 files changed

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

0 commit comments

Comments
 (0)