Hi, On 9/21/26 12:05 AM, Osman Ahmadzai wrote: > The README points at some sixty files in the tree, but it has no > extension, so it shows up as plain text and none of those paths can be > followed. You have to go and find each one by hand. > > The content has always been reStructuredText - it uses reST section > syntax for its headings - so give it the extension to match, and wrap > each in-tree reference in an anonymous hyperlink whose link text is the > path itself. The rendered text is byte-for-byte what it was before; only
What causes README.rst to be rendered? Is it named README.html? I don't see it being rendered on a clean 'make htmldocs' build. I see DOCS/Documentation/output/admin-guide/README.html, but that's a different file. > the markup is new. Anonymous because a handful of the paths are listed > twice and named targets would collide. > > checkpatch.pl and get_maintainer.pl both test for a file called README to > find the top of the tree, and the Makefile points readers at ./README, so > those are updated in step. scripts/spdxexclude lists the file as having > no copyrightable content; only its path changes there. > > Signed-off-by: Osman Ahmadzai <[email protected]> > --- > v2: Dropped the second file - you are right, two copies would be out of > sync within a release. This renames instead, so there is one copy of > the content, and updates the four places that referred to the old > name. I went with the rename rather than the symlink because it > leaves nothing pointing at a name that no longer describes the file, > and the fixups turned out to be one line each. > > I did look at folding it into Documentation/index.rst, and it looks > like a bigger change than this one rather than an alternative to it. > The README names 55 documents; only 12 of them appear in the > index.rst toctrees today, the other 43 being reachable only by > descending into process/index.rst, subsystem-apis.rst and the rest. > So integrating means either pulling those 43 into index.rst or > dropping them, and that is an editorial call about material that > landed in b9a565b3e4d8 last November rather than a presentation fix. > I would rather not make it as a side effect of this patch. > > If you do want it, what I had in mind is a short "where to start" > section near the top of index.rst - one entry per kind of reader, > pointing at the existing index documents (process/index.rst for new > developers, subsystem-apis.rst for internals, admin-guide/index.rst > for administrators, and so on) rather than repeating the individual > paths. Around forty lines, and automarkup turns every path in it > into a link with no markup needed. The README would then shrink to a > pointer at the documentation. Say the word and I will send it as its > own patch. > > Makefile | 4 +- > README | 168 ------------------------------------- > README.rst | 170 ++++++++++++++++++++++++++++++++++++++ > scripts/checkpatch.pl | 2 +- > scripts/get_maintainer.pl | 2 +- > scripts/spdxexclude | 2 +- > 6 files changed, 175 insertions(+), 173 deletions(-) > delete mode 100644 README > create mode 100644 README.rst thanks. -- ~Randy
