Re: [PATCH v2] docs/zh_CN: add the translation of kbuild/gcc-plugins.rst

[YanTeng Si <si.yanteng@linux.dev>]

Hi Akira,


在 2024/9/2 11:21, Akira Yokosawa 写道:
> On Mon, 2 Sep 2024 09:32:08 +0800, YanTeng Si wrote:
> ...
>> 在 2024/9/1 14:03, Akira Yokosawa 写道:
>>> Hi,
>>>
>>> I'm not Alex, but let me chime in.
>>>
>>> On Sat, 31 Aug 2024 17:34:11 +0800, Dongliang Mu wrote:
>>>> On 2024/8/31 12:11, Alex Shi wrote:
>>>>> On 8/31/24 11:48 AM, Dongliang Mu wrote:
>>>>>> +目的
>>>>>> +=======
>>>>>> +
>>>>> there are still a lots of sign incorrect. Please be sure everything looks fine in a web browser after you 'make htmldocs'
>>>> What do you mean by "sign incorrect"? I check the html rendering in the
>>>> vscode. It seems fine to me.
>>> You are right.  There is nothing wrong as far as the reST specification
>>> is concerned.
>>>
>>> Quote from https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#sections
>>> (emphasis by me):
>>>
>>>       An underline/overline is a single repeated punctuation character that
>>>       begins in column 1 and forms a line extending *at least* as far as the
>>>       right edge of the title text.
>> Yes, I guess we should also think about the reading experience
>> of readers who use vim to read kernel documentation.
>>
>> Because Chinese characters are already very neat, sentences
>> and paragraphs should also be neat, otherwise the reading
>> experience will be poor.
>>
>> Let's take a look at some examples: (copy to vim)
>>
>> 整齐
>> ====
>> 整齐
>> ====
>> 整齐
>> ====
>> Great!
>>
>>
>> And
>>
>>
>> 不整齐
>> ============
>> 不整齐
>> =========
>> 不整齐
>> ================
>> I think this is a bit difficult to read. What do you think?
>>
> So you are talking about your personal preference, not about what is
> technically correct or wrong.
In a sense, yes.
> And you are exaggerating by collecting them in one place.
>
> If they appeared springily as title adornments, they would not bother
> me at all.
Sorry, my example is not good enough.


>
> At times, especially with a very short title, I'd like to have a way
> longer adornment line to make it stand out such as:
>
>    整齐
>    ------------
Okay, I'm not a stubborn person, I just care about the feelings of most 
people.

If you open any document, you will find that the author is trying to keep
everything as neat as possible.

let's vim kbuild/gcc-plugins.rst

---

=========================
GCC plugin infrastructure
=========================


Introduction
============

GCC plugins are loadable modules that provide extra features to the
compiler [1]_. They are useful for runtime instrumentation and static 
analysis.
We can analyse, change and add further code during compilation via
callbacks [2]_, GIMPLE [3]_, IPA [4]_ and RTL passes [5]_.

...


Purpose
=======

GCC plugins are designed to provide a place to experiment with potential
compiler features that are neither in GCC nor Clang upstream. Once
their utility is proven, the goal is to upstream the feature into GCC
(and Clang), and then to finally remove them from the kernel once the
feature is available in all supported versions of GCC.

...

After a feature is available in upstream GCC, the plugin will be made
unbuildable for the corresponding GCC version (and later). Once all
kernel-supported versions of GCC provide the feature, the plugin will
be removed from the kernel.


Files
=====

**$(src)/scripts/gcc-plugins**

....
     These headers automatically generate the registration structures for
     GIMPLE, SIMPLE_IPA, IPA and RTL passes.
     They should be preferred to creating the structures by hand.


Usage
=====

You must install the gcc plugin headers for your gcc version,
e.g., on Ubuntu for gcc-10::

.....

or just run the kernel make and compile the whole kernel with
the cyclomatic complexity GCC plugin.


4. How to add a new GCC plugin
==============================

The GCC plugins are in scripts/gcc-plugins/. You need to put plugin 
source files
right under scripts/gcc-plugins/. Creating subdirectories is not supported.
It must be added to scripts/gcc-plugins/Makefile, 
scripts/Makefile.gcc-plugins
and a relevant Kconfig file.

---

We can see that all the underline are aligned with the title,  Even each 
row is
as long as possible. I think most readers are also accustomed to alignment.


In addition, we are only translating from English to Chinese, and the
translation should be as consistent as possible with the original
document to facilitate readers/developers to compare the original
document. Because our translations may not be accurate and updates
may not be timely, keeping them consistent with English will make
everything simpler.
>
> Of course I don't have a say on personal preferences and I think
> maybe I was stupid making a *technical* comment here in the first
> place. :-/
Don't say that, your comment makes this matter clearer and greatly
reduces the difficulty of discussion. I understand your feelings very
well, as I replied to your first comment by saying 'yes', and then I
elaborated on my point of view, although not entirely perfect.


Thanks,
Yanteng
>
>          Akira.
>
>>
>> Thanks,
>> Yanteng
>>> HTH, Akira
>>>
>>>> Dongliang Mu