Re: [RFC PATCH 06/11] docs: process: remove outdated submitting-drivers.rst
From: Bagas Sanjaya
Date: Tue Jun 28 2022 - 02:40:24 EST
On 6/28/22 12:00, Lukas Bulwahn wrote:
> On Tue, Jun 28, 2022 at 3:21 AM Bagas Sanjaya <bagasdotme@xxxxxxxxx> 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