[PATCH] Documentation: Chinese translation of arm64/silicon-errata.txt

[wefu]

From: Fu Wei 

This is a Chinese translated version of Documentation/arm64/silicon-errata.txt

Signed-off-by: Fu Wei 
---
 Documentation/zh_CN/arm64/silicon-errata.txt | 74 
 1 file changed, 74 insertions(+)
 create mode 100644 Documentation/zh_CN/arm64/silicon-errata.txt

diff --git a/Documentation/zh_CN/arm64/silicon-errata.txt 
b/Documentation/zh_CN/arm64/silicon-errata.txt
new file mode 100644
index 000..0584bd6
--- /dev/null
+++ b/Documentation/zh_CN/arm64/silicon-errata.txt
@@ -0,0 +1,74 @@
+Chinese translated version of Documentation/arm64/silicon-errata.txt
+
+If you have any comment or update to the content, please contact the
+original document maintainer directly.  However, if you have a problem
+communicating in English you can also ask the Chinese maintainer for
+help.  Contact the Chinese maintainer if this translation is outdated
+or if there is a problem with the translation.
+
+M: Will Deacon 
+zh_CN: Fu Wei 
+C: e835a65f7ab143acf9aee6f9a98ef1c7afd2a835
+-
+Documentation/arm64/silicon-errata.txt 的中文翻译
+
+如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
+交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
+译存在问题，请联系中文版维护者。
+
+英文版维护者： Will Deacon 
+中文版维护者： 傅炜  Fu Wei 
+中文版翻译者： 傅炜  Fu Wei 
+中文版校译者： 傅炜  Fu Wei 
+本文翻译提交时的 Git 检出点为： e835a65f7ab143acf9aee6f9a98ef1c7afd2a835
+
+以下为正文
+-
+芯片勘误和软件解决办法
+==
+
+作者: Will Deacon 
+日期: 2015年11月27日
+
+一个不幸的现实：硬件经常带有一些所谓的“错误（errata）”，致使其在
+某些特定的情况下会违背构架定义的行为。对基于 ARM 的硬件，这些错误
+大体被分为以下几类：
+
+  A 类：无可行解决方法的严重错误。
+  B 类：有可接受的解决方法的重大或严重错误。
+  C 类：在正常操作中不会显现的小错误。
+
+更多资讯，请在 infocenter.arm.com （需注册）中查阅“软件开发者勘误
+笔记”（“Software Developers Errata Notice”）文档。
+
+对于 Linux 而言，B 类错误可能需要操作系统的某些特别处理。例如，避免
+一个特殊的代码序列，或是以一种特定的方式配置处理器。在某种不太常见的
+情况下，为将 A 类错误当作 C 类处理，可能需要用类似手段。这些手段被
+统称为“软件解决办法”，且仅在少数情况需要（例如，那些需要一个在非安全
+异常级运行的解决方法 *且* 能被 Linux 触发的情况）。
+
+对于尚在讨论中的可能对未受错误影响的系统产生不利影响的软件解决办法，
+有一个相应的内核配置（Kconfig）选项被加在 “内核特性（Kernel Features）”
+- > “基于可选方案框架的 ARM 错误解决办法（ARM errata workarounds via
+the alternatives framework）"。这些选项被默认开启，若探测到受影响的CPU，
+补丁将在运行时被打入。对于对系统运行影响较小的解决办法，内核配置选项
+并不存在，且代码以一种避开错误的方式被构造（带注释为宜）。
+
+这种做法对于在任意内核源代码树中准确地判断出哪个错误已被软件方法所解决
+稍微有点麻烦，所以这个文件在 Linux 内核中作为软件解决办法的注册表，
+并将在新的软件解决办法被提交和反向移植到稳定内核时被更新。
+
+| 实现者 | 受影响的组件| 勘误编号| 内核配置|
+++-+-+-+
+| ARM| Cortex-A53  | #826319 | ARM64_ERRATUM_826319
|
+| ARM| Cortex-A53  | #827319 | ARM64_ERRATUM_827319
|
+| ARM| Cortex-A53  | #824069 | ARM64_ERRATUM_824069
|
+| ARM| Cortex-A53  | #819472 | ARM64_ERRATUM_819472
|
+| ARM| Cortex-A53  | #845719 | ARM64_ERRATUM_845719
|
+| ARM| Cortex-A53  | #843419 | ARM64_ERRATUM_843419
|
+| ARM| Cortex-A57  | #832075 | ARM64_ERRATUM_832075
|
+| ARM| Cortex-A57  | #852523 | N/A 
|
+| ARM| Cortex-A57  | #834220 | ARM64_ERRATUM_834220
|
+|| | | 
|
+| Cavium | ThunderX ITS| #22375, #24313  | CAVIUM_ERRATUM_22375
|
+| Cavium | ThunderX GICv3  | #23154  | CAVIUM_ERRATUM_23154
|
-- 
2.5.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Kernel docs: muddying the waters a bit

[Jonathan Corbet]

So I fear you all are going to hate me for this...

Asciidoc is a credible solution to the formatted documentation problem,
but it's not the only such; I'd like to be sure that we pick the right
one.  I worry that asciidoc seems to be aimed mostly at small documents,
and that the project itself seems a little lifeless - it's not a good
sign when your main page's link to the repository has been dead for a long
time.  (Asciidoctor seems more active, with the Github folks behind it,
but that means bringing Ruby into the picture).

An alternative we haven't really looked at yet is ReStructuredText (or
"RST") and the Sphinx system (sphinx-doc.org) built on top of it.  RST is
YA simple markup scheme, remarkably similar to Markdown or Asciidoc;
Sphinx is a fairly sophisticated documentation system that uses RST.

I spent a few hours reworking the asciidoc patches to do RST instead, then
built a few template files' worth of docs.  The result can be seen at:

http://static.lwn.net/kerneldoc/

It's very much a POC (however you might want to define the term), there's
lots of glitches, I chose a theme pretty much at random, etc.  But it
shows that it can be done.

Like asciidoc, Sphinx is Python-based, so it adds little to the toolchain
requirements there.  It produces integrated, multi-file HTML natively,
with a TOC, an index, cross-file cross references, and more.  It can make
things like function indexes.  It claims output in epub, docbook, and man
(I've not yet messed with those).  The path to PDF is via latex; clearly
the docbook path could be used too.

I used my same docproc hack to extract the comments here, mostly because I
had it at hand.  We could go with Jani's separate-file approach if we
wanted.  There's also a tool out there (called "breathe") that's meant to
turn doxygen-style comments into RST; I haven't had a chance to mess with
it.  We *could* also write an extension to pull the comments directly in
Sphinx if there were a compelling reason to do so.

If anybody's curious, the work done to get this far is in:

git://git.lwn.net/linux.git doc/sphinx

but it looks suspiciously like the previous asciidoc patches, and, in any
case, it would have to be thrown out, publicly disowned, and replaced
before going any further with this, should that be what we decide to do.

So can we discuss?  I'm not saying we have to use Sphinx, but, should we
choose not to, we should do so with open eyes and good reasons for the
course we do take.  What do you all think?

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Kernel docs: muddying the waters a bit

[Keith Packard]

Jonathan Corbet  writes:

> Asciidoc is a credible solution to the formatted documentation problem,
> but it's not the only such; I'd like to be sure that we pick the right
> one.  I worry that asciidoc seems to be aimed mostly at small documents,
> and that the project itself seems a little lifeless - it's not a good
> sign when your main page's link to the repository has been dead for a long
> time.  (Asciidoctor seems more active, with the Github folks behind it,
> but that means bringing Ruby into the picture).

I was surprised when one of the asciidoctor developers said that
asciidoc itself was 'in maintenance mode for existing users'. I've tried
asciidoctor but never got it to the point where I was happy with the
results. Having two tools using the same nominal format doesn't seem
like a great idea to me.

It's also clear from my hacking in asciidoc that docbook is the expected
target for that tool. I've managed to make direct HTML output usable,
but LaTeX doesn't work at all. Something which focuses on direct HTML
(and ePub) output would be pretty nice.

> An alternative we haven't really looked at yet is ReStructuredText (or
> "RST") and the Sphinx system (sphinx-doc.org) built on top of it.  RST is
> YA simple markup scheme, remarkably similar to Markdown or Asciidoc;
> Sphinx is a fairly sophisticated documentation system that uses RST.

I've installed debian's python3-sphinx package; it looks like it doesn't
have a huge dependency chain below it, which is a nice change.

I translated a fairly long document from asciidoc to rst using pandoc by
using the docbook output from asciidoc -- pandoc doesn't have a native
asciidoc reader, only a writer. The result didn't totally suck, although
I haven't messed with fixing the css or using a different theme at all.

http://keithp.com/~keithp/altusmetrum-sphinx/altusmetrum.html

I installed the sphinxcontrib.fulltoc extension so that the whole TOC
was visible from each section; this made navigating a lot easier. Having
search included (if you have javascript) seems like a nice feature.

> Like asciidoc, Sphinx is Python-based, so it adds little to the toolchain
> requirements there.

Having functional native latex output means that even PDF generation is
lighterweight though.

> It produces integrated, multi-file HTML natively,
> with a TOC, an index, cross-file cross references, and more.  It can make
> things like function indexes.  It claims output in epub, docbook, and man
> (I've not yet messed with those).  The path to PDF is via latex; clearly
> the docbook path could be used too.

I've tried epub and latex backends; epub seems just fine (it's just
html, after all). LaTeX works, and generates functional PDF, but I'm
going to have to spend a bunch of time making it looks nice.

http://keithp.com/~keithp/altusmetrum-sphinx/AltusMetrum.pdf

> So can we discuss?  I'm not saying we have to use Sphinx, but, should we
> choose not to, we should do so with open eyes and good reasons for the
> course we do take.  What do you all think?

Having spent the afternoon playing with it, I'm definitely
impressed. I've spent a ton of time getting asciidoc to generate html
and pdf that I can tolerate; far too much of that involved hacking XML
files related to the docbook backend.

Pros

 * Credible HTML output without docbook

 * Credible PDF output without docbook.

 * Constructs a unified set of documents across
   multiple files.

 * Written in Python (2 or 3)

 * PanDoc already supports rst for both input and output. So, if we get
   bored with RST, we've got a way out.

Cons

 * Table formatting doesn't seem as sophisticated as asciidoc

Questions

 * Conditional text appears to be harder to manage (I haven't managed to
   make it work at all).

 * Takes over a directory making building more than one
   document in a directory hard/impossible? The config file must be
   named 'conf.py'?
   
-- 
-keith


signature.asc
Description: PGP signature

[PATCH] Documentation/ko_KR: update maintainer information

[SeongJae Park]

Maintainer informations of Documentation/ko_KR is outdated. This commit
update the informations to the latest ones.

Signed-off-by: SeongJae Park 
---
 Documentation/ko_KR/HOWTO   | 4 ++--
 Documentation/ko_KR/stable_api_nonsense.txt | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/ko_KR/HOWTO b/Documentation/ko_KR/HOWTO
index 1aef53e..5a81b39 100644
--- a/Documentation/ko_KR/HOWTO
+++ b/Documentation/ko_KR/HOWTO
@@ -1,6 +1,6 @@
 NOTE:
 This is a version of Documentation/HOWTO translated into korean
-This document is maintained by minchan Kim 
+This document is maintained by Minchan Kim 
 If you find any difference between this document and the original file or
 a problem with the translation, please contact the maintainer of this file.
 
@@ -14,7 +14,7 @@ try to update the original English file first.
 Documentation/HOWTO
 의 한글 번역입니다.
 
-역자： 김민찬 
+역자： 김민찬 
 감수： 이제이미 
 ==
 
diff --git a/Documentation/ko_KR/stable_api_nonsense.txt 
b/Documentation/ko_KR/stable_api_nonsense.txt
index 51f85ad..3ba10b1 100644
--- a/Documentation/ko_KR/stable_api_nonsense.txt
+++ b/Documentation/ko_KR/stable_api_nonsense.txt
@@ -1,7 +1,7 @@
 NOTE:
 This is a version of Documentation/stable_api_nonsense.txt translated
 into korean
-This document is maintained by barrios 
+This document is maintained by Minchan Kim 
 If you find any difference between this document and the original file or
 a problem with the translation, please contact the maintainer of this file.
 
@@ -15,7 +15,7 @@ try to update the original English file first.
 Documentation/stable_api_nonsense.txt
 의 한글 번역입니다.
 
-역자： 김민찬 
+역자： 김민찬 
 감수： 이제이미 
 ==
 
-- 
1.9.1

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html