linux-kernel - Re: [PATCH v2] docs: trace: Refactor index documentation

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] [day] [month] [year] [list]

Message-ID: <7dc0e44c-32ae-402c-a89e-aa0824770bcd@gmail.com>
Date: Fri, 14 Feb 2025 00:42:39 +0530
From: Purva Yeshi <purvayeshi550@...il.com>
To: Steven Rostedt <rostedt@...dmis.org>
Cc: mhiramat@...nel.org, corbet@....net, skhan@...uxfoundation.org,
 mathieu.desnoyers@...icios.com, linux-kernel@...r.kernel.org,
 linux-trace-kernel@...r.kernel.org, linux-doc@...r.kernel.org
Subject: Re: [PATCH v2] docs: trace: Refactor index documentation

On 13/02/25 22:17, Steven Rostedt wrote:
> On Thu, 13 Feb 2025 17:26:21 +0530
> Purva Yeshi <purvayeshi550@...il.com> wrote:
> 
>>>> +Tracing in the Linux kernel is a powerful mechanism that allows
>>>> +developers and system administrators to analyze and debug system
>>>> +behavior. This guide provides documentation on various tracing
>>>> +frameworks and tools available in the Linux kernel.
>>>> +
>>>> +Introduction to Tracing
>>>> +-----------------------
>>>> +
>>>> +This section provides an overview of Linux tracing mechanisms
>>>> +and debugging approaches.
>>>>    
>>>>    .. toctree::
>>>> -   :maxdepth: 2
>>>> +   :maxdepth: 1
>>>
>>> I don't really know what the maxdepth gives here, but there was no mention
>>> in the change log why it had to be converted from 2 to 1.
>>>    
>>
>> I changed :maxdepth: from 2 to 1 to simplify the table of contents,
>> keeping only document titles instead of also including second-level
>> section headings. The intent was to improve readability and navigation.
>>
>> Additionally, I referred to commit '270beb5b2aae', as suggested by
>> Jonathan Corbet in the v1 patch, to align the documentation structure
>> accordingly.
>>
>> I'll update the commit message in the next revision to explicitly
>> mention this change.
>>
> 
> Can you make that a separate patch. A commit should do only one thing and
> that change isn't necessary to be part of the rest of the changes.

Okay, I’ll separate this change into a new patch.

> 
>>>>    
>>>> -   ftrace-design
>>>> +   debugging
>>>> +   tracepoints
>>>>       tracepoint-analysis
>>>> +
> 
>>>> +
>>>> +Hardware and Performance Tracing
>>>> +--------------------------------
>>>> +
>>>> +This section covers tracing features that monitor hardware
>>>> +interactions and system performance.
>>>> +
>>>> +.. toctree::
>>>> +   :maxdepth: 1
>>>> +
>>>>       intel_th
>>>    
>>>>       ring-buffer-design
>>>
>>> The ring-buffer-design should be in "Core Tracing Frameworks".
>>>    
>>
>> I'll move 'ring-buffer-design' to the Core Tracing Frameworks section.
>>
>>>>       ring-buffer-map
>>>
>>> This describes how to map the ring buffer in user space. Maybe it should go
>>> at the "Introduction" section?
>>>
>>>    
>>
>> For ring-buffer-map, placing it in the Introduction section could
>> provide early context, but since it is more implementation-specific, it
>> might fit better under Core Tracing Frameworks alongside
>> ring-buffer-design. Would that placement works?
> 
> 
> But it's not kernel implementation. It describes how to use it in user
> space. That is, it's not part of the tracing framework.
> 
> -- Steve

Thanks for the clarification. I’ll move it to the Introduction section 
in the next revision.