{"id":13523604,"url":"https://github.com/RolfBremer/gloss-awe","last_synced_at":"2025-04-01T01:33:05.109Z","repository":{"id":164864399,"uuid":"639860731","full_name":"RolfBremer/gloss-awe","owner":"RolfBremer","description":"Automatically create a glossary in typst.","archived":false,"fork":false,"pushed_at":"2024-07-25T13:21:06.000Z","size":2048,"stargazers_count":19,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-11-02T08:30:19.281Z","etag":null,"topics":["glossary","typst"],"latest_commit_sha":null,"homepage":"","language":"Typst","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RolfBremer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-12T11:48:31.000Z","updated_at":"2024-10-17T15:59:54.000Z","dependencies_parsed_at":"2024-07-25T15:29:29.784Z","dependency_job_id":null,"html_url":"https://github.com/RolfBremer/gloss-awe","commit_stats":null,"previous_names":["rolfbremer/typst-glossary"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RolfBremer%2Fgloss-awe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RolfBremer%2Fgloss-awe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RolfBremer%2Fgloss-awe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RolfBremer%2Fgloss-awe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RolfBremer","download_url":"https://codeload.github.com/RolfBremer/gloss-awe/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246567081,"owners_count":20798110,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["glossary","typst"],"created_at":"2024-08-01T06:01:01.719Z","updated_at":"2025-04-01T01:33:01.697Z","avatar_url":"https://github.com/RolfBremer.png","language":"Typst","funding_links":[],"categories":["Templates \u0026 Libraries"],"sub_categories":["General"],"readme":"# gloss-awe\n\nAutomatically create a glossary in [typst](https://typst.app/).\n\nThis typst component creates a glossary page from a given pool of potential glossary\nentries using only those entries, that are marked with the `gls` or `gls-add` functions in\nthe document.\n\n⚠️ Typst is in beta and evolving, and this package evolves with it. As a result, no\nbackward compatibility is guaranteed yet. Also, the package itself is under development\nand fine-tuning.\n\n## Table of Contents\n\n* [Usage](#usage)\n  * [Marking the Entries](#marking-the-entries)\n  * [Controlling the Show](#controlling-the-show)\n  * [Hiding Entries from the Glossary Page](#hiding-entries-from-the-glossary-page)\n  * [Pool of Entries](#pool-of-entries)\n  * [Unknown Entries](#unknown-entries)\n  * [Creating the glossary page](#creating-the-glossary-page)\n* [Changelog](#changelog)\n  * [v0.1.5](#v015)\n  * [v0.1.4](#v014)\n  * [v0.1.3](#v013)\n  * [v0.1.2](#v012)\n  * [v0.1.1](#v011)\n  * [v0.1.0](#v010)\n  * [v0.0.5](#v005)\n  * [v0.0.4](#v004)\n  * [v0.0.3](#v003)\n  * [v0.0.2](#v002)\n\n## Usage\n\n### Adding the package to your project\n\nThe package can either be added to your project by adding the main file `gloss-awe.typ` and\nimporting it, or by importing the package via the typst package manager (available from\nTypst version 0.6.0 or later).\n\n#### Importing from File\n\n```typ\n    #import \"gloss-awe.typ\": *\n```\n\n#### Importing via Typst Package Manager\n\n```typ\n    #import \"@preview/gloss-awe:0.1.5\": *\n```\n\n### Marking the Entries\n\nTo include a term into the glossary, it can be marked with the `gls` function. The\nsimplest form is like this:\n\n```typ\nThis is how to mark something for the glossary in #gls[Typst].\n```\n\nThe gls function will render in the resulting document as defined with the specified\nshow rule (see below!).\n\n### Controlling the Show\n\nTo control, how the markers are rendered in the document, a function can be \nprovided for the markers:\n\n```typ\n#gls(showmarker: m =\u003e [#emph(m)])[Butterscotch]\n```\n\nThis sample will display the marked word as emphasized in the document.\n\n### Hiding Entries from the Glossary Page\n\nIt is also possible to hide entries (temporarily) from the generated glossary page without\nremoving any markers for them from the document.\n\nThe following sample will hide the entries for \"Amaranth\" and \"Butterscotch\" from the\nglossary, even if it is marked with `gls[...]` or `gls-add[...]` somewhere in the\ndocument.\n\n```typ\n    #let hidden-entries = (\n        \"Amaranth\",\n        \"Butterscotch\"\n    )\n\n    #make-glossary(glossary-pool, excluded: hidden-entries)\n```\n\n### Pool of Entries\n\nA \"pool of entries\" is a typst dictionary. It can be read from a file or may be the result\nof other operations.\n\nOne or more pool(s) are then given to the `make-glossary()` function. This will create a\nglossary page of all referenced entries. If given more than one pool, the order pools are\nsearched in the order they are given to the method. The first match wins. This can be used\nto have a global pool to be used in different documents, and another one for local usage\nonly.\n\nThe pool consists of a dictionary of definition entries. The key of an entry is the term.\nNote, that it is case-sensitive. Each entry itself is also a dictionary, and its main key\nis `description`. This is the content for the term. There may be other keys in an entry in\nthe future. For now, it supports:\n\n* description\n* link\n\nAn entry in the pool for the term \"Engine\" file may look like this:\n\n```typ\n    Engine: (\n        description: [\n\n            In the context of software, an engine...\n\n        ],\n        link: [\n\n            (1) Software engine - Wikipedia.\n            https://en.wikipedia.org/wiki/Software_engine\n            (13.5.2023).\n\n        ]\n    ),\n```\n\n### Unknown Entries\n\nIf the document marks a term that is not contained in the pool, an entry will be generated\nanyway, but it will be visually marked as missing. This is convenient for the workflow,\nwhere one can mark the desired entries while writing the document, and provide missing\nentries later.\n\nThere is a parameter for the `make-glossary()` function named `missing`, where a function\ncan be provided to format or even suppress the missing entries.\n\n### Creating the Glossary Page\n\nTo create the glossary page, provide the pool of potential entries to the make-glossary\nfunction. The following listing shows a complete sample document with a glossary. The\nsample glossary pool is contained in the main document as well:\n\n```typ\n    #import \"@preview/gloss-awe:0.1.5\": *\n\n    // Text settings\n    #set text(font: (\"Arial\", \"Trebuchet MS\"), size: 12pt)\n\n    // Defining the Glossary Pool with definitions.\n    #let glossary-pool = (\n        Cloud: (\n            description: [\n\n                Cloud computing is a model where computer resources are made available\n                over the internet. Such resources can be assigned on demand in a very short\n                time, and only as long as they are required by the user.\n\n            ]\n        ),\n\n        Marker: (\n            description: [\n\n                A Marker in `gloss-awe` is a typst function to mark a word or phrase to appear\n                in the documents glossary. The marker is also linked to the glossary section\n                by referencing the label `\u003cGlossary\u003e`.\n\n            ]\n        ),\n\n        Glossary: (\n            description: [\n\n                A glossary is a list of terms and their definitions that are specific to a\n                particular subject or field. It is used to define the intended meaning of\n                terms used in a document and to agree on a common definition of those terms. A\n                well-defined glossary can be very helpful in documents where very specific\n                meanings of certain terms are used.\n\n            ]\n        ),\n\n        \"Glossary Pool\": (\n            description: [\n\n                A glossary pool is a collection of glossary entries. An automated tool can\n                pull needed definitions from this pool to create the glossary pages for a\n                specific context.\n\n            ]\n        ),\n\n        REST: (\n            description: [\n\n                Representational State Transfer (abgekürzt REST) ist ein Paradigma für die\n                Softwarearchitektur von verteilten Systemen, insbesondere für Webservices.\n                REST ist eine Abstraktion der Struktur und des Verhaltens des World Wide\n                Web. REST hat das Ziel, einen Architekturstil zu schaffen, der den\n                Anforderungen des modernen Web besser genügt.\n\n            ]\n        ),\n\n        XML: (\n            description: [\n\n                XML stands for `'eXtensible Markup Language'`.\n\n            ],\n            link: [https://www.w3.org/XML]\n        ),\n    )\n\n    // Defining, how marked glossary entries in the document appear\n    #show figure.where(kind: \"jkrb_glossary\"): it =\u003e {it.body}\n\n    // This alternate rule, creates links to the glossary for marked entries.\n    // #show figure.where(kind: \"jkrb_glossary\"): it =\u003e [#link(\u003cGlossar\u003e)[#it.body]]\n\n    = My Sample Document with `gloss-awe`\n\n    In this document the usage of the `gloss-awe` package is demonstrated to create a glossary\n    with the help of a simple and small sample glossary pool. We have defined the pool in a\n    dictionary named #gls[Glossary Pool] above. It contains the definitions the `gloss-awe`\n    can use to build the glossary in the #gls[Glossary] section of this document. The pool\n    could also come from external files, like #gls[JSON] or #gls[XML] or other sources. Only\n    those definitions are shown in the glossary, that are marked in this document with one of\n    the #gls(entry: \"Marker\")[marker] functions `gloss-awe` provides.\n\n    If a Word is marked, that is not in the Glossary Pool, it gets a special markup in the\n    resulting glossary, making it easy for the Author to spot the missing information an\n    providing a definition. In this sample, there is no definition for \"JSON\" provided,\n    resulting in an Entry with a red remark \"#text(fill: red)[No~glossary~entry]\".\n\n    There is also a way to include Entries in the glossary for Words that are not contained in\n    the documents text:\n\n    #gls-add(\"Cloud\")\n    #gls-add(\"REST\")\n\n\n    = Glossary \u003cGlossary\u003e\n\n    This section contains the generated Glossary, in a nice two-column-layout. It also bears a\n    label, to enable the linking from marked words to the glossary.\n\n    #line(length: 100%)\n    #set text(font: (\"Arial\", \"Trebuchet MS\"), size: 10pt)\n    #columns(2)[\n        #make-glossary(glossary-pool)\n    ]\n\n```\n\nTo use more than one pool, this can be used instead:\n\n```typ\n#import \"/Global/GlossaryPool.typ\": glossary-pool\n#import \"/Global/LocalGlossaryPool.typ\": local-glossary-pool\n\n#columns(2)[\n    #make-glossary(local-glossary-pool, glossary-pool)\n]\n```\n\nUsing this, the local pool takes precedence over the global pool, because it is the first\nparameter.\n\nMore usage samples are shown in the document `sample-usage.typ` on\n[gloss-awe´s GitHub]([Title](https://github.com/RolfBremer/typst-glossary)).\n\nA more complex sample PDF is available there as well.\n\n\u003c/span\u003e\n\n## Changelog\n\n### v0.1.5\n\n* Migrate deprecated locate to context.\n\n### v0.1.4\n\n* Fix a Bug introduced in 0.1.3 where glossary entries with empty entries are not shown.\n\n### v0.1.3\n\n* Enhance internal `as-text` function to be more robust.\n* tidy up sample-usage.typ document.\n\n### v0.1.2\n\n* Provide a parameter to suppress \"no glossary entry\" messages in the glossary page.\n* Support rich content in glossary titles.\n* Increase robustness for different content in the entry.\n* Ignore empty glossary pools without throwing an error.\n\n### v0.1.1\n\n* Improve display behavior of `gls()` by not emitting additional spaces.\n* Clean up documentation.\n\n### v0.1.0\n\n* Add an optional parameter `sort: k =\u003e k` to make-glossary() to provide a method to\n  determine the sort key.\n* Remove the (mis-)usage of figures to mark glossary entries. This also removes the\n  requirement to have a show rule for those figures defined to suppress the markers.\n\n### v0.0.5\n\n* Address change in `figure.caption` in typst (commit: 976abdf ).\n\n### v0.0.4\n\n* Breaking: Renamed the main file from `glossary.typ` to `gloss-awe.typ` to match package.\n* Added support for hidden glossary entries.\n* Added a Changelog to this readme.\n\n### v0.0.3\n\n* Added support for package manager in Typst.\n* Add `gls-add[...]` function for entries that are not in the document.\n\n### v.0.0.2\n\n* Moved version to Github.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRolfBremer%2Fgloss-awe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FRolfBremer%2Fgloss-awe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRolfBremer%2Fgloss-awe/lists"}