openSUSE / openSUSE/doc-kit

dm:translation tags in non-modifiable files..?

Open
#16 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

cat-bug scope-tool
Dominant language
Shell
Stars
5
Forks
3
Avg merge
2d 15h
Merged PRs (30d)
1

Description

@tbazant has the issue that he needs dm:translation tags in the intro documents for SES.
As translation tags need to be filled with either "yes" or "no" depending on the context, having translation tags in a file that is not supposed to be modified downstream is a conceptual issue. I am not 100% sure that translation tags really need to be part of the intro though ... would it not be enough to have them in the MAIN? Translation tags are file-based, so yes, they need to be in each individual file.

Specifically for the intro though, translation tags can just always be set to "yes" currently, because the intro pretty much always needs to be translated (and if none of the documents from the repo are translated, nothing will evaluate those tags, so what they are set to does not matter in that case anyway).

Zooming out and looking at the general issue though, this would only be properly solvable if we could mark up sections that can be changed in some way.

...
<!-- dk-ignore-start -->
<dm:translation>yes</dm:translation>
<!-- dk-ignore-end -->
...

But of course since doc-kit is supposed to be document type-agnostic, you'd have to make sure that whatever comment markup is needed for the file type is supported somehow. I don't know where to start, except maybe by defining that *.xml means that <!--these--> are comments and *.js means that //these\n are comments and ... where to stop. Seems like an endless hole.

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 reviewing how doc-kit handles file-based dm:translation tags in the intro documents and MAIN. Consider the proposed dk-ignore sections and the comment syntaxes mentioned for *.xml and *.js. Done would require a defined, document-type-agnostic way to mark sections that may be changed downstream.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.