linux-kernel - Re: [PATCH] docs: remove tree links from the main index

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]

Date:   Sat, 22 Jul 2023 05:21:56 +0300
From:   Costa Shulyupin <costa.shul@...hat.com>
To:     Jonathan Corbet <corbet@....net>
Cc:     "open list:DOCUMENTATION" <linux-doc@...r.kernel.org>,
        open list <linux-kernel@...r.kernel.org>
Subject: Re: [PATCH] docs: remove tree links from the main index

The left column "Contents" is overloaded and hard to use. The value of
this patch is to make it more usable.

Sections of the main page are not displayed after patch "docs: Add
more information to the HTML sidebar". So sections don't work now and
should be fixed too.

I have in mind to reorganize the main page so the left column
"Contents" becomes usable.

Thanks
Costa

On Fri, 21 Jul 2023 at 22:56, Jonathan Corbet <corbet@....net> wrote:
>
> Costa Shulyupin <costa.shul@...hat.com> writes:
>
> > and leave only their neighbor subsystem-apis
> >
> > because these links are already listed under
> > section "Core subsystems" of Documentation/subsystem-apis.rst:
> >
> >     Core subsystems
> >     ---------------
> >
> >     .. toctree::
> >        :maxdepth: 1
> >
> >        core-api/index
> >        driver-api/index
> >        mm/index
> >        power/index
> >        scheduler/index
> >        timers/index
> >        locking/index
> >
> > Reference:
> > - https://www.kernel.org/doc/html/next/subsystem-apis.html#core-subsystems
> >
> > Motivation:
> > - make the documentation more organized
> > - increase consistency, observability and maintainability
> > - improve balance of ToC tree by reducing overly populated lists
> > - avoid duplicate parallel links
> > - escape tangling of links
> > - intention to fit the main index into one page
> >
> > Signed-off-by: Costa Shulyupin <costa.shul@...hat.com>
> > ---
> >  Documentation/index.rst | 3 ---
> >  1 file changed, 3 deletions(-)
> >
> > diff --git a/Documentation/index.rst b/Documentation/index.rst
> > index 9dfdc826618c..8d8b7eab1131 100644
> > --- a/Documentation/index.rst
> > +++ b/Documentation/index.rst
> > @@ -38,10 +38,7 @@ kernel.
> >  .. toctree::
> >     :maxdepth: 1
> >
> > -   core-api/index
> > -   driver-api/index
> >     subsystem-apis
> > -   Locking in the kernel <locking/index>
>
> So I don't really see the value of this.  It takes away some of the most
> important links from the documentation front page, leaving the "Internal
> API manuals" section nearly empty.  Why would we want to do this?
>
> Thanks,
>
> jon
>