When writing documentation, there's a way to create a "term list" using some special list syntax:
- term Word: the word's definition
Is there a way to have DocC aggregate these terms into a glossary page, and then allow me to link other things in the documentation to those terms? I was expecting to be able to do something like <term:SomeTerm> or <doc:term/SomeTerm>, but neither worked.
That feature doesn't exist in DocC today, but it's a reasonable idea. I'd hope that it wouldn't be limited to terms defined in lists, however. Inline definitions for new terms are pretty common across all sorts of docs.
I've filled out a feature request here: Linkable glossary · Issue #838 · apple/swift-docc · GitHub
as i understand it, term lists are just a markdown syntax extension for creating <dl> lists, so outlining these into a glossary page would mean there is no way to create a structured <dl> element that appears inline on a documentation page.
however, i don’t see why we can’t support a @Glossary block directive that would support this behavior. would that be an acceptable alternative?
I'm still struggling to find my way around DocC, so I can't speak to a @Glossary directive, as I've not had to use such directives before.
If that would get me a page of terms that I could use in a <term:The-Word> link throughout my docs, then great! :)
I think this is a good idea but I have some questions about how it would work.
Should every term list contribute to the glossary page? If not, how can a developer control which term lists contribute to the glossary page?
What happens if the same term is defined on multiple pages? This could happen when a term has different meaning in different local contexts.
What would the glossary page display? Should it repeat the definition of each term?
What order should the glossary page display terms? I've seen cases where a few related terms are listed and defined together. If one of these is separated from the other terms in the same list it may be hard for the reader to understand the term definition "out of context".
I haven't had time to think too much about this yet but my initial feeling is that it terms that would be displayed on a glossary page probably needs to be written in a way where they don't need any additional context to understand them. As such, it may make sense to annotate the specific term lists—for example by wrapping them in a new block directive—that are written so that they are independently understandable (without the context of the rest of the page where they're defined).
Taking that idea one step further; if these term definitions wouldn't need the context of any specific page, would it make sense to define them all in a glossary page and only link to them in the other places? That could allow a project to have more than one glossary page with terminology for different parts of the project.
in the interest of not overdesigning features, if a documentation engine allowed you to link to fragment URLs, would it be sufficient to just define the glossary as an ordinary article, and link to its headings with <doc:Glossary#Some%20term>?
A decent stop-gap feature would be to give the generated <dt> elements an id so I could construct links to them via <doc:Glossary#The-Term>
i know this may not be particularly relevant to you, but as a funny story, we enabled this for a while on Swiftinit last fall, and it turns out sometimes people redefine the same terms multiple times on the same page, which generates duplicate id attributes. which is not a problem for users, but when we publish such pages, we get inundated with suspicious traffic. my working hypothesis is there are malicious scripts that crawl the web for pages with markup errors, and use that as a signal to probe a site for vulnerabilities. the internet is a weird place.
so, i’ve worked on the site’s markdown semantic analyzer some more and once we are able to resolve all of the anchors in a particular documentation realm it should be possible to prevalidate all of those links and in anticipation of that i added support for linkable term lists in the Swiftinit’s documentation compiler.
one package that is using a lot of term lists is @hassila ’s package-benchmark, and some of the terms are quite elaborate, for example, --skip-target <skip-target>. it is not actually a problem for URLs, as these strings are completely URL-safe, but it would be painful to spell links to them in source due to percent encoding and the way markdown parses hyperlinks. perhaps those links might benefit from a more identifier-friendly alias. but adding such a feature would add to the complexity of term lists. thoughts?