robotframework / robotframework/robotframework-RFCP-syllabus

Allow for a 'backlink' generated solution in Glossary / linking

Open
#85 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
TypeScript
Stars
20
Forks
20
PR merge metrics
No merged PRs in 30d

Description

A notation method to link to a 'in context' location inside the glossary, so that people can navigate from the glossary to the place (or places) where they can read more about a term inside that context. This allows for navigation to and from glossary as well.

We could keep the current :term[...] notation and extend it only for the special cases where we want a glossary backlink.

Examples:

:term[Variable Scope]
:term[test cases]{term="Test Case"}
:term[Variable Scope]{source="#variable-scope-explained"}
:term[test cases]{term="Test Case" source="/docs/tests#test-case-structure"}

Proposal:

  • Keep :term[...] as the standard glossary link syntax.
  • Keep {term="..."} for alias text.
  • Add an optional source="..." attribute for the few cases where a glossary entry should offer a “read more” backlink into the docs.
  • If no source is given, no backlink is created in the glossary entry.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating the implementation of the :term[...] syntax and the glossary generation or rendering path. Trace how the existing term and alias attributes are handled, then verify the proposed source attribute with the examples in this issue; done means glossary entries can optionally link back to the specified context location without changing entries that omit source.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.