Closed christophcemper closed 2 years ago
This is just a quick answer and we may be able to brake this story down in multiple requirements / issues
REQ-1: Structured output/export format for glossary terms
REQ-2: Structured input format for glossary terms
REQ-3 External Definitions
I've long been thinking about doing something based on JSON-LD and I think this one could make me work on it.
Hello @christophcemper . It took me a while but eventually there's an import
and export
functionality in glossarify-md@next
.
Exporting a glossary with terms in german
{
"glossaries": [{
"uri": "http://allIknow.com/glossary/de#",
"file": "./glossary.md",
"export": {
"file": "./glossary.json"
}
}],
"i18n": {
"locale": "de"
}
}
While I stated in REQ-3.2 that glossarify does not need to compile a Markdown file from a JSON import it was easier to implement so, eventually. So by default when importing terms any occurrences will be linked to the markdown file generated from the import.
There are two options by which you can choose to link to an external authoritative source, using a terms URI:
"showUris": true
will make the URI visible within the generated glossary.md
file (also possible: a markdown string with a placeholder ${uri}
""linkUris": true
will cause any term occurrences be linked to the external source rather than to the glossary of the markdown book. So a config on the importing side could look like:
{
"glossaries": [{
"import": {
"file": "./glossary.json"
},
"file": "./glossary.md",
"linkUris": true,
"showUris": true
}]
}
Would be glad to hear your feedback.
Thank you very much for the ping and the new feature! Fantastic!
I noticed some weeks ago that you were heavily working on it and going to lenghts I thought about but didn't suggest, so I was excited.
I am swamped in some other projects, including actually the complex Spec project - so that "pain" is still there and I cannot wait to roll this out to the project and give you extensive feedback!
Thanks again, expect detailled feedback in the next weeks when this is all in place - cannot wait for it myself!
I am closing this since v6.0.0 is out now featuring imports and exports. However, I am still interested in your feedback so feel free to keep on commenting on this issue.
What's your user story?
Story 1:
As a analyst of large multi component projects I would like to generate a glossary-reference-index for other projects to import, so they can use the Glossary in their source and create links to the place where the original glossary is published
related Story 2:
As a domain expert I would like to publish my authoritative glossary on the web myspecialknowhow.com/glossary and give other projects and people an easy way to use the term definitions and create links back to my glossary on their source.
less but still related Story 3:
As an analyst I would like to have externally defined Glossary terms linked with my document having term and term definition in the Link Title, but the actual link go out to URLs I pre-defined to go to authoritative sources Wikipedia, Investopedia, Merriam-Webster Medical Dictionary, etc.
How would you like the system behave to satisfy your needs? How would you like it not?
glossarify-md
source
elementsNote: on the format specification I am unsure, as research has shown quite a lot of different initiatives over the years, including some ISO standards. (I have not found yet, if there's a dominant syntax,language def to use)
Rationale:
Currently I clone relevant dependencies as sub modules, which does the job as in the requirements example for one. Example:
However this leads to duplication of the "common" glossaries across projects. And while this option is a good workaround for a local documentation base, it does not allow the second Story 2 use case.
The generates Glossary source files of each component could also be published e.g. on component2.at/en/component2-glossary-source.de.yaml for the German glossary terms of Component 2 Project
Do you know examples of systems that have a similar feature you need?
https://github.com/itsallcode/openfasttrace
OpenFastTrace does a great job for requirements tracing. It has an export/import function for the requirement outputs of a project, that can be included in other projects.
We use it to generate the requirements from one project as XML and import all requirements from the stack of inherited projects.
A similar functionality would allow us to export the terms and definitions per project using glossarify-md.
Additional context
Only generating links to glossary documents helps avoid redundancy and allows to reference external sources.
If the glossary-index-format is something easy to read and still ensure consistency in the editor then it may be even possible to create a list Glossary terms that should link out to say Wikipedia or another trusted source on the web.