Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <1abcb226-dbfd-b3d2-5453-208af7faa0c2@gmail.com>
Date:   Wed, 23 Feb 2022 22:16:30 +0900
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101
 Thunderbird/91.5.0
Subject: Re: [PATCH v4 00/11] Transform documentation into POD
Content-Language: en-US
To:     =?UTF-8?B?VG9tYXN6IFdhcm5pZcWCxYJv?= <tomasz.warniello@gmail.com>
Cc:     Randy Dunlap <rdunlap@infradead.org>, corbet@lwn.net,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        Akira Yokosawa <akiyks@gmail.com>
References: <525f3696-91f4-5a4a-c9ef-24758ccaa2bb@infradead.org>
 <ff98f455-0221-7ff0-08ed-8dea9f08694b@gmail.com>
 <939ef119-8a84-9206-bd7c-cfd215bb0200@gmail.com>
 <20220223135548.27babd85@fuji.fritz.box>
From:   Akira Yokosawa <akiyks@gmail.com>
In-Reply-To: <20220223135548.27babd85@fuji.fritz.box>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
Precedence: bulk

On Wed, 23 Feb 2022 13:55:48 +0100,
Tomasz Warnie=C5=82=C5=82o wrote:
> Hi Akira,
>=20
> Take a look at `man perl` and you will find a synopsis also.

When I do "man perl", I want to see a detailed explanation, and
somewhat hard-to-parse synopsis is ok.

I'm saying that I don't like to see such a thing when I type
"./scripts/kerneldoc -h".  I expect a hint to recall which option I
should use.  I don't want to scroll back the terminal.

It would be nice if the verbose man page can be shown by
"./scripts/kerneldoc -v -h" or "perldoc -F ./scripts/kerneldoc".

>                                                              It's simpl=
y
> better in depicting grammar relations than a flat switch list. Especial=
ly
> when the grammar gets complex. I dislike it also. And I don't think it
> looks good. Rather creepy and overwhelming.
>=20
>>> I don't see much point for such a non-user-facing script having nice-=
looking
>>> well-structured documentation in the first place.
>=20
> You're touching the very essence of kernel-doc here. What and who is it=
 for?
> Not just the script - all of it.

Sorry, I have no idea what I am being asked.
Could you rephrase above for a non-native speaker of English, please?

        Thanks, Akira

>=20
> Regards,
>=20
> Tomasz