From a851051de084ed55ca25e48ccc3568b32161b869 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Fri, 7 Nov 2025 11:12:20 +0100 Subject: [PATCH 1/8] Add initial glossary --- docs/glossary/TEMPLATE.md | 32 ++++++++++++++++++++ docs/glossary/bibliography.md | 55 +++++++++++++++++++++++++++++++++++ docs/glossary/catalogue.md | 55 +++++++++++++++++++++++++++++++++++ docs/glossary/citation-key.md | 51 ++++++++++++++++++++++++++++++++ docs/glossary/citation.md | 34 ++++++++++++++++++++++ docs/glossary/index.md | 3 ++ docs/glossary/library.md | 47 ++++++++++++++++++++++++++++++ docs/glossary/references.md | 35 ++++++++++++++++++++++ 8 files changed, 312 insertions(+) create mode 100644 docs/glossary/TEMPLATE.md create mode 100644 docs/glossary/bibliography.md create mode 100644 docs/glossary/catalogue.md create mode 100644 docs/glossary/citation-key.md create mode 100644 docs/glossary/citation.md create mode 100644 docs/glossary/index.md create mode 100644 docs/glossary/library.md create mode 100644 docs/glossary/references.md diff --git a/docs/glossary/TEMPLATE.md b/docs/glossary/TEMPLATE.md new file mode 100644 index 00000000000..5b933ef86c6 --- /dev/null +++ b/docs/glossary/TEMPLATE.md @@ -0,0 +1,32 @@ +--- +parent: Glossary +nav_order: 100 # remove this for the concrete term +--- + +# {{Term}} + +**Synonyms:** {{List of synonyms}} + +## Meaning + +{{Explain the meaning of the term, ideally one or two sentences. Include what it represents, its purpose, or how it is used in context.}} + +## Delimitation (Scope and Exclusions) + +{{Clarify where this term applies and where it does not. Describe boundaries or cases that are explicitly excluded.}} + +## Validity + +{{Describe temporal, spatial, or contextual validity — for example, when or where the term is applicable.}} + +## Naming and Uniqueness + +{{Explain how the term is identified unambiguously — e.g., by an ID, key, or other defining attributes.}} + +## Open Issues / Uncertainties + +{{List unresolved questions, unclear definitions, or aspects pending clarification.}} + +## Related Terms (Cross-References) + +{{List (and possibly link) related or similar terms, e.g., “User”, “Identifier”, “Session Token”.}} diff --git a/docs/glossary/bibliography.md b/docs/glossary/bibliography.md new file mode 100644 index 00000000000..0d4cfae99be --- /dev/null +++ b/docs/glossary/bibliography.md @@ -0,0 +1,55 @@ +--- +parent: Glossary +--- + +# Bibliography + +**Synonyms:** Literature list + +## Meaning + +A **bibliography** is a structured list or catalog of written works, such as books, articles, reports, or other publications, usually organized for scholarly or informational purposes. +It can describe *all* literature relevant to a topic, not only those directly cited in a specific work. + +In JabRef and literature management, a bibliography represents a **conceptual collection of bibliographic records** — the intellectual set of works compiled for study, documentation, or publication. + +## Delimitation (Scope and Exclusions) + +* **Not the same as references:** + *[References](references.md)* are the specific sources cited within a publication; a *bibliography* may also include works *consulted but not cited*. +* **Not the same as a [library](library.md):** + A *library* is the concrete storage file (e.g., a `.bib` file) containing bibliographic data. + A *bibliography* is the logical or thematic organization of that data. +* **Not a [citation](citation.md):** + A *citation* is an inline or textual reference to one bibliographic entry. + +## Validity + +A bibliography can exist: + +* as part of a publication (e.g., “Bibliography” or “Works consulted” section), +* as a standalone compilation (e.g., “Annotated bibliography”), +* or as a conceptual subset within a reference manager such as JabRef. + +## Naming and Uniqueness + +Bibliographies may be organized by: + +* topic, +* author, +* period, +* or purpose (e.g., *project bibliography*, *course reading list*). + +Uniqueness is defined by content and context, not by file identity. + +## Open Issues / Uncertainties + +* The distinction between “bibliography” and “references” is blurred in many publication styles. +* Some citation styles (e.g., APA, IEEE) use the term “References” exclusively, even when a broader list would qualify as a bibliography. + +## Related Terms (Cross-References) + +* [References](references.md) +* [Library](library.md) +* [Entry](entry.md) +* [Citation](citation.md) diff --git a/docs/glossary/catalogue.md b/docs/glossary/catalogue.md new file mode 100644 index 00000000000..31b6a833729 --- /dev/null +++ b/docs/glossary/catalogue.md @@ -0,0 +1,55 @@ +--- +parent: Glossary +--- + +# Catalogue + +**Synonyms:** Online library, Literature database, Reference source, Data provider + +## Meaning + +A **catalogue** is an online bibliographic data source that allows searching, retrieving, and importing metadata for scholarly works such as journal articles, conference papers, and books. +In JabRef, a catalogue refers to an **external service or repository** — for example, ACM Digital Library, IEEE Xplore, Google Scholar, CrossRef, or arXiv — from which bibliographic entries can be fetched. + +Catalogues provide structured metadata (author, title, DOI, year, etc.) that JabRef imports to enrich or create local entries in a user’s library. + +## Delimitation (Scope and Exclusions) + +* **Not the same as a library:** + A *[library](library.md)* is the local `.bib` file managed in JabRef; a *catalogue* is an external source from which data is imported. +* **Not the same as a bibliography:** + A *[bibliography](bibliography.md)* is a conceptual collection of works; a *catalogue* is a retrieval system that provides access to such works. +* **Not the same as references:** + *[References](references.md)* are selected works cited in a publication, possibly originating from multiple catalogues. +* **Not a search engine in general:** + Although some catalogues expose web search interfaces, their primary function is structured metadata access. + +## Validity + +A catalogue is valid as long as its public interface (API or HTML interface) is operational and accessible. + +Different catalogues may use: + +* standard interfaces (e.g., **DOI**, **OAI-PMH**, **OpenSearch**), +* custom APIs (e.g., **CrossRef REST API**), +* or web-scraping-based access (e.g., Google Scholar). + +## Naming and Uniqueness + +Each catalogue is identified by: + +* its **provider name** (e.g., “ACM Digital Library”), and +* its **base URL** or **API endpoint**. + +In JabRef’s internal configuration, catalogues correspond to **[fetchers](../code-howtos/fetchers.md)**, each implementing a standardized interface for metadata retrieval. + +## Open Issues / Uncertainties + +* Availability and licensing of catalogue APIs may change without notice. +* Metadata quality and completeness vary by provider. +* Rate limits or CAPTCHA systems can restrict automated access. +* The term “catalogue” is JabRef-specific; other reference managers use “online database” or “data source.” + +## Related Terms (Cross-References) + +[Library](library.md), [Bibliography](bibliography.md), [Citation](citation.md) diff --git a/docs/glossary/citation-key.md b/docs/glossary/citation-key.md new file mode 100644 index 00000000000..4a6df54f2f1 --- /dev/null +++ b/docs/glossary/citation-key.md @@ -0,0 +1,51 @@ +--- +parent: Glossary +--- + +# Citation key + +**Synonyms:** BibTeX key + +## Meaning + +A **citation key** is a short, unique identifier assigned to a bibliographic +entry. It is used in documents (e.g. LaTeX) and tools (e.g. JabRef) to refer +to that entry in citations, cross-references, and commands. + +Example: `LunaOstos2024` + +## Delimitation (Scope and Exclusions) + +- It is **not** the same as: + - a database primary key, + - a persistent identifier (DOI, ISBN, URI), + - a filename. +- It is not globally unique across all users or projects, only within the + scope where the bibliography is used. + +## Validity + +- Must be unique **within a given bibliography file or project**. +- May change if the user renames it or regeneration rules change. +- Not guaranteed to be stable across different tools or imported/exported files + unless explicitly preserved. + +## Naming and Uniqueness + +- Allowed characters and format depend on the target system (e.g. BibTeX vs. + BibLaTeX) but are typically ASCII without spaces. +- JabRef and similar tools can **generate** citation keys based on patterns + (author, year, title, etc.). +- Uniqueness is usually enforced by the reference manager; collisions must be + resolved. + +## Open Issues / Uncertainties + +- No universal standard across all tools and workflows. +- Migration between tools or key-pattern changes can break existing documents + if keys are not updated consistently. + +## Related Terms (Cross-References) + +- [Bibliography](bibliography.md) +- [Citation](citation.md) diff --git a/docs/glossary/citation.md b/docs/glossary/citation.md new file mode 100644 index 00000000000..98fb5032285 --- /dev/null +++ b/docs/glossary/citation.md @@ -0,0 +1,34 @@ +--- +parent: Glossary +--- + +# Citation + +## Meaning + +A citation is a reference to a source. More precisely, a citation is an abbreviated alphanumeric expression embedded in the body of an intellectual work that denotes an entry in the bibliographic references section of the work for the purpose of acknowledging the relevance of the works of others to the topic of discussion at the spot where the citation appears. +[Source: [WikiPedia](https://en.wikipedia.org/wiki/Citation)] + +Example: + +> In their study, Ostos et al. (2024) employed interviews with both plant workers and farmers to gather data, with the aim of corroborating existing reports and gaining new insights, respectively. + +## Delimitation (Scope and Exclusions) + +{{Clarify where this term applies and where it does not. Describe boundaries or cases that are explicitly excluded.}} + +## Validity + +{{Describe temporal, spatial, or contextual validity — for example, when or where the term is applicable.}} + +## Naming and Uniqueness + +{{Explain how the term is identified unambiguously — e.g., by an ID, key, or other defining attributes.}} + +## Open Issues / Uncertainties + +{{List unresolved questions, unclear definitions, or aspects pending clarification.}} + +## Related Terms (Cross-References) + +{{List (and possibly link) related or similar terms, e.g., “User”, “Identifier”, “Session Token”.}} diff --git a/docs/glossary/index.md b/docs/glossary/index.md new file mode 100644 index 00000000000..48a1504054a --- /dev/null +++ b/docs/glossary/index.md @@ -0,0 +1,3 @@ +# Glossary + +This section collects important terms in the domain of JabRef. diff --git a/docs/glossary/library.md b/docs/glossary/library.md new file mode 100644 index 00000000000..c90fe2519d2 --- /dev/null +++ b/docs/glossary/library.md @@ -0,0 +1,47 @@ +# Library + +**Synonyms:** BibTeX file, `.bib` file, Database file, Bibliographic library + +## Meaning + +A **library** is a data file that stores a collection of bibliographic entries in a structured format (**BibTeX** or **BibLaTeX**). +In JabRef, a library is the **working data source** containing all references managed by the user — it is the digital equivalent of a physical card catalog. + +Each library file typically has the extension `.bib` and can contain hundreds or thousands of bibliographic entries, along with metadata such as groups, keywords, and linked files. + +## Delimitation (Scope and Exclusions) + +* **Not the same as a bibliography:** + A *[bibliography](bibliography.md)* is the conceptual list of relevant works; a *library* is the file storing the corresponding data. +* **Not the same as references**: + [References](references.md) are the specific works cited in a publication, often a subset of a larger library. +* **Not the same as a database:** + While technically similar, JabRef libraries are *file-based*; databases (e.g., SQL, Zotero, or shared repositories) provide multi-user or networked storage. +* **Not the same as a citation:** + A *[citation](citation.md)* refers to an entry in the library but is not part of the data container itself. + +## Validity + +A library is valid as long as it can be parsed by JabRef or other BibTeX-compatible tools. + +It may represent: + +* a user’s complete reference collection, +* a project-specific subset, +* or a shared file under version control. + +## Naming and Uniqueness + +* Identified by its **file path** and **name** (e.g., `references.bib`). +* Each entry inside a library must have a **unique [citation key](citation-key]**. +* Libraries may be linked or merged to form larger collections. + +## Open Issues / Uncertainties + +* Encoding inconsistencies (e.g., UTF-8 vs. legacy encodings) can affect portability. +* Some tools extend the BibTeX syntax (e.g., BibLaTeX fields), leading to partial incompatibility. +* Synchronization between multiple libraries can cause key collisions. + +## Related Terms (Cross-References) + +[Bibliography](bibliography.md), [Citation](citation.md), [Citation key](citation-key.md) diff --git a/docs/glossary/references.md b/docs/glossary/references.md new file mode 100644 index 00000000000..786bd046489 --- /dev/null +++ b/docs/glossary/references.md @@ -0,0 +1,35 @@ +# References + +**Synonyms:** Bibliographic References, Reference List, Literature, Literature List, Works Cited + +## Meaning + +**References** is a structured list of works cited in a scientific work. +collection of bibliographic records describing scholarly works such as articles, books, or reports. + +In JabRef, a bibliography usually corresponds to a **.bib file** (BibTeX or BibLaTeX format) that stores all entries used for citation and reference management. + +## Delimitation (Scope and Exclusions) + +A bibliography is not the same as: +- a **[citation](citation.md)**, which is an in-text reference to a work; +- a **[library](library.md)**, which stores physical or digital documents; +- a **database connection**, which may serve as a data source for bibliographic information but is not itself a bibliography. + +## Validity + +Applicable to all contexts in which bibliographic metadata is collected, organized, and exported — independent of citation style (BibTeX, BibLaTeX, CSL, etc.) or output format (PDF, HTML, DOCX). +Valid both for local files and online collections managed through JabRef integrations. + +## Naming and Uniqueness + +Each bibliography is typically represented by a **file path** or **project identifier**. +Within a bibliography, every **[citation key](citation-key.md)** (BibTeX key) must be unique to ensure unambiguous citation references. + +## Open Issues / Uncertainties + +The distinction between *references*, *bibliography* and *database* may vary across user communities. + +## Related Terms (Cross-References) + +[Bibliography](bibliography.md), [Citation](citation.md), [Citation key](citation-key.md) From e1cc25a320e6eeea68792b65a2d3fdd6fb70027c Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Fri, 7 Nov 2025 11:17:39 +0100 Subject: [PATCH 2/8] Enable rendering of children --- docs/architecture-and-components.md | 1 + docs/glossary/index.md | 4 ++++ 2 files changed, 5 insertions(+) diff --git a/docs/architecture-and-components.md b/docs/architecture-and-components.md index 67de9f4fce4..77382df14ea 100644 --- a/docs/architecture-and-components.md +++ b/docs/architecture-and-components.md @@ -1,4 +1,5 @@ --- +nav-order: 8 --- # Architecture and Components diff --git a/docs/glossary/index.md b/docs/glossary/index.md index 48a1504054a..84c14f44bb6 100644 --- a/docs/glossary/index.md +++ b/docs/glossary/index.md @@ -1,3 +1,7 @@ +--- +nav_order: 100 +has_children: true +--- # Glossary This section collects important terms in the domain of JabRef. From 6b90d7a7ec4bc54ba71252c68028fb06ab41662f Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Sun, 9 Nov 2025 15:55:22 +0100 Subject: [PATCH 3/8] Fix broken link --- docs/glossary/bibliography.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/glossary/bibliography.md b/docs/glossary/bibliography.md index 0d4cfae99be..16c54683d9d 100644 --- a/docs/glossary/bibliography.md +++ b/docs/glossary/bibliography.md @@ -49,7 +49,4 @@ Uniqueness is defined by content and context, not by file identity. ## Related Terms (Cross-References) -* [References](references.md) -* [Library](library.md) -* [Entry](entry.md) -* [Citation](citation.md) +[References](references.md), [Library](library.md), [Entry](entry.md), [Citation](citation.md) From c05278370a10e266208e46a2f4ed3bf61c4c5fb9 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Sun, 9 Nov 2025 15:56:13 +0100 Subject: [PATCH 4/8] Add hint on database --- docs/glossary/library.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/glossary/library.md b/docs/glossary/library.md index c90fe2519d2..97191f0ea7f 100644 --- a/docs/glossary/library.md +++ b/docs/glossary/library.md @@ -38,6 +38,7 @@ It may represent: ## Open Issues / Uncertainties +* Historically, this was called `database` in JabRef and there is still work to do to rename it. * Encoding inconsistencies (e.g., UTF-8 vs. legacy encodings) can affect portability. * Some tools extend the BibTeX syntax (e.g., BibLaTeX fields), leading to partial incompatibility. * Synchronization between multiple libraries can cause key collisions. From e0fb3d57763e87efe5d83fcc3898a38c3d9c8478 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Sun, 9 Nov 2025 15:58:50 +0100 Subject: [PATCH 5/8] Fix markdown lint issues --- docs/glossary/citation-key.md | 21 ++++++++------------- docs/glossary/library.md | 2 +- docs/glossary/references.md | 1 + 3 files changed, 10 insertions(+), 14 deletions(-) diff --git a/docs/glossary/citation-key.md b/docs/glossary/citation-key.md index 4a6df54f2f1..cf499ef33f2 100644 --- a/docs/glossary/citation-key.md +++ b/docs/glossary/citation-key.md @@ -17,11 +17,10 @@ Example: `LunaOstos2024` ## Delimitation (Scope and Exclusions) - It is **not** the same as: - - a database primary key, - - a persistent identifier (DOI, ISBN, URI), - - a filename. -- It is not globally unique across all users or projects, only within the - scope where the bibliography is used. + - a database primary key, + - a persistent identifier (DOI, ISBN, URI), + - a filename. +- It is not globally unique across all users or projects, only within the scope where the bibliography is used. ## Validity @@ -32,18 +31,14 @@ Example: `LunaOstos2024` ## Naming and Uniqueness -- Allowed characters and format depend on the target system (e.g. BibTeX vs. - BibLaTeX) but are typically ASCII without spaces. -- JabRef and similar tools can **generate** citation keys based on patterns - (author, year, title, etc.). -- Uniqueness is usually enforced by the reference manager; collisions must be - resolved. +- Allowed characters and format depend on the target system (e.g. BibTeX vs. BibLaTeX) but are typically ASCII without spaces. +- JabRef and similar tools can **generate** citation keys based on patterns (author, year, title, etc.). +- Uniqueness is usually enforced by the reference manager; collisions must be resolved. ## Open Issues / Uncertainties - No universal standard across all tools and workflows. -- Migration between tools or key-pattern changes can break existing documents - if keys are not updated consistently. +- Migration between tools or key-pattern changes can break existing documents if keys are not updated consistently. ## Related Terms (Cross-References) diff --git a/docs/glossary/library.md b/docs/glossary/library.md index 97191f0ea7f..084c8415eba 100644 --- a/docs/glossary/library.md +++ b/docs/glossary/library.md @@ -44,5 +44,5 @@ It may represent: * Synchronization between multiple libraries can cause key collisions. ## Related Terms (Cross-References) - + [Bibliography](bibliography.md), [Citation](citation.md), [Citation key](citation-key.md) diff --git a/docs/glossary/references.md b/docs/glossary/references.md index 786bd046489..b74fa7e853f 100644 --- a/docs/glossary/references.md +++ b/docs/glossary/references.md @@ -12,6 +12,7 @@ In JabRef, a bibliography usually corresponds to a **.bib file** (BibTeX or BibL ## Delimitation (Scope and Exclusions) A bibliography is not the same as: + - a **[citation](citation.md)**, which is an in-text reference to a work; - a **[library](library.md)**, which stores physical or digital documents; - a **database connection**, which may serve as a data source for bibliographic information but is not itself a bibliography. From e21d7a6035128c07c295f62bf698cc222ea0f830 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Sun, 9 Nov 2025 16:10:38 +0100 Subject: [PATCH 6/8] Update docs/glossary/TEMPLATE.md Co-authored-by: Subhramit Basu --- docs/glossary/TEMPLATE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/glossary/TEMPLATE.md b/docs/glossary/TEMPLATE.md index 5b933ef86c6..86f86fdf2b4 100644 --- a/docs/glossary/TEMPLATE.md +++ b/docs/glossary/TEMPLATE.md @@ -9,7 +9,7 @@ nav_order: 100 # remove this for the concrete term ## Meaning -{{Explain the meaning of the term, ideally one or two sentences. Include what it represents, its purpose, or how it is used in context.}} +{{Explain the meaning of the term, in ideally one or two sentences. Include what it represents, its purpose, or how it is used in context.}} ## Delimitation (Scope and Exclusions) From 2338747c3d6f5f52f2a1cd4c3e56040c95140705 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Sun, 9 Nov 2025 16:11:27 +0100 Subject: [PATCH 7/8] Fix spaces --- docs/glossary/citation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/glossary/citation.md b/docs/glossary/citation.md index 98fb5032285..b5a00ef8352 100644 --- a/docs/glossary/citation.md +++ b/docs/glossary/citation.md @@ -11,7 +11,7 @@ A citation is a reference to a source. More precisely, a citation is an abbrevia Example: -> In their study, Ostos et al. (2024) employed interviews with both plant workers and farmers to gather data, with the aim of corroborating existing reports and gaining new insights, respectively. +> In their study, Ostos et al. (2024) employed interviews with both plant workers and farmers to gather data, with the aim of corroborating existing reports and gaining new insights, respectively. ## Delimitation (Scope and Exclusions) From 9ab7054474fd486e256524b4cb6ee359e4f1c718 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 10 Nov 2025 00:36:58 +0100 Subject: [PATCH 8/8] Remove 404 link --- docs/glossary/bibliography.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/glossary/bibliography.md b/docs/glossary/bibliography.md index 16c54683d9d..5e129f16ef3 100644 --- a/docs/glossary/bibliography.md +++ b/docs/glossary/bibliography.md @@ -49,4 +49,4 @@ Uniqueness is defined by content and context, not by file identity. ## Related Terms (Cross-References) -[References](references.md), [Library](library.md), [Entry](entry.md), [Citation](citation.md) +[References](references.md), [Library](library.md), [Citation](citation.md)