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

Documentation example commands should prefer short options #15571

Open
witt-bit opened this issue Jan 21, 2025 · 1 comment
Open

Documentation example commands should prefer short options #15571

witt-bit opened this issue Jan 21, 2025 · 1 comment

Comments

@witt-bit
Copy link
Collaborator

Hi, I noticed that most of the example commands in tldr documents use long options. I think this is inconsistent with my understanding. I think tldr-pages is a convenient tool to quickly familiarize yourself with commands. The example commands provided should be as short and easy to understand as possible. It doesn't make sense that the example commands always use long options!

@Managor
Copy link
Collaborator

Managor commented Jan 23, 2025

The reason why we use longform is to teach. A longform option conveys what the option does better. I forgot what contribution guideline file this reasoning was explained in.
Case by case we might use shortform like for example in pacman-sync because nobody uses pacman longform options or we might use {{-s|--longform}}. When only shortform option is available, we use mnemonics. https://github.com/tldr-pages/tldr/blob/main/contributing-guides/style-guide.md#option-syntax
I have made some ideas on how to make it user configurable to show either longform or shortform. I'm currently waiting for feedback from other members #15253

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