Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::3:7 as permitted sender) client-ip=2620:137:e000::3:7;
Message-ID: <77b25d0b-ceb4-4589-bf40-ff464e2a6b7f@vt.edu>
Date:   Sun, 10 Dec 2023 19:58:19 -0600
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
Subject: Re: [PATCH 1/1 RESEND] docs: Include simplified link titles in main
 page's index
Content-Language: en-US
To:     Randy Dunlap <rdunlap@infradead.org>,
        Jonathan Corbet <corbet@lwn.net>
Cc:     Miguel Ojeda <miguel.ojeda.sandonis@gmail.com>,
        alex.gaynor@gmail.com, wedsonaf@gmail.com, boqun.feng@gmail.com,
        gary@garyguo.net, bjorn3_gh@protonmail.com, benno.lossin@proton.me,
        a.hindborg@samsung.com, aliceryhl@google.com,
        "linux-doc@vger.kernel.org" <linux-doc@vger.kernel.org>,
        Linux Kernel Mailing List <linux-kernel@vger.kernel.org>
References: <58e78693-82d1-451d-a546-51fb64ef6eb5@vt.edu>
 <dcab1e08-c054-441b-8d4e-f46e2f22605c@vt.edu>
 <9b52c145-7466-4e81-a911-25f472c2a2ea@infradead.org>
From:   Carlos Bilbao <bilbao@vt.edu>
In-Reply-To: <9b52c145-7466-4e81-a911-25f472c2a2ea@infradead.org>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk


On 12/10/23 7:41 PM, Randy Dunlap wrote:
> Hi Carlos,
> 
> On 12/10/23 17:20, Carlos Bilbao wrote:
>> Include simplified link titles in the main page's documentation index to
>> enhance website's readability and UX. Update the text that directs users to
>> various documents without changing the actual titles chosen by the authors.
>>
>> Signed-off-by: Carlos Bilbao <bilbao@vt.edu>
>> ---
>>  Documentation/index.rst | 50 ++++++++++++++++++++---------------------
>>  1 file changed, 25 insertions(+), 25 deletions(-)
>>
>> diff --git a/Documentation/index.rst b/Documentation/index.rst
>> index 9dfdc826618c..be395d0a4318 100644
>> --- a/Documentation/index.rst
>> +++ b/Documentation/index.rst
>> @@ -22,10 +22,10 @@ community and getting your work upstream.
>>  .. toctree::
>>     :maxdepth: 1
>>  
>> -   process/development-process
>> -   process/submitting-patches
>> +   Development process <process/development-process>
>> +   Submitting patches <process/submitting-patches>
>>     Code of conduct <process/code-of-conduct>
>> -   maintainer/index
>> +   Maintainer handbook <maintainer/index>
>>     All development-process docs <process/index>
>>  
>>  
>> @@ -38,10 +38,10 @@ kernel.
>>  .. toctree::
>>     :maxdepth: 1
>>  
>> -   core-api/index
>> -   driver-api/index
>> -   subsystem-apis
>> -   Locking in the kernel <locking/index>
>> +   Core API <core-api/index>
>> +   Driver implementation API <driver-api/index>
>> +   Subsystems <subsystem-apis>
>> +   Locking <locking/index>
>>  
>>  Development tools and processes
>>  ===============================
>> @@ -51,15 +51,15 @@ Various other manuals with useful information for all kernel developers.
>>  .. toctree::
>>     :maxdepth: 1
>>  
>> -   process/license-rules
>> -   doc-guide/index
>> -   dev-tools/index
>> -   dev-tools/testing-overview
>> -   kernel-hacking/index
>> -   trace/index
>> -   fault-injection/index
>> -   livepatch/index
>> -   rust/index
>> +   Licensing rules <process/license-rules>
>> +   Writing documentation <doc-guide/index>
>> +   Development tools <dev-tools/index>
>> +   Testing <dev-tools/testing-overview>
>> +   Hacking <kernel-hacking/index>
>> +   Tracing <trace/index>
>> +   Fault injection <fault-injection/index>
>> +   Livepatching <livepatch/index>
>> +   Rust <rust/index>
>>  
>>  
>>  User-oriented documentation
>> @@ -72,11 +72,11 @@ developers seeking information on the kernel's user-space APIs.
>>  .. toctree::
>>     :maxdepth: 1
>>  
>> -   admin-guide/index
>> -   The kernel build system <bailed/index>
> 
> Where do the subdir names "bailed" above and "bugled" below come from?


No clue how that happened. Thanks for catching it, Randy.


> 
>> -   admin-guide/reporting-issues.rst
>> +   Administration <admin-guide/index>
>> +   Build system <bugled/index>
> 
>                     ^^^^^^
> 
> 
> Thanks.
> 
>> +   Reporting issues <admin-guide/reporting-issues.rst>
>>     User-space tools <tools/index>
>> -   userspace-api/index
>> +   User-space API <userspace-api/index>
>>  
>>  See also: the `Linux man pages <https://www.kernel.org/doc/man-pages/>`_,
>>  which are kept separately from the kernel's own documentation.
>> @@ -89,8 +89,8 @@ platform firmwares.
>>  .. toctree::
>>     :maxdepth: 1
>>  
>> -   firmware-guide/index
>> -   devicetree/index
>> +   Firmware <firmware-guide/index>
>> +   Firmware and Devicetree <devicetree/index>
>>  
>>  
>>  Architecture-specific documentation
>> @@ -99,7 +99,7 @@ Architecture-specific documentation
>>  .. toctree::
>>     :maxdepth: 2
>>  
>> -   arch/index
>> +   CPU Architectures <arch/index>
>>  
>>  
>>  Other documentation
>> @@ -112,7 +112,7 @@ to ReStructured Text format, or are simply too old.
>>  .. toctree::
>>     :maxdepth: 1
>>  
>> -   staging/index
>> +   Unsorted documentation <staging/index>
>>  
>>  
>>  Translations
>> @@ -121,7 +121,7 @@ Translations
>>  .. toctree::
>>     :maxdepth: 2
>>  
>> -   translations/index
>> +   Translations <translations/index>
>>  
>>  Indices and tables
>>  ==================
> 

Best,
Carlos