favour or at least mention single-letter options #8046
Comments
|
I have to agree with both the original rationale and your example of it failing. Our goal is to provide users an alternative for quickly looking up how to use a command in a beginner-friendly way, not how to master it. That's why we should, as we currently do, prefer GNU options. But yes, nobody types I think these sentences at least need a little change: GNU (or long) options are preferred/the default, but Unix (or short) options are fine in certain cases. Another option, and I think that this would be even better, is a standardized |
|
From what I can tell, the unwritten rule is for example From
|
|
@CleanMachine1 Are you sure about that? Because that would mean there is an unwritten rule that both you and And I still don't think that this is the perfect solution, we should have a way of including the long form somehow. |
|
😄 I forgot the context of that but it was something to do with making the commands understandable rather than rememberable. I think the current way we have is okay, which from what I can tell is By adding to it such as {{--sync --refresh --sysupgrade|-Syu}}, it stops the user from being able to copy the commands directly which is a pretty nice feature, and to remove it is a little annoying. |
|
(About the context: I included the link in the 1st post for convenience). I agree with @CleanMachine1 that the format I'm not sure if the md syntax would allow both alternatives on the same line when it's short enough, as for ex:
By separating the format of 'or' naturally with the colours, if need be with brackets, or using '||' instead, I think it would remain clear.
I think it touches a fundamental question. If it is described above the command, the necessary information remains to associate the functionality to the command, even if it's not always clear which letter means what - especially when they change, like 'y'... There are other examples that help understand the letters. And many other commands only have the short form anyway. Perhaps it depends on the purpose of
If that's the latter, all details must be added because we don't want someone to half-knowingly type sudo commands, but then we're back to the man pages. My understanding is that it's meant mainly for the former, I must update or look for a package but I'm not sure about the letters anymore because there are many combinations, and looking up the man pages takes a lot of time. I'm about to use this command quite a few times, so maybe I don't want to type the long form, or maybe I memorize the short form more easily. Still, other people probably prefer the long form and it should remain. What is important is the description above, short enough to describe unambiguously what the command does. |
@pixelcmtd, I personally like it for simple commands. But what to do with separation by folders?
It already exists. Note that right now not all pages are duplicated to support long/short options. Another question: what to prefer - joined single-letter (
Sometimes we can't provide comprehensive descriptions of commands because they for instance have too many defaults to list them explicitly or have complex syntax which can't be expressed easily via placeholders. For instance we can't at once describe Python syntax in 8 examples and mention CLI. But for Simple commands ( |
pixelcmtd
added
stalebot ignore
decision
|
Personally, I still like the solution I proposed in #6246. It works with all clients and doesn't make the example any longer. And if we only do this for very common pages there's also not a lot more effort to maintain this new convention. |
|
I just wanted to chime in here and advocate for some means of including the short options alongside the long options. As a intermediary solution that still supports copy-pasta while also providing the information necessary we could potentially do something like the following My preference is the latter, less to copy and then the common variant is also by default in shell history. |
|
I think this would be doable. But we would have to restrict this exception to only very few pages (like @sbrl @navarroaxel @CleanMachine1 do you think we could make an exception for |
|
As others have discussed the general rule has been that if a command is commonly used, we use short options on that page. There are many commands used in day-to-day terminal usage, and tldr-pages should reflect the version that people are most likely to use. The example of The |
|
I will say I think it's hard to define what is |
|
I agree with defaulting to short options and the argument that tldr is for practical commands. The point of the command explanation is to explain the flags, so it is redundant with long options. |
|
Sad to see this closed. Out of curiosity, is that by lack of consensus? It seems that displaying two lines like the first example only got 6 upvotes and no downvotes so I don't understand why it shouldn't be adopted for some of the commands where practically all examples use the short format. |
|
It was closed automatically as stale by gh actions bot, which I disagree with on principle (it's not that old) |
|
There are standardized rules now when to use long and short options which I've proposed. You can check style guide for them. :) As «commonly used» is not a clear and hard measurable criteria I've decided to rely on option portability across different platforms to chose when to use a long option and when a short counterpart. I guess that long non portable options can be shown via shell commentary on the same string. It will not introduce a new page syntax and make all clients to support such new feature. :) But our official clients can optionally handle these commentaries in a such way that they are shown on a separate string in a format smth like that:
|
@EmilySeville7cfg I see now, my database was simply not updated. Thanks for the style-guide update! But I see this specific issue has been discussed by someone again from scratch in another issue (#8286) instead of continuing the discussion here, and that it finally ended up with short format only. Then this duplicate issue was closed instead of this one, so it's confusing. I see the guide suggests either long or short format now, which one may find strange and arbitrary. It means that users don't see that So it's a good step but ultimately I would have kept both short and long formats, I don't see why GNU commands and OS-specific commands should have a different treatment, to be honest. It would be very easy to display each style on its own line like in the first post, and to implement a basic parsing with an option to see both formats or only one of them (for ex. from a command-line option or from an environment variable, like I fear it's too late to restart this painful discussion though. 😉 |
I agree, the best solution to provide both option's styles and give user a chance to select the preferred one. |
|
I have modified Since I'm not the owner of this tool, I have forked the project and made a pre-release here (currently tagged "CODE-FILTER-RC1" in the "code-filter" branch): Assets also include
Let me know what you think. 😀 If that's all right, then I'll propose the change to Proposed changeWhen there are "short" and "long" option format alternatives, they are (optionally) given on two consecutive lines, for example: (old format but I haven't seen any new format yet - the proposed change and its implementation work with both anyway) The filter compares two consecutive lines of example code. One must have more All other cases won't be considered as alternatives and will always be displayed. Normally, there shouldn't be successive lines of codes so far, so I don't think there should be any conflict with the current pages. Tool implementationThe modified
The command-line option is prevalent. When it is not specified and there is no entry in the config file, the default is Command-line: Config file: Test with pre-release
I have duplicated a couple of options in the |
I like this change. But I have another suggestion too now. :) I've created repo for formalizing CLI of all available commands though JSON schemas. It means that if we implement a proper CLI parser we will be able to replace short <-> long options based on user request as we will know what expect in some command CLI interface. But further more we will be able to validate commands and create linters for such tools like BTW, I see an issue in your decision. It's not clearly defined for instance where long option ends: it's undefined which assignment style it uses: just space, equal sign or smth else. My way to solve this issue addresses this problem. :) Also, what if some option is not convertible to it's long or short counterpart? How do we know how to extract options to find their counterparts? What implications are done here? Note that such questions are only valid if a real CLI parser gonna to be written. If we just present short/long options on two separate lines we care about command correctness ourselves (but I prefer to rely on programs). 😄 If we would have a CLI parser we can optionally select which options to present as long and which as short, what assignment style to prefer and everything it automatically. :) For example always show |
That's ... quite a change, sorry I missed that discussion or I wouldn't have bothered. It will solve several issues indeed, do you intend to put all the languages at the same place? Or in separate files? I suppose it could take a while before all the pages are translated. From what I saw, they haven't been translated into the "new" syntax defined in RFC 958 yet. It also means a complete re-work of the existing tools. So for the practicalities, what now, should I simply delete everything?
I'm not sure I understand the problem. Do you mean there are long options that are sometimes specified with another syntax than |
I intend to keep exactly the same file structure like in this repo for
No, it's a good work. And until I've made everything ready to automate CLI checking we can use your solution. :) It's definitely better than just having just one thing shown (short or long options).
It's not clear what delimits option value and the option itself. Sometimes it's equal sign, sometimes it's space, sometimes it's smth else... I wanna universal solution to be able describe almost any CLI can be created.
We should agree. :) Otherwise how do script quickly know what line to use to short short options or long ones? Can you create a PR changing CLIENT-SPECIFICATION to allow two lines for code example instead of one? |
Oh I see. My mistake, I misunderstood what you meant by language-independent. 😄
I mean, I'm not convinced others would adopt it, even less if the format was supposed to change. But I suppose it can't hurt to modify a few pages and create a pull request, same with the tool. Have you already started working on other tools to support the JSON format, or do you know if someone else has?
Ah, you mean the *.md format versus the *.json format, not specifically the little modification I suggested. Agreed, it's not obvious. I suppose that options mostly begin with Too bad because a script could have pre-translated the markdown pages to JSON. I suppose it's still possible to do that to speed up the conversion, but someone has to make a verification pass.
I explained it above, it compares the number of "--" and "-" in both lines. Should we enforce 1st line long and 2nd line short or just let the tool find out? To be honest, enforcing it simplifies the code, but if someone makes a mistake it won't be detected (unless s/o provides a script to check). Either is fine by me, we could simply wait to see if others chime in. I can do the PR, yes. PS: I made a quick Python script to check and at the moment, no page has successive code lines. So at least there will be no conflict. |
|
Thanks for your comments, by the way! |
I suggest to enforce (and later to implement basic script check to ensure whether everything is okay).
Can you share it with me? |
Sure. I had this one to show the successive lines of the pages I modified. It's quick and dirty and only works on the "old" syntax. """Looks for successive code lines in all *.md files (a code line begins with `)"""
import os
from os.path import join
from itertools import pairwise
for root, dirs, files in os.walk("."):
for file in (fi for fi in files if fi.endswith(".md")):
filename = join(root, file)
with open(filename, encoding="utf8") as f:
for a, b in pairwise(f.readlines()):
if a.startswith('`') and b.startswith('`'):
print(f"{filename}:\n- {a}- {b}")
breakIt doesn't print anything on the unmodified pages. It may be a good base to validate any file with long/short alternatives; I can do that later. mx = 0
for root, dirs, files in os.walk("."):
for file in (fi for fi in files if fi.endswith(".md")):
filename = join(root, file)
count = 0
with open(filename, encoding="utf8") as f:
for line in f.readlines():
if line.startswith("`"):
count += 1
if count > mx:
mx = count
mx_file = filename
else:
count = 0
print(f"max = {mx} in file {mx_file}")It returns 1. |
|
You need to be in |
|
I'll check it tomorrow I guess. Thanks. :) |
|
You're welcome. 🙂 from glob import glob
for page in glob("pages*"):
print(f"processing {page}...")
for root, dirs, files in os.walk(page):
/* ... */ |
|
I realize that 2 consecutive lines are shown on the same line, in some markdown (not here but for ex. in IntelliJ plugin):
Could that be a problem for some tools? |
I guess it's just a render problem and should be addressed specifically with such problematic plugins. |
|
@blueglyph, here is my attempt to check the order of code examples (first one should have long options and the second one - short ones): import os
from os.path import join
from itertools import pairwise
import re
from typing import Tuple, List, NewType
ShortOptions, LongOptions = NewType("ShortOptions", str), NewType("LongOptions", str)
def get_options(code) -> Tuple[List[ShortOptions], List[LongOptions]]:
code = f" {code[1:-1]} "
return (re.findall(r"\s+-([A-Za-z])\s+", code),
re.findall(r"\s+--([A-Za-z][-A-Za-z0-9]+)\s+", code))
for root, directories, files in os.walk("."):
for file in (filename for filename in files if filename.endswith(".md")):
filename = join(root, file)
with open(filename, encoding="utf8") as file:
first_code_example = True
for line in file.readlines():
if line.startswith("`"):
line = line.rstrip('\n')
short, long = get_options(line.rstrip('\n')[1:-2])
stats = f"[short: {short}, long: {long}]"
if len(short) == 0 and len(long) == 0:
pass
elif len(short) > 0 and len(long) > 0:
print(f"{filename}: expected short or long options only in {line} {stats}")
elif first_code_example and (len(short) > 0) and (len(long) == 0):
print(f"{filename}: expected long options only in the first example {line} {stats}")
elif (not first_code_example) and (len(short) == 0) and (len(long) > 0):
print(f"{filename}: expected short options only in the second example {line} {stats}")
first_code_example = False
else:
first_code_example = True
|
|
@EmilySeville7cfg Nice! I have a few suggestions, for what it's worth: For the algorithm:
And to speed up the code, are regex necessary? We don't really care about the name of the options, so isn't this enough? Here's the algorithm I used; it's Rust but hopefully it's clear enough. the count of short and long are in if prev.long < curr.long && prev.short > curr.short {
return OptionFmtSeq::ShortThenLong;
} else if prev.long > curr.long && prev.short < curr.short {
return OptionFmtSeq::LongThenShort;
} else {
return OptionFmtSeq::Other;
}So in short, if we want "long" first, we want to see more "long" in the previous line, and more "short" in the current line. Just a suggestion, but I think it will be more flexible and still as robust. PS: I see there's already a |
That's why I am going to narrow down list of used languages in TlDr while rewritting existing things to Python, Bash and Go (I don't like JS too). :) |
Maybe... I was just afraid of making the pages not back-compatible. If users just see two lines sometimes, it's fine, but if they see 2 examples on the same line it will be a mess. Mobs will rise. Heads will roll. I have modified CLIENT-SPECIFICATION.md, style-guide.md and pacman.md. Can I ask for your opinion before making the pull request? I thought your guide was the perfect place for the rule (long first, etc), but should it be in the CLI spec? And let me know if it's understandable or just gibberish. 😉 https://github.com/blueglyph/tldr/commit/a7b535042107324e0a8c1987450706842050bbe9 |
If I would keep backward compatibility constantly now we had no such standardized rules. So sometimes we can sacrifice compatibility to enhance smth.
I like how it's written, please send PR here. :) |
Thanks, there you are. I've also run both original and the new simplified RC2 Feel free to use and modify the script as you wish if you find it useful. |
The guildelines specify:
Actually the purpose is to give practical examples of commands that are often used. For example, nobody ever types
sudo pacman --sync --refresh --sysupgradeInstead, people type:
sudo pacman -SyuThat's also what you'll see people try to help you out. "Have you tried pacman -Syu?". Hmm, what does it do, let's check with tldr... and no luck, it's not there. Back to the man pages then.
So while it is interesting to see there are spelled-out options, it is redundant with the description above the command (Synchronize and update all packages:), and not very practical. Sure, I can check the man page for find the equivalent, but then this makes these pages irrelevant.
As a suggestion, it would be best to have at least the practical alternatives for long commands:
The text was updated successfully, but these errors were encountered: