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
Proposal: remove --help
and --version
flags from pages
#12306
Comments
They 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:
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? |
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. |
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. |
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. |
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. |
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 |
Pushed a commit updating the section, feel free to check it out and suggest improvements. |
I second this 👆 |
Initially suggested by @cyqsimon in #11903 (comment):
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.The text was updated successfully, but these errors were encountered: