search

rclone / rclone

"rsync for cloud storage" - Google Drive, S3, Dropbox, Backblaze B2, One Drive, Swift, Hubic, Wasabi, Google Cloud Storage, Azure Blob, Azure Files, Yandex Files
https://rclone.org
MIT License
47.05k stars 4.21k forks source link

Rewrite or remove the man page for rclone #5099

Open buengese opened 3 years ago

buengese commented 3 years ago

The current rclone man page is a bit of a mess, it's way too long, doesn't get to the important points. That's of course because the current manpage is a straight conversion of the entire documentation.

I'd suggest rewriting a short man page more in line with the standards, i.e. just a short summary, a list of the commands, flags, and backends, and a few examples and links to the docs for everything else.

Another option would potentially be to remove it entirely since rclone help already covers a decent part of the function of a man page.

buengese commented 3 years ago

@rclone/rclone

ncw commented 3 years ago

The rclone man page is of course a straight forward conversion of MANUAL.md which is in turn a concatenated version of the docs with a big of munging which is done by make_manual.py

Maybe we should be asking ourselves if and how we should improve MANUAL.md because I think improvements to that will make a better man page. This also generates MANUAL.html.

Maybe what is needed is a more traditional first section (other than the opening page of the website) which is much more like a man page. This could even be a page on the website which is a good idea since it will get more eyeballs on it. So a replacement for _index.md. This might need to have auto generated parts.

I still like the idea of having all the docs in MANUAL.md and the man page. It does make it long, but no-one can complain that man page is out of date or incomplete! Though perhaps the man page way would be to have separate docs for rclone, rclone-s3, rclone-box

Maybe we should accept the fact that the main docs were designed to be viewed on the web and leave them there.

Or we could supply a complete copy of the rclone website as docs...

@albertony and @edwardxml I'd value your feedback here.

PS I really don't want to be maintaining troff man files - I'd much rather do the conversion from markdown using pandoc even if it isn't quite perfect.

albertony commented 3 years ago

I have never used MANUAL.md/MANUAL.html myself, so personally I would not mind if only https://rclone.org manual were available, in addition to the built-in command-line help.

Looking into the MANUAL.html, I see when opening the local MANUAL.html most links go the the web version.. So in MANUAL.html#configure, clicking "Box" link in the list "See the following for detailed instructions for:" takes me to https://rclone.org/box/ and not to MANUAL.html#box. So unless you enjoy scrolling a lot in the huge single-page website, as soon as you click a link you are taken to the online version and likely to continue there..?

Or we could supply a complete copy of the rclone website as docs...

One alternative could be, like PowerShell's Update-Help: Add a command that downloads a copy of the website/manual docs.

ivandeex commented 3 years ago

Or we could supply a complete copy of the rclone website as docs...

One alternative could be, like PowerShell's Update-Help: Add a command that downloads a copy of the website/manual docs.

In the Linux world it will be called apt install rclone-doc. I propose a new rclone-doc.deb (rpm) with a local copy of html pages in /usr/share/doc/rclone/html. This will need a change in Makefile.

Next. Currently man rclone is a useless behemoth as large as as man bash. However, many packages have a stub man page. Let's have man1/rclone.1 a stub that just says You can run rclone help or see full documentation locally in /usr/share/.... or online at rclone.org. I'd even delete the stub from rclone.deb (make it a binary-only package) and move it to rclone-doc.deb.

edwardxml commented 3 years ago

Let's have man1/rclone.1 a stub that just says You can run rclone help or see full documentation locally in /usr/share/.... or online at rclone.org. I'd even delete the stub from rclone.deb (make it a binary-only package) and move it to rclone-doc.deb.

tl;dr @Ivandeex might be the way to go.

I only use rclone on linux and it feels good to me to have a man page. Proper applications should have a man page right? I have used the man page and got the information I sought. Searching through man pages is easy so the length of the page doesn't bother me.

However.

I only searched in man because I knew exactly what I was looking for. Reading through the man would not be a good introduction to using rclone. It is unlikely I would use the man again. Web is more convenient for us all. Rclone users are not sitting in front of green screen terminals and any that insist on doing so have smartphone web browsers.

Accepting man no longer holds substantive documentation will strip constraints away on crosslinking the web documentation. At present external links are fine but intra documentation links are awkward and liable to lead the reader from man to the web documentation.

Navigation menus and search tools added in future to the web site will diverge the man and web experience. Maintaining man functionality hampers that sort of improvement.

Rclone doesn't lend itself to the way most of us use man nowadays. It is a family of commands. The rsync like synopsis and list of flags doesn't fit well. Separate man pages would be hard to justify prioritising. There would still be an issue dealing with overlapping flags between man pages and that would distract from getting cross reference right in the web pages.

I like man pages and use them routinely. I can see when rclone was smaller and simpler the present arrangement worked well. Now it distracts from improving documentation in page navigation, search and cross reference hyperlinks.

Rclone is beyond the point it is effective to single source documentation between web and man. Nobody wants dual source...

ncw commented 3 years ago

@albertony wrote:

I have never used MANUAL.md/MANUAL.html myself, so personally I would not mind if only https://rclone.org manual were available, in addition to the built-in command-line help.

If the man page emphasized how to get help out of rclone that might be a good idea

rclone --help
rclone command --help
rclone help flags <regexp> # I use this one all the time!
rclone help backend backend name
rclone backend help name

None of that covers the getting started though.

Looking into the MANUAL.html, I see when opening the local MANUAL.html most links go the the web version.. So in MANUAL.html#configure, clicking "Box" link in the list "See the following for detailed instructions for:" takes me to https://rclone.org/box/ and not to MANUAL.html#box. So unless you enjoy scrolling a lot in the huge single-page website, as soon as you click a link you are taken to the online version and likely to continue there..?

Probably.

This could be fixed... Maybe!

Or we could supply a complete copy of the rclone website as docs...

One alternative could be, like PowerShell's Update-Help: Add a command that downloads a copy of the website/manual docs.

Hmm... rclone fetch docs would be easy to write...

@ivandeex wrote

Or we could supply a complete copy of the rclone website as docs...

In the Linux world it will be called apt install rclone-doc. I propose a new rclone-doc.deb (rpm) with a local copy of html pages in /usr/share/doc/rclone/html. This will need a change in Makefile.

This is a common pattern in the unix world. We could make a .zip file for everyone else too.

Next. Currently man rclone is a useless behemoth as large as as man bash. However, many packages have a stub man page. Let's have man1/rclone.1 a stub that just says You can run rclone help or see full documentation locally in /usr/share/.... or online at rclone.org. I'd even delete the stub from rclone.deb (make it a binary-only package) and move it to rclone-doc.deb.

I think I'd keep the stub in the rclone.deb/.zip etc packages if only as a pointer to the full docs. Also the stub could emphasize rclone's self help features (see above).

@edwardxml wrote:

Let's have man1/rclone.1 a stub that just says You can run rclone help or see full documentation locally in /usr/share/.... or online at rclone.org. I'd even delete the stub from rclone.deb (make it a binary-only package) and move it to rclone-doc.deb.

tl;dr @ivandeex might be the way to go.

Indeed!

I only use rclone on linux and it feels good to me to have a man page. Proper applications should have a man page right? I have used the man page and got the information I sought. Searching through man pages is easy so the length of the page doesn't bother me.

Searching a single page doc is easy. Whether you'll find what you need is another thing. Google does it better ;-)

I only searched in man because I knew exactly what I was looking for. Reading through the man would not be a good introduction to using rclone. It is unlikely I would use the man again. Web is more convenient for us all. Rclone users are not sitting in front of green screen terminals and any that insist on doing so have smartphone web browsers.

Accepting man no longer holds substantive documentation will strip constraints away on crosslinking the web documentation. At present external links are fine but intra documentation links are awkward and liable to lead the reader from man to the web documentation.

Navigation menus and search tools added in future to the web site will diverge the man and web experience. Maintaining man functionality hampers that sort of improvement.

Rclone doesn't lend itself to the way most of us use man nowadays. It is a family of commands. The rsync like synopsis and list of flags doesn't fit well. Separate man pages would be hard to justify prioritising. There would still be an issue dealing with overlapping flags between man pages and that would distract from getting cross reference right in the web pages.

I like man pages and use them routinely. I can see when rclone was smaller and simpler the present arrangement worked well. Now it distracts from improving documentation in page navigation, search and cross reference hyperlinks.

Rclone is beyond the point it is effective to single source documentation between web and man. Nobody wants dual source...

A lot of most excellent point. Especially "Nobody wants dual source..."!

OK here is a proposal

We write a stub man page in MANUAL.md so that page will no longer be auto generated. This will contain a very short synopsis of rclone and instructions on

This page could be on the website also if we wanted if we stuck it in docs/content/manual.md

We then supply that as a MANUAL.txt, MANUAL.html and rclone.1 in the zip files as we do at the moment. I hope we can carry on using pandoc as we do at the moment for converting from MANUAL.md to the other formats.

We also adjust the build to make rclone-doc.zip and rclone-doc.deb which is essentially a built copy of the website.

Thoughts?

albertony commented 3 years ago

Sounds good!