lkml.org 
[lkml]   [2022]   [Jun]   [28]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
From
Date
SubjectRe: [RFC PATCH 06/11] docs: process: remove outdated submitting-drivers.rst
On Tue, Jun 28, 2022 at 3:21 AM Bagas Sanjaya <bagasdotme@gmail.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?

> > - :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` and :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>`
> > - These files describe in explicit detail how to successfully create
> > + :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
> > + This file describes in explicit detail how to successfully create
> > and send a patch, including (but not limited to):
> >
>
> Maybe "This document" instead of file?
>

Either 'this file' or 'this document' fits for me. I have just been
conservative here: It was 'These files' (written by the original
author) and after deleting the second reference, it is just 'this
file'.

If there is no strong opinion, I would leave this as-is.

> > @@ -12,9 +12,8 @@ This document contains a large number of suggestions in a relatively terse
> > format. For detailed information on how the kernel development process
> > works, see Documentation/process/development-process.rst. Also, read
> > Documentation/process/submit-checklist.rst
> > -for a list of items to check before submitting code. If you are submitting
> > -a driver, also read Documentation/process/submitting-drivers.rst; for device
> > -tree binding patches, read
> > +for a list of items to check before submitting code.
> > +For device tree binding patches, read
> > Documentation/devicetree/bindings/submitting-patches.rst.
>
> The hunk above is OK.
>
> --
> An old man doll... just what I always wanted! - Clara

\
 
 \ /
  Last update: 2022-06-28 07:02    [W:1.233 / U:0.108 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site