[PATCH 0/4] bcachefs: casefolding.rst fixes

[PATCH 0/4] bcachefs: casefolding.rst fixes

[Bagas Sanjaya]

Hi Kent, hi Joshua,

Here are fixes for casefolding docs. Patches [1/4], [2/4], and [4/4]
fixes htmldocs warnings reported in linux-next.

Enjoy!

Bagas Sanjaya (4):
  Documentation: bcachefs: casefolding: Do not italicize NUL
  Documentation: bcachefs: casefolding: Fix dentry/dcache considerations
    section
  Documentation: bcachefs: casefolding: Use bullet list for dirent
    structure
  Documentation: bcachefs: Add casefolding toctree entry

 Documentation/filesystems/bcachefs/casefolding.rst | 13 ++++++++-----
 Documentation/filesystems/bcachefs/index.rst       |  1 +
 2 files changed, 9 insertions(+), 5 deletions(-)


base-commit: 77308424ba26e1b41a7db5d4eae121841a707c05
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 1/4] Documentation: bcachefs: casefolding: Do not italicize NUL

[Bagas Sanjaya]

Sphinx reports htmldocs warning:

Documentation/filesystems/bcachefs/casefolding.rst:36: WARNING: Inline interpreted text or phrase reference start-string without end-string. [docutils]

That's because NUL word is italicized but it is written in plural form
instead (`NUL`s). Sphinx, however, doesn't tip over when the italicized
word in this fashion is followed by punctuation instead.

Do not italicize the word to keep Sphinx happy.

Fixes: bc5cc09246c5 ("bcachefs: bcachefs_metadata_version_casefolding")
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Closes: https://lore.kernel.org/linux-next/20250221162135.79be0147@canb.auug.org.au/
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/filesystems/bcachefs/casefolding.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/filesystems/bcachefs/casefolding.rst b/Documentation/filesystems/bcachefs/casefolding.rst
index 6546aa4f7a8684..1c385b6d21a0a8 100644
--- a/Documentation/filesystems/bcachefs/casefolding.rst
+++ b/Documentation/filesystems/bcachefs/casefolding.rst
@@ -33,8 +33,9 @@ The structure looks like this:
 Regular:    [dirent data][regular name][nul][nul]...
 Casefolded: [dirent data][reg len][cf len][regular name][casefolded name][nul][nul]...
 
-(Do note, the number of `NUL`s here is merely for illustration, they count can vary
- per-key, and they may not even be present if the key is aligned to `sizeof(u64)`.)
+(Do note, the number of NULs here is merely for illustration; their count can
+vary per-key, and they may not even be present if the key is aligned to
+`sizeof(u64)`.)
 
 This is efficient as it means that for all file lookups that require casefolding,
 it has identical performance to a regular lookup:
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 2/4] Documentation: bcachefs: casefolding: Fix dentry/dcache considerations section

[Bagas Sanjaya]

Sphinx reports htmldocs warnings on dentry/dcache section:

Documentation/filesystems/bcachefs/casefolding.rst:75: WARNING: Title underline too short.

dentry/dcache considerations
--------- [docutils]
Documentation/filesystems/bcachefs/casefolding.rst:84: WARNING: Definition list ends without a blank line; unexpected unindent. [docutils]

Fix the section by:

* Extending the section underline to match the section title length;
* Separating problem list from surrounding paragraphs.

Fixes: bc5cc09246c5 ("bcachefs: bcachefs_metadata_version_casefolding")
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Closes: https://lore.kernel.org/linux-next/20250221161911.2d16138b@canb.auug.org.au/
Closes: https://lore.kernel.org/linux-next/20250221162135.79be0147@canb.auug.org.au/
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/filesystems/bcachefs/casefolding.rst | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/filesystems/bcachefs/casefolding.rst b/Documentation/filesystems/bcachefs/casefolding.rst
index 1c385b6d21a0a8..d5861b44463576 100644
--- a/Documentation/filesystems/bcachefs/casefolding.rst
+++ b/Documentation/filesystems/bcachefs/casefolding.rst
@@ -73,15 +73,17 @@ any encodings than a single UTF-8 version. When future encodings are desirable,
 they will be added trivially using the opts mechanism.
 
 dentry/dcache considerations
----------
+----------------------------
 
 Currently, in casefolded directories, bcachefs (like other filesystems) will not cache
 negative dentry's.
 
 This is because currently doing so presents a problem in the following scenario:
+
  - Lookup file "blAH" in a casefolded directory
  - Creation of file "BLAH" in a casefolded directory
  - Lookup file "blAH" in a casefolded directory
+
 This would fail if negative dentry's were cached.
 
 This is slightly suboptimal, but could be fixed in future with some vfs work.
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 3/4] Documentation: bcachefs: casefolding: Use bullet list for dirent structure

[Bagas Sanjaya]

The doc lists dirent structure for both regular and casefolded names,
yet it is written (and rendered) as long paragraph instead.

Write the structure list as bullet list.

Fixes: bc5cc09246c5 ("bcachefs: bcachefs_metadata_version_casefolding")
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/filesystems/bcachefs/casefolding.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/filesystems/bcachefs/casefolding.rst b/Documentation/filesystems/bcachefs/casefolding.rst
index d5861b44463576..ba5de97d155ffa 100644
--- a/Documentation/filesystems/bcachefs/casefolding.rst
+++ b/Documentation/filesystems/bcachefs/casefolding.rst
@@ -30,8 +30,8 @@ name with the regular name in the dirent.
 
 The structure looks like this:
 
-Regular:    [dirent data][regular name][nul][nul]...
-Casefolded: [dirent data][reg len][cf len][regular name][casefolded name][nul][nul]...
+* Regular:    [dirent data][regular name][nul][nul]...
+* Casefolded: [dirent data][reg len][cf len][regular name][casefolded name][nul][nul]...
 
 (Do note, the number of NULs here is merely for illustration; their count can
 vary per-key, and they may not even be present if the key is aligned to
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 4/4] Documentation: bcachefs: Add casefolding toctree entry

[Bagas Sanjaya]

Sphinx reports htmldocs toctree warning:

Documentation/filesystems/bcachefs/casefolding.rst: WARNING: document isn't included in any toctree

Fix the warning by adding casefolding documentation entry to bcachefs
toctree.

Fixes: bc5cc09246c5 ("bcachefs: bcachefs_metadata_version_casefolding")
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Closes: https://lore.kernel.org/linux-next/20250221161728.32739f85@canb.auug.org.au/
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/filesystems/bcachefs/index.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/filesystems/bcachefs/index.rst b/Documentation/filesystems/bcachefs/index.rst
index 7db4d7ceab5826..0415b5d781920d 100644
--- a/Documentation/filesystems/bcachefs/index.rst
+++ b/Documentation/filesystems/bcachefs/index.rst
@@ -10,4 +10,5 @@ bcachefs Documentation
 
    CodingStyle
    SubmittingPatches
+   casefolding
    errorcodes
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 0/4] bcachefs: casefolding.rst fixes

[Kent Overstreet]

On Sat, Feb 22, 2025 at 04:18:49PM +0700, Bagas Sanjaya wrote:
> Hi Kent, hi Joshua,
> 
> Here are fixes for casefolding docs. Patches [1/4], [2/4], and [4/4]
> fixes htmldocs warnings reported in linux-next.
> 
> Enjoy!

Thanks, applied

> 
> Bagas Sanjaya (4):
>   Documentation: bcachefs: casefolding: Do not italicize NUL
>   Documentation: bcachefs: casefolding: Fix dentry/dcache considerations
>     section
>   Documentation: bcachefs: casefolding: Use bullet list for dirent
>     structure
>   Documentation: bcachefs: Add casefolding toctree entry
> 
>  Documentation/filesystems/bcachefs/casefolding.rst | 13 ++++++++-----
>  Documentation/filesystems/bcachefs/index.rst       |  1 +
>  2 files changed, 9 insertions(+), 5 deletions(-)
> 
> 
> base-commit: 77308424ba26e1b41a7db5d4eae121841a707c05
> -- 
> An old man doll... just what I always wanted! - Clara
>