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;
Date:   Wed, 23 Feb 2022 15:04:03 +0100
From:   Tomasz =?UTF-8?B?V2FybmllxYLFgm8=?= <tomasz.warniello@gmail.com>
To:     Akira Yokosawa <akiyks@gmail.com>
Cc:     Randy Dunlap <rdunlap@infradead.org>, corbet@lwn.net,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: Re: [PATCH v4 00/11] Transform documentation into POD
Message-ID: <20220223150403.350ba3d0@fuji.fritz.box>
In-Reply-To: <1abcb226-dbfd-b3d2-5453-208af7faa0c2@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>
        <1abcb226-dbfd-b3d2-5453-208af7faa0c2@gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Precedence: bulk

On Wed, 23 Feb 2022 22:16:30 +0900
Akira Yokosawa <akiyks@gmail.com> wrote:

> 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".

This is an option. But it makes things more complex. I'd rather reduce
the easy in favour of the difficult.

> >>> I don't see much point for such a non-user-facing script having nice-looking
> >>> well-structured documentation in the first place.  
> > 
> > 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?

Who is the "user"? Most of Linux users never even browse the source code.

Tomasz