Add initial glossary (#14248)

Co-authored-by: Subhramit Basu <[email protected]>

Author: koppor

docs/architecture-and-components.md

@@ -1,4 +1,5 @@
 ---
+nav-order: 8
 ---
 # Architecture and Components
 

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, in 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”.}}

docs/glossary/bibliography.md

@@ -0,0 +1,52 @@
+---
+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), [Citation](citation.md)

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)

docs/glossary/citation-key.md

@@ -0,0 +1,46 @@
+---
+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)

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”.}}

docs/glossary/index.md

@@ -0,0 +1,7 @@
+---
+nav_order: 100
+has_children: true
+---
+# Glossary
+
+This section collects important terms in the domain of JabRef.

docs/glossary/library.md

@@ -0,0 +1,48 @@
+# 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
+
+* 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.
+
+## Related Terms (Cross-References)
+
+[Bibliography](bibliography.md), [Citation](citation.md), [Citation key](citation-key.md)

docs/glossary/references.md

@@ -0,0 +1,36 @@
+# 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)