Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Minor documentation nits #22

Open
mlawren opened this issue Mar 27, 2024 · 1 comment
Open

Minor documentation nits #22

mlawren opened this issue Mar 27, 2024 · 1 comment

Comments

@mlawren
Copy link

mlawren commented Mar 27, 2024

A couple of things look funny to me:

  1. If you understand the same convention around square brackets that I do, then the synopsis indicates to me that an argument is optional, when in fact one is required. Ideally just this?:

    rfc <command> | <number>

  2. If angle brackets above indicate user-provided argument then for consistency I would expect the same for sub-commands:

    rfc search <query>

  3. Along the same lines, if you don't bold the sync synopsis keywords, why do you underline the search synopsis keyword? Or vice-versa ...

  4. The CURL environment variable description is not quite a sentence. Perhaps "Force the use of curl (default) or wget to retrieve RFC files"?

bfontaine added a commit that referenced this issue Mar 28, 2024
@bfontaine
Copy link
Owner

  1. I think this was because you can run rfc without argument, although it’s useless. I fixed it.
  2. I removed the brackets in 1.
  3. the arguments of the sync command are fixed words, while the one for search is a placeholder. In the source I used <query> for the placeholder and `week` or `month` for the fixed words. Would you expect all arguments to be underlined (or bold), even if they are of different “type”?
  4. Fixed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants