how to link vignettes automatically with internal links and check these links are not dead ?

Open
#6,373 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Stale
Tech stack
r
Domain
documentation

Research direction

Start by reviewing the vignette layout and the example datatable-secondary-indices-and-auto-indexing-en.Rmd, including its reference to “Joins and rolling joins”. Define how links to target vignettes and anchors should resolve across translated and English vignettes, including missing-target fallback behavior. Done should include an agreed filesystem/linking model and a way to detect dead targets and missing anchors.

Written by the indexing model from the issue text.

Description

translation

Two related topics here which emerged from my vignette translations :

  • Vignette referencing a target vignette
  • Vignette referencing an anchor in another vignette

Either they have been solved and I have skipped the resolution, or they could start a proposal.

Vignette referencing a target vignette

Manually of course one can verify by using the true name of the target vignette and then by checking it really exists in the directory - and this for each language.

Example:
datatable-secondary-indices-and-auto-indexing-en.Rmd ends by par "We will discuss fast subsets using keys and secondary indices to joins in the next vignette, “Joins and rolling joins”."
so I expect to see a link to the next vignette but there is none. So I guess a "Joins and rolling joins.Rmd" or similar must exist, but there is none.

Then are there some functions to declare these links ? Nice for example in blue if the target vignette exists., red if it is not created yet.

This applies also to translated vignettes i.e. a FR vignette should reference a FR vignette. If we adopt the principle of MediaWiki, a fallback solution can be applied. That means if FR target vignette is not defined, then use the EN one as target, or put it red if the EN does not exist. This is dynamic and once the target FR is created users are forwarded directly to it. That supposes also an item of higher level exists identifying the EN vignette as the mother which is aware of the name of its daughters.

This is a kind of internal URL but as vignettes are delivered within the package, a relative path could be used. Of course it is bound to the structure of the filesystem (to be defined once status of translated vignettes name/location is known)

Vignette referencing an anchor in the target vignette

Again as a similitude with MediaWiki, it should be possible to access a given section within another vignette. The same restrictions/fallback apply concerning the existence of the target vignette. Additional restriction could apply when the anchor is not defined in the target (pop up "anchor not found"). The anchor is NOT translated. It is the EN value forwarded on each translated page as translated page TOC is cloned on the structure of the EN mother (but of course with different titles).

Dominant language
R
Stars
3.9k
Forks
1.1k
Avg merge
14h 4m
Merged PRs (30d)
4

Contributor guide

Open the contributing guide

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.

More from Rdatatable/data.table

All issues in Rdatatable/data.table

Similar issues

More R issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.