Correct and modernize the wolfProvider manual against current wolfProvider sources - #280
Correct and modernize the wolfProvider manual against current wolfProvider sources#280aidangarske wants to merge 4 commits into
Conversation
yosuke-wolfssl
left a comment
There was a problem hiding this comment.
Reviewing the src-ja/ half, against the English in this same PR and against the PR
description.
The new Japanese reads well — chapter 7's replace-default section is fluent and faithful.
The issue is coverage: three chapters the PR description claims to have fixed did not get
translated, and the rest was translated from an intermediate draft, so parts of the JA
manual now contradict the EN manual beside it.
1. Claimed in the PR description, but not present in src-ja/
| Chapter | PR description says | src-ja/ actually has |
|---|---|---|
chapter05.md |
"corrects every enum to WP_LOG_LEVEL_* / WP_LOG_COMP_*, adds DEBUG/TRACE, fixes the default mask, documents the compile-time filters" |
Only the quote characters changed. Still wolfProvider_LogType, WP_LOG_ERROR, WP_LOG_COMPONENTS_ALL, and PROVIDER_ctrl_cmd() / 「エンジン制御コマンド」 in 6 places |
chapter08.md |
"corrects the entry points, the four provider params, the capability set, and the teardown behavior" | Source-file table only; all five ### subsections EN has (wolfprov_teardown … wolfprov_query) are missing |
chapter11.md |
"notes validated FIPS/FIPS-Ready reject PQC/LMS" | That paragraph is not in the JA chapter |
Two knock-on effects worth noting:
chapter05.mdis now internally inconsistent — the typedef was renamed to
wolfProv_Logging_cb, but the surrounding text still registers it via the
"set_logging_cb"エンジン制御コマンド, and the EN no longer describes it that way.chapter08.mdkeeps 「OSSLパラメータに関する注意(後述):」, a forward reference to
sections that exist only in the EN file.
2. Translation fidelity
chapter04.md — the JA is stronger than the EN in a FIPS context, and drops EN's
qualifiers:
- 「完全なFIPS適合を実現するには」 for "For broader FIPS coverage" → suggest
「FIPS適合の範囲を広げるため」 - 「…フォールバックすることを防ぎます」 for "reduces the risk of … silently falling back"
→ suggest 「…リスクを低減します」 - EN says replace-default needs both
--enable-replace-defaultand an OpenSSL
built with wolfProvider's provider replacement, and points at
scripts/build-wolfprovider.sh --replace-default. The JA says only 「置き換え用デフォルト
モード (--enable-replace-default) でビルドされます」, so a JA reader will think the
configure flag alone is enough. - EN's closing caveat 「これ自体がシステム全体のFIPS適合を保証するものではありません」 is
dropped, and the JA still carries the old third paragraph
(「FIPSで検証されたアルゴリズム、モード、および鍵サイズ…のみが含まれます」) that the EN
softened in this PR.
chapter03.md
- Line 342 says
WP_HAVE_SEED; the EN table saysWP_HAVE_SEED_SRC. - The EN deleted
## Building on WinCE. The JA kept 「## WinCE上でのビルド」 (line 207) and
also added the new 「## Windows上でのビルド (Visual Studio)」 (line 240), so the JA
manual carries two incompatible Windows sections. - Not carried over: the
user_settings.hremoval from the package layout, theIDE/
description, the reworked OpenSSL build block and "latest patch release" note,
--enable-sha3/--enable-shake256, the--enable-spquoting fix, the expanded
WOLFPROVIDER_USER_SETTINGSrow, and theLD_LIBRARY_PATHfix (JA line 173 still has
the old/usr/local/ssl:form). - The build examples drifted: EN
openssl-3.5.4, JAopenssl-3.5.0.
chapter06.md — the platform lists differ. JA: Linux / macOS / Windows / Windows CE.
EN: Linux / macOS / Windows / Android / Apple platforms. The JA also lacks EN's new
threading caveat about the logging setters and FIPS-check state being unsynchronised
process globals.
3. JA translated from the pre-revision EN
Commit 2 translated the English, commit 3 revised the English without re-syncing. Two of
these now say the opposite of the EN:
chapter11.mdLMS rationale — JA keeps 「OpenSSL 3.6のプロバイダーABIがLMSを検証専用として
定義しているため」, which commit 3 replaced with the key-type-contract + design-choice
framing.chapter11.mdprovider.conf— JA: 「関係のない操作が…選択されないことを保証するものでは
ありません」. EN now says onlylibwolfprovis activated, so unsupported operations fail
rather than falling back.chapter09.md— JA says FIPS is additionally verified 「Jenkinsパイプライン」; EN now says
dedicated FIPS / FIPS-Ready GitHub Actions workflows.chapter11.mdalso misses theOPENSSL_TAG=openssl-3.6.2build commands, the "not
3.6.0" note, and themake checkcorrection.
4. Minor
chapter07.mduses*…*italics on Japanese text in 5 places. The JA PDF is built with
CJKmainfont="Noto Sans CJK JP", which has no italic face — use**…**or 「…」.chapter08.mdmixes 「プロバイダー」 and 「プロバイダ」 within the same table (new rows vs
existing rows). 「プロバイダ」may be natural one.chapter11.mdline 252: 「selectionの処理」 — untranslated word; at least 「selectionの処理」.
Its code comments are also left in English, whilechapter03.mdtranslates them.
Suggestion
Worth running make pdf html with DOC_LANG=JA before merge too — chapter11.md is new
on the JA side and the Makefile change moves it into the JA SOURCES list.
yosuke-wolfssl
left a comment
There was a problem hiding this comment.
Looks good to me.
Let's give @padelsbach a chance to review this.
wolfProvider manual general updates