linux-kernel - Re: [RFC PATCH 06/11] docs: process: remove outdated submitting-drivers.rst

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <e8605c72-7807-ee03-83eb-6744bb3dbd47@gmail.com>
Date:   Tue, 28 Jun 2022 13:40:09 +0700
From:   Bagas Sanjaya <bagasdotme@...il.com>
To:     Lukas Bulwahn <lukas.bulwahn@...il.com>
Cc:     Jonathan Corbet <corbet@....net>,
        Federico Vaga <federico.vaga@...a.pv.it>,
        Alex Shi <alexs@...nel.org>,
        Yanteng Si <siyanteng@...ngson.cn>,
        Hu Haowen <src.res@...il.cn>,
        "open list:DOCUMENTATION" <linux-doc@...r.kernel.org>,
        linux-doc-tw-discuss@...ts.sourceforge.net,
        Jean Delvare <jdelvare@...e.com>,
        Guenter Roeck <linux@...ck-us.net>,
        linux-hwmon@...r.kernel.org,
        kernel-janitors <kernel-janitors@...r.kernel.org>,
        Linux Kernel Mailing List <linux-kernel@...r.kernel.org>
Subject: Re: [RFC PATCH 06/11] docs: process: remove outdated
 submitting-drivers.rst

On 6/28/22 12:00, Lukas Bulwahn wrote:
> On Tue, Jun 28, 2022 at 3:21 AM Bagas Sanjaya <bagasdotme@...il.com> wrote:
>>
>> On 6/27/22 22:18, Lukas Bulwahn wrote:
>>>  There are numerous sources of information on Linux kernel development and
>>>  related topics.  First among those will always be the Documentation
>>> -directory found in the kernel source distribution.  The top-level :ref:`process/howto.rst <process_howto>`
>>> -file is an important starting point; :ref:`process/submitting-patches.rst <submittingpatches>`
>>> -and :ref:`process/submitting-drivers.rst  <submittingdrivers>`
>>> -are also something which all kernel developers should
>>> -read.  Many internal kernel APIs are documented using the kerneldoc
>>> -mechanism; "make htmldocs" or "make pdfdocs" can be used to generate those
>>> -documents in HTML or PDF format (though the version of TeX shipped by some
>>> -distributions runs into internal limits and fails to process the documents
>>> -properly).
>>> +directory found in the kernel source distribution.  Start with the
>>> +top-level :ref:`process/howto.rst <process_howto>`; also read
>>> +:ref:`process/submitting-patches.rst <submittingpatches>`. Many internal
>>> +kernel APIs are documented using the kerneldoc mechanism; "make htmldocs"
>>> +or "make pdfdocs" can be used to generate those documents in HTML or PDF
>>> +format (though the version of TeX shipped by some distributions runs into
>>> +internal limits and fails to process the documents properly).
>>>
>>
>> Did you mean "beware that TeX distribution version as shipped by distributions
>> may fail to properly generate the documents"? I have never tried pdfdocs,
>> since the dependency requirement can be huge (hundreds of MB needed to
>> download packages), so I can't tell whether the phrase is relevant.
>>
> 
> I only touched this sentence with 'make pdfdocs' above to reformat the
> paragraph after deleting the reference to submitting-drivers. Maybe
> the statement on make pdfdocs is outdated already or we should refer
> to the documentation build page instead?
> 

I think we can say "The kernel documentation subsystem (kernel-doc)
uses Sphinx. Refer to Documentation/doc-guide/sphinx.rst for more
information.", at least.

-- 
An old man doll... just what I always wanted! - Clara