Proposal: remove `--help` and `--version` flags from pages
acuteenvy opened this issue · 15 comments
Initially suggested by @cyqsimon in #11903 (comment):
What's the policy on informational/conventional flags like these? I feel like they aren't particularly useful - if someone is using TLDR, I think it's fair to assume they likely know the existence of these conventional flags.
Some pages have these flags, some do not. I think we should not put them in unless the program in question uses some nonstandard flag (i.e. something other than --version / --help).
There are 202 pages with --help and 78 with --version as of now.
$ rg -l -- '--help' pages/ | wc -l
202
$ rg -l -- '--version' pages/ | wc -l
78They are filler in some regard however there merit for newer users to Linux especially can be helpful. They are the first commands to be replace if better commands are needed, I think they should remain.
IMO it doesn't hurt to have them -- however, if there are better examples that demonstrate the actual usage of the command in question and the limit of 8 examples is reached, they should go first (especially --version).
Thanks for the proposal. I think we could combine @CleanMachine1's, @gutjuri's suggestion and the proposed point to suggest something like this:
- Help and version flags can be used as filler examples for small pages. They can be replaced to accommodate other examples if required.
- It is suggested to document the help and version examples if they follow unconventional flags in platforms like Windows.
I personally wouldn't suggest removing them from existing pages, unless there is some other different example to replace with.
Btw, I will try to address this in #12304 later today.
What about pages that have subcommands and subcommands pages? IMO it's not that obvious that subcommands have their own "--help". Maybe it's better to just add this as a note in the description and use the 8 places for useful examples rather than taking 1 example just for a standard option?
What about pages that have subcommands and subcommands pages? IMO it's not that obvious that subcommands have their own "--help". Maybe it's better to just add this as a note in the description and use the 8 places for useful examples rather than taking 1 example just for a standard option?
I think we should deal with this on a case-by-case basis instead of specifying a definite way in the style guide, i.e. if there are only 5 subcommand pages for a reference page we would still have remaining entries to highlight global as well as subcommand help examples, in other cases we can follow your proposed method to highlight it in descriptions or add it to subcommand pages as a filler.
Help and version flags can be used as filler examples for small pages.
add it to subcommand pages as a filler
I don't quite understand the point of "filler examples". If there is a command that is so simple it can be described in less than 8 examples, then what's the point of making the page longer?
I don't quite understand the point of "filler examples". If there is a command that is so simple it can be described in less than 8 examples, then what's the point of making the page longer?
Given that there's not anything more to put, IMO it doesn't hurt, as it help new users.
Also, they are short examples, so I don't think it is a huge problem to make the page a bit longer for this.
I don't quite understand the point of "filler examples". If there is a command that is so simple it can be described in less than 8 examples, then what's the point of making the page longer?
A lot of our pages (most of the ones I know) have close to 5 examples rather than the maximum 8. We suggest the same here https://github.com/tldr-pages/tldr/blob/main/CONTRIBUTING.md#guidelines, so this is where we use filler examples like help and version. But yeah, it does make pages longer but it doesn't have a significant impact on the end-user and it makes the formatting much more consistent.
As clean machine states above tldr is not only targeted at experienced users but also towards newer ones (beginners) who aren't familiar with the command line so the filler examples come in handy for them to know how to see the complete usage/check the version.
You could tell that we could make clients show this as a global option, but that wouldn't work as a lot of tools I have used swap verbose and version flags and some don't implement help separately and it is just part of the base command's usage. So I think it is fine to have them rather then removing them completely. Optionally, We could assess who the end user of a tool might be and add this over there if we think it is required.
You could tell that we could make clients show this as a global option, but that wouldn't work as a lot of tools I have used swap verbose and version flags and some don't implement help separately and it is just part of the base command's usage. So I think it is fine to have them rather then removing them completely. Optionally, We could assess who the end user of a tool might be and add this over there if we think it is required.
I have a suggestion that I've seen on clip-pages, that is putting help and version commands on the description rather than on examples, like this:
> Help: {{-h|--help}}
> Version: {{-v|--version}}This can be easily parsed by our clients and specially rendered or even hidden if they want, not polluting the description.
Edit. Maybe it's better to put the whole help and version commands if we go this way.
I have an idea that I've seen on clip-pages, that is putting help and version commands on the description rather than on examples.
We discussed this a while ago afaik, this method is much cleaner but the issue is it would make the descriptions much longer than the suggested 3 points .
We discussed this a while ago afaik, this method is much cleaner but the issue is it would make the descriptions much longer than the suggested 3 points .
Maybe we can use only one line for this? Also, I think it's fine if it's up to the clients if they show it or hide it if the users want or even shown at the end.
Alternatively, we can use this syntax only when a non-standard option is used
Btw, I will try to address this in #12304 later today.
Pushed a commit updating the section, feel free to check it out and suggest improvements.
Alternatively, we can use this syntax only when a non-standard option is used
I second this 👆