alias: split alias into two pages: alias and unalias

[EmilyGraceSeville7cf]

No description provided.

[chrisallenlane]

Thanks for opening this, but I'm going to decline to merge. I'd prefer to keep cheatsheets brief, and I'd prefer not to insert context/commentary beyond the commands unless they're strictly necessary.

[EmilyGraceSeville7cf]

@chrisallenlane

What makes such output necessary then? As a person relying on strict rules I have to ask. 😊

If u mean that some change is necessary when at least one person don't understand the current page then here I am: if I were a newbie in Bash this comments would be useful for me.

If this definition of necessarity is wrong can u explain me what you mean to help me review PRs correctly? Because now while reviewing PRs due to the absence of strict rules here I rely on some TlDr style guide ones.

[chrisallenlane]

Hi, @EmilySeville7cfg

Let me take a small step back and describe what I want (and don't want) in a cheatsheet pull-request.

Want

Regarding the minutia, this is generally what I want to see:

• If the cheatsheet contains frontmatter, it must be valid.
• Cheatsheets should generally be scoped to a single CLI command.
• Cheatsheets should end with a newline, but not a blank line.
• Command "blocks" should be separated by a single blank line.
• The comment line should end with a colon: (# To foo the bar:, rather than # To foo the bar)
• Text should be reduced near to the minimum necessary to do the job. Avoid commentary and context where possible.
• Where possible, cheatsheets should be consistent both internally, and with other sheets.
• Excluding cases where it might cause confusion, commands should generally conform to docopt syntax.

I waste an annoying, disproportionate amount of time making minor text edits like that on PRs, so if you want to keep your eyes open for those problems, that would be very helpful. (Frankly, I've gotten lazier about correcting some of these problems as they come in. I just don't have time to care right now.)

(And, to clarify: I have never documented the "rules" above anywhere, so it's my fault alone if folks submit PRs that don't adhere to these guidelines. I can't expect contributors to read my mind.)

Let me elaborate on two of those above:

Text should be reduced near to the minimum necessary to do the job. Avoid commentary and context where possible.

The reasoning behind this is twofold:

One, cheat provides cheatsheets, which are brief by definition. Users interested in more information should consult the man pages or online documentation.

Two, and critically: one of the most important use-cases for cheat is in conjunction with the --search flag. Example: I personally use cheat git -s amend much more often than I use the unadorned cheat git. With that said, the less extraneous noise we can keep out of the sheets, the more effective the search function will be.

Where possible, cheatsheets should be consistent both internally, and with across other sheets.

"Where possible" is critical here, because some cheatsheets simply must be formatted uniquely. The vim cheatsheet is perhaps the best example of this case, because vim is an interactive application.

As an aside, these "weird" cheatsheets are the primary reason I haven't attempted to write a linter to enforce these "rules." They can only ever be "guidelines" instead of "rules," because certain cheatsheets aren't compatible with the typical format. ("Frontmatter must be valid" is the one obvious exception. I do plan to eventually build CI tooling to verify YAML correctness when a PR is opened.)

Don't Want

I am averse to PRs that engage in bikeshedding, which primarily rearrange whitespace or make subjective formatting changes. These are actively harmful to the project, because they consume my (and others') time, which could be better spent working on more impactful changes.

(Note that I don't consider the correction of typos or technical errors to be bikeshedding. The contributions are valuable, if small.)

I'm also somewhat averse to giant PRs that touch multiple cheatsheets at once - especially if they contain a mixture of small and large changes. These can take a long time to review, are likely to cause merge-conflicts with others' work, and generally waste my time and slow down progress.

I hope that's helpful. It probably would be worth documenting this somewhere in the future. You can see the theme, though - I simply haven't had time to do this.

Please let me know if you have any questions. Thanks.

[EmilyGraceSeville7cf]

@chrisallenlane

Cheatsheets should generally be scoped to a single CLI command.

Can I just split alias page to two without any drastic changes to the content? I am doubt because this page is too small and it's not harmful to keep it as it is.

Excluding cases where it might cause confusion, commands should generally conform to docopt syntax.

It should be clearly defined what is considered to be a confusion. Placeholder syntax with angle brackets breaks most shell's syntax in many examples: you can't copy-paste such examples without any edits because it's invalid syntax. As a workaround we can avoid placeholders at all and use valid variable syntax instead of them:

caja "$path_to_directory"

As a bonus: user will not be confused with a "strange new syntax" in examples because everything will be a valid shell syntax. Personally I can fix all pages to use variables instead of placeholders if u agree that it's a good suggestion.

What I am suggesting now is an entirely different solution of writing pages compared to TlDr project where {{/}} are used as a placeholder delimiters.

Please let me know if you have any questions. Thanks.

I have one. 😄 Is it correct that this project aims to provide help system for commands without good help system via -h/--help and man "$command_name"? I am asking because in TlDr for instance we have (from my point of view) a little bit another goal: to provide a standardized way to get help for all possible commands and even those having a good help system.

[chrisallenlane]

@EmilySeville7cfg

Can I just split alias page to two without any drastic changes to the content? I am doubt because this page is too small and it's not harmful to keep it as it is.

I wouldn't bother in the case of alias. The entire cheatsheet consists of 3 commands anyway, and a search for alias will substring match unalias.

Placeholder syntax with angle brackets breaks most shell's syntax in many examples: you can't copy-paste such examples without any edits because it's invalid syntax.

This is a convention that has been widely used everywhere, though. Example:

chris@longarm:~$ git --help
usage: git [--version] [--help] [-C <path>] [-c <name>=<value>]
           [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
           [-p | --paginate | -P | --no-pager] [--no-replace-objects] [--bare]
           [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
           <command> [<args>]

This is why docopt syntax looks the way it does: it just codified the convention.

I wouldn't worry too much about users being able to copy-and-paste commands. In most cases, they're going to need to make modifications anyway, even if only to specify file paths in place of placeholders regardless of what syntax is used, be it <foo> or $foo.

Lastly: cheat has been around for nearly 10 years now, by my recollection, and it's used by a lot of people. I'd rather not change the conventions now, even if only to avoid disruptions (and annoyances) to existing users. A change like this is going to cause friction.

Is it correct that this project aims to provide help system for commands without good help system via -h/--help and man "$command_name"? I am asking because in TlDr for instance we have (from my point of view) a little bit another goal: to provide a standardized way to get help for all possible commands and even those having a good help system.

Neither, really. The goal of the project is just to provide a convenient tool for users to record the quick-and-dirty bash commands that they will need on a recurring basis. Think of it as a local cache for Stack Overflow: instead of Googling a command over and over again, just Google it once and store it in a cheatsheet.

The community cheatsheets are just kind of a "bonus" on top of the above goal. But if there's perhaps two things I'd like to see in community cheatsheets, they are:

1. 99% use-case examples
2. Clever/helpful usage examples that are still broadly applicable

We aren't trying to recreate the man pages, or the functionality provided by tldr. If a user wants tldr's functionality, they should use tldr! It's a wonderful project!

[EmilyGraceSeville7cf]

@chrisallenlane,

I wouldn't bother in the case of alias. The entire cheatsheet consists of 3 commands anyway, and a search for alias will substring match unalias.

Got it.

Lastly: cheat has been around for nearly 10 years now, by my recollection, and it's used by a lot of people. I'd rather not change the conventions now, even if only to avoid disruptions (and annoyances) to existing users. A change like this is going to cause friction.

I understand it. So the only way I can help enhance project in this context is to check all pages to for conforming docopt conventions and fix errors to enhance user experience. :)

So I have no any questions no, thanks! 🚀