Fix example and language in manpage #636

mb720 · 2023-10-29T13:16:58Z

Hi and thanks a lot for rmlint!

I'd like to offer some improvements for the manpage.

It's mostly typo fixes and attempts to make the manpage easier to read.

But I think I also spotted an error in the examples. In the old version, rmlint -e was described as

Find duplicates with same basename (excluding extension)

Yet I'm pretty sure that option -b does that, whereas -e makes rmlint consider two files as duplicates only if their extensions match.

cebtenzzre · 2023-10-29T22:27:53Z

docs/rmlint.1.rst

    This command makes ``rmlint`` exit with one of the following exit codes:

    * 0: files are reflinks
    * 1: files are not reflinks
    * 3: not a regular file
    * 4: file sizes differ
    * 5: fiemaps can't be read
-    * 6: file1 and file2 are the same path
+    * 6: file1 and file2 are at the same path


I'm not sure about this change. This status is for when the two paths provided are literally the same path after resolving symlinks, hence no data needs to be looked at. Maybe we could say "have the same path", but I'd have to think about it - technically, no two files can have the same path, because that would mean they're the same file.

Maybe "path1" and "path2" are more suitable argument names. Then this could read:

6: path1 and path2 point to the same file (after resolving symlinks)

Come to think of it, this sounds reasonable as well:

6: file1 and file2 are the same (after resolving symlinks)

Well, "the same file" is ambiguous here, because it could be taken to mean "the same inode." But that's a hardlink - two different paths that point to the same file. The paths themselves are equal after resolving symlinks in this case.

Why not just explain more explicitly in the same way as we do in this discussion?
Like:
* 6: resolved absolute paths of file1 and file2 are identical

I find that still a bit confusing: what is the actual state it should explain?

file1 is file2 (same path) or
file1 is a symlink to file2 or
file2 is a symlink to file1 or
file1 and file2 are symlink to the same file3

But they are not symlink to each others ;)

vt@luga ~/dev/contrib/rmlint% ls -l b c lrwxrwxrwx 1 vt vt 1 Mar 3 20:19 b -> c lrwxrwxrwx 1 vt vt 1 Mar 3 20:19 c -> b vt@luga ~/dev/contrib/rmlint% rmlint --is-reflink b c ERROR: lib/utilities.c:1167: rm_util_link_type: Error opening /home/vt/dev/contrib/rmlint/c: Too many levels of symbolic links

And status 9 (RM_LINK_SYMLINK) seems not possible to happen in that case

@RayOei what do you think should be the right formulation ?

I think your suggestion is fine.

vassilit · 2025-03-02T23:47:50Z

docs/rmlint.1.rst

@@ -268,7 +268,7 @@ General Options

    The letter may also be written uppercase (similar to ``-S /
    --rank-by``) to reverse the sorting. Note that ``rmlint`` has to hold
-    back all results to the end of the run before sorting and printing.
+    back all results till the end of the run before sorting and printing.


I'm not a native speaker of English, but it seems to me that until sounds better than till in this sentence and the formal style of a manual page.
What do you think?

Not native either. But from my understanding both are fine, albeit until is a bit more formal and would therefore fit a bit better in manual, I think.

docs/rmlint.1.rst

vassilit · 2025-03-02T23:52:49Z

docs/rmlint.1.rst

    while ``apple.png`` and ``peach.png`` won't. The comparison is case-insensitive.

 :``-n --newer-than-stamp=<timestamp_filename>`` / ``-N --newer-than=<iso8601_timestamp_or_unix_timestamp>``:

    Only consider files (and their size siblings for duplicates) newer than a
    certain modification time (*mtime*).  The age barrier may be given as
-    seconds since the epoch or as ISO8601-Timestamp like
+    seconds since the epoch or as an ISO8601 timestamp like


ISO 8601-formatted timestamp

or ISO 8601 formatted timestamp, whichever looks better to you.

I think 8601-formatted is unnatural in English.
The more common phrasing would be a timestamp formatted according to ISO 8601

vassilit · 2025-03-03T08:23:42Z

docs/rmlint.1.rst


  Available options:

-  - *iso8601=[true|false]:* Write an ISO8601 formatted timestamps or seconds
+  - *iso8601=[true|false]:* Write ISO8601-formatted timestamps or seconds


I guess that answers my question above ;)
I feel like it would be more accurate with a space after ISO though. What do you think?

See above 😁

vassilit · 2025-03-03T08:43:19Z

docs/rmlint.1.rst

    This command makes ``rmlint`` exit with one of the following exit codes:

    * 0: files are reflinks
    * 1: files are not reflinks
    * 3: not a regular file
    * 4: file sizes differ
    * 5: fiemaps can't be read
-    * 6: file1 and file2 are the same path
+    * 6: file1 and file2 are at the same path


Why not just explain more explicitly in the same way as we do in this discussion?
Like:
* 6: resolved absolute paths of file1 and file2 are identical

docs/rmlint.1.rst

vassilit · 2025-03-20T11:26:40Z

docs/rmlint.1.rst

-    The gui has its own set of options, see ``--gui --help`` for a list. These
-    should be placed at the end, ie ``rmlint --gui [options]`` when calling
-    it from commandline.
+    The GUI has its own set of options, see ``--gui --help`` for a list.  These


Why two spaces after dot ?

Typo, I presume?

Typo, I presume?

Yeah, but in the original version there was only one, and the two spaces appeared multiple times over the document. So maybe I thought that was a formatting of some sort.

cebtenzzre reviewed Oct 29, 2023

View reviewed changes

vassilit added the input-needed label Mar 2, 2025

vassilit added this to the 2.10.3 Ludicrous Lemur Bugfixes milestone Mar 3, 2025

vassilit reviewed Mar 3, 2025

View reviewed changes

docs/rmlint.1.rst Show resolved Hide resolved

vassilit reviewed Mar 20, 2025

View reviewed changes

Fix example and language in manpage

4122764

vassilit force-pushed the patch-1 branch from c1312f8 to 4122764 Compare March 20, 2025 11:35

man: more precision on --is-reflink output

01f5aad

vassilit approved these changes Mar 20, 2025

View reviewed changes

vassilit merged commit 01f5aad into sahib:master Mar 20, 2025

Fix example and language in manpage #636

Fix example and language in manpage #636

Uh oh!

Conversation

mb720 commented Oct 29, 2023

Uh oh!

cebtenzzre Oct 29, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mb720 Oct 30, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cebtenzzre Oct 29, 2023 •

edited

Loading

mb720 Oct 30, 2023 •

edited

Loading