How documentation is organized, concerning flags?

[Luca]

What is the problem you are having with rclone?

I don't understand how documentation is organized in terms of the many flags available.

There are 4 web pages that list flags

• https://rclone.org/docs/
• https://rclone.org/commands/rclone/
• https://rclone.org/flags/
• https://rclone.org/commands/rclone_[command], for every [command]

In page https://rclone.org/commands/rclone_sync/ for example, I guess there are listed

• in section called "Options", the options applicable only to rclone sync
• in the other sections, the options that are applicable to rclone sync and also to other rclone [command]s, which are listed also in https://rclone.org/docs/, https://rclone.org/commands/rclone/ and https://rclone.org/flags/

In page https://rclone.org/flags/, I guess there are listed

• all the flags applicable to multiple rclone [command]s, so excluding those applicable only to a specific rclone [command] listed in section "Options" of https://rclone.org/commands/rclone_[command]

In section "Sync" of https://rclone.org/flags/, however, there are listed flags just used for rclone sync (for example --backup-dir). Why? Shouldn't those be listed only in https://rclone.org/commands/rclone_sync/, in sec. "Options" and not in sec. "Sync Options"?

In page https://rclone.org/commands/rclone/, there are listed

• in sec. "Options", all the flags listed also in https://rclone.org/flags/, not split into groups.
• in sec. "Options", all the flags applicable to rclone alone (e.g. --version)

However, in sec. "Options" of https://rclone.org/commands/rclone/ I would expect only flags that are applicable to rclone alone, and not to other rclone [command] (in analogy to the sections called "Options" found in pages for specific rclone [command] and in accordance to the synopsis rclone [flags]).

In page https://rclone.org/docs/, there are listed

• all the flags listed also in https://rclone.org/flags/ and in https://rclone.org/commands/rclone/, just split into different groups and with more extensive explanation.

Can someone help me make sense of how documentation is organized in terms of flags, and tell me if my understanding above is correct and where it's incorrect?

I would be glad to help in contributing to the documentation, once I'm more confortable with it.

Run the command 'rclone version' and share the full output of the command.

rclone v1.66.0

• os/version: ubuntu 22.04 (64 bit)
• os/kernel: 6.5.0-28-generic (x86_64)
• os/type: linux
• os/arch: amd64
• go/version: go1.22.1
• go/linking: static
• go/tags: none

Which cloud storage system are you using? (eg Google Drive)

Onedrive

The command you were trying to run (eg rclone copy /tmp remote:tmp)

rclone [flags]
rclone [command]

[kapitainsky]

Have a look at this thread:

Make Docs for mortals not only rclone gurus

It is continuation of my comment and ncw reply from Rclone v1.63.0 release - #7 by kapitainsky, more appropriate to move it here: Noted. Yes you are right there. The docs are, as forever, a work in progress Which commands work with which backends tends to be based on the feature flags. --inplace requires the PartialUploads feature flags on a backend and --track-renames requires Move or Copy. If you want to see what features a backend has use rclone backend features remote…

This was the last attempt to introduce some order and logic. Current docs state is result of it.

Of course it can be improved and any ideas or PRs with changes are welcomed.

[Luca]

I've just read that thread. It's about how to organize documentation mostly from the perspective of a documentation generator tool. My questions (and implicit suggestions) above are purely from a user point of view.

I mainly don't understand what's the purpose of https://rclone.org/flags/. It says "flags available to every rclone command split into groups." (emphasis added), but the groups are not general for every command, but often rather specific to a subset of commands (e.g. "Flags for anything which can Copy a file.").

On the other hand, for example, also --combined string or --create-empty-src-dirs in https://rclone.org/commands/rclone_sync/ are also listed respectively in https://rclone.org/commands/rclone_check/ and https://rclone.org/commands/rclone_copy/ (so they are flags available to multiple commands). So why not put also those flags into https://rclone.org/flags/?

Put in simple words, If my understanding is correct since I don't have a long experience with rclone and apart from technical considerations on how to implement this automatically, I would:

• move https://rclone.org/docs/#options to https://rclone.org/flags/ and reorganize it so to have a unique and coherent grouping scheme and both brief and long description in one page.
• for each long flag description in https://rclone.org/flags/, list all the commands to which it is applicable (in my opinion this would make having a grouping scheme like "Listing" or "Logging" less important)
• in https://rclone.org/flags/, list all the flags (e.g. including --create-empty-src-dirs of rclone sync and rclone copy)
• in https://rclone.org/commands/rclone/, list and explain only the flags relevant to only rclone [flags] (and not rclone [command])

I'd like to have some reassurance that my understanding is correct and so my suggestions plausible.

Thanks,
Luca