Project

General

Profile

Actions

Idea #19939

closed

Fully document, illustrate how to use arv-mount --exec

Added by Brett Smith almost 2 years ago. Updated 9 months ago.

Status:
Resolved
Priority:
Normal
Assigned To:
Category:
Documentation
Start date:
Due date:
Story points:
0.5

Description

There's nothing in our documentation that actually tells you how to use arv-mount --exec. Some of arv-mount --help sort of hints at it, and you can figure it out if you're very familiar with the underlying conventions, but we can do better.

  • Consider writing our own usage line(s) for arv-mount, rather than relying on the one generated by argparse. There are so many options that the generated one is unhelpfully long anyway. One should illustrate how to use arv-mount --exec. Others can illustrate other common operation modes.
  • The help string for --exec should specify:
    • It reads the command as multiple arguments, until it reaches the end of arguments or --.
    • The command is not run through the shell. (This is important because it means your command can't use shell constructs, globs, etc.)
  • If possible without writing new code, write a metavar for --exec that better illustrates that multiple arguments are used. There was a previous attempt at this (metavar is a tuple) but it doesn't work as intended, it just gets rendered as ....
  • There should be no need for epilog text after these changes. We shouldn't expect users to read documentation in two places to learn how to use one feature.
  • Add a section to doc/user/tutorials/tutorial-keep-mount-gnu-linux.html that illustrates how to use arv-mount --exec with a basic example.

Related issues 2 (0 open2 closed)

Related to Arvados - Bug #8294: [FUSE] arv-mount usage message shows incorrect order for [--exec ...] optionResolvedBrett SmithActions
Related to Arvados - Feature #21504: arv-mount reference pageResolvedBrett SmithActions
Actions #1

Updated by Brett Smith almost 2 years ago

  • Related to Bug #8294: [FUSE] arv-mount usage message shows incorrect order for [--exec ...] option added
Actions #2

Updated by Brett Smith almost 2 years ago

  • Description updated (diff)
Actions #3

Updated by Brett Smith almost 2 years ago

  • Target version set to Future
Actions #4

Updated by Brett Smith almost 2 years ago

  • Story points set to 0.5
Actions #5

Updated by Brett Smith 10 months ago

Actions #6

Updated by Brett Smith 10 months ago

  • Target version changed from Future to Development 2024-03-13 sprint
  • Assigned To set to Brett Smith
  • Status changed from New to Resolved

As part of #21504, the --help text is improved, there is no separate epilog documentation anymore, and there's an example in the new options refererence.

Actions

Also available in: Atom PDF