trustoverip / concepts-and-terminology-wg

Content and code repository for the Concepts & Terminology Working Group
https://trustoverip.github.io/concepts-and-terminology-wg/
Creative Commons Attribution 4.0 International
3 stars 3 forks source link

Discussion on Glossary generation #53

Open RieksJ opened 3 years ago

RieksJ commented 3 years ago

This issue aims to discuss glossary generation related topics such as:

  1. how do we inventory the terms that should be included in a glossary?
  2. what does a glossary entry look like? Is it fixed, can it be tailored somehow?
  3. what do we need from the corpus to allow for glossary generation?
  4. can there be different glossary generation tools?
  5. would/could a glossary generation tool be part of the tt-toolbox, or not? If so, do all such tools belong there?
  6. ...

And then let's make one (or two) to see if it works like we would like it to

dhh1128 commented 3 years ago

Re. #1: this is answered here

Re. #2: The job of our tooling is to export all the data that could be in a glossary entry (see here). A tool that is out of scope of our WG tools (e.g., mkdocs) can then do a prettified rendering of that data. It can be tailored in that tool, not ours.

Re. #3: We have already debated this at great length. I feel like this is already answered by the design we've constructed -- particularly, by the [internal data model of the corpus](https://github.com/trustoverip/concepts-and-terminology-wg/blob/master/docs/internal-data-model.md, including its term record and concept record.

Re. #4: There is only one tool for exporting data from the corpus, but it takes different export definitions or export sub-commands (export makedocs, export <something else>). Anything beyond the customization offered by this is the province of configuration for rendering tools like mkdocs.

Re. #5: Yes, as documented in the tt spec.