Sorry I dropped the ball with this. I'm now getting up to speed with the project and the various issues.

I've been thinking and it might be that these issues with the dynamic help are unsolvable with the current approach of section matching (or string matching if we use gettext() (#16)). In summary the problem comes down to this: Rd files are processed in several stages, but the strings we are storing are not.

There are 3 moments when the documentation runs macros: 1. build, 2. install, 3. render. There is also #ifdef OS, which is run before install. Our translation step is done before render, so we miss any macro on the previous steps. There is also the issue with user-defined macros (See #28).

Using an example modified from the tools documentation:

  For example, this man page was:
  \enumerate{
    \item built on
    \Sexpr[stage=build]{format(Sys.time(), "\%Y-\%m-\%d at \%H:\%M:\%S")}
    # ifdef windows
    on windows
    #endif,
    \item installed on
    \Sexpr[stage=install]{format(Sys.time(), "\%Y-\%m-\%d at \%H:\%M:\%S")}, and
    \item rendered on
    \Sexpr[stage=render]{format(Sys.time(), "\%Y-\%m-\%d at \%H:\%M:\%S")}.
  }
}

We are taking this raw text and using it as "original" and translating it, but by the time we get the text to translate it looks like this:

  For example, this man page was:
  \enumerate{
    \item built on
    "2025-11-02 at 11:10:34"
    on windows,
    \item installed on
    "2025-12-20 at 18:07:58", and
    \item rendered on
    \Sexpr[stage=render]{format(Sys.time(), "\%Y-\%m-\%d at \%H:\%M:\%S")}.
  }
}

If we replace this with the translation, we display the raw code for the build and install macros. The render-time macros should work ok, though.

We could solve the build macro issue by taking the strings from a built version of the package, but that wouldn't solve the install and #ifdef issue.

The most straightforward solution might be to have the translated documentation hosted as regular Rd files in the translation package. All macros then would be processed as regular files in a way consistent with the original package. Some modifications might be needed for macros that use functions or data from the original package, but that should be manageable.

A potential problem with this implementation is that we lose all the string/section matching that was possible with the other implementation and that provided options to handle incomplete translation. I think this could still be done if we parse the translated Rd at translation time and compare section by section.

We would still like to have a good workflow to go from Rd to .po (or other format) and viceversa to use in translation software.

This is a diagram of how I think it would work:

How would dynamic pages work #25

Description

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions