From b18e8b9c8b4f9c1ef565a178e944626050478a1e Mon Sep 17 00:00:00 2001 From: EmilySeville7cfg Date: Wed, 23 Nov 2022 15:59:10 +1000 Subject: [PATCH 1/8] Standardize header syntax --- .github/README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/README.md b/.github/README.md index efd7798..e8f6339 100644 --- a/.github/README.md +++ b/.github/README.md @@ -1,5 +1,4 @@ -cheatsheets -=========== +# cheatsheets # This repository contains community-sourced cheatsheets to be used with [cheat][] and similar applications. From e77630d68348228f4fe9f426ae28c1d971d21794 Mon Sep 17 00:00:00 2001 From: EmilySeville7cfg Date: Wed, 23 Nov 2022 16:12:35 +1000 Subject: [PATCH 2/8] Write rules accrording to this comment: - https://github.com/cheat/cheatsheets/pull/183#issuecomment-1324338507 --- .github/README.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/.github/README.md b/.github/README.md index e8f6339..bd63b54 100644 --- a/.github/README.md +++ b/.github/README.md @@ -21,10 +21,19 @@ git add --all git commit -m ``` -As a guideline, it is preferred to use [docopt][] syntax when specifying -parameter placeholders. In edge-cases where that syntax may cause confusion, it -is permissible to use placeholder values (`foo.txt`, `example.com`, etc.) as -necessary. +To take a long story short here are our guidelines for cheatsheets: + +- If the cheatsheet contains frontmatter, it must be valid. +- Cheatsheets should generally be scoped to a single CLI command. + It's not always possible. For instance pages describing shell syntax often can't avoid describing + multiple CLI commands as almost everything in traditional shells is a command. +- Cheatsheets should end with a newline, but not a blank line. +- Code 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. +- Instead of placeholders use variable names like `caja "$path_to_directory"`. ### License ### Cheatsheets are licensed under [Creative Commons CC0 1.0][cc0]. See From 672cc800dbabcdc0a0fe513362f52e656ce734be Mon Sep 17 00:00:00 2001 From: EmilySeville7cfg Date: Wed, 23 Nov 2022 16:18:05 +1000 Subject: [PATCH 3/8] Be more precise about valid command pages --- .github/README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/.github/README.md b/.github/README.md index bd63b54..3f79156 100644 --- a/.github/README.md +++ b/.github/README.md @@ -24,9 +24,11 @@ git commit -m To take a long story short here are our guidelines for cheatsheets: - If the cheatsheet contains frontmatter, it must be valid. -- Cheatsheets should generally be scoped to a single CLI command. - It's not always possible. For instance pages describing shell syntax often can't avoid describing - multiple CLI commands as almost everything in traditional shells is a command. +- Cheatsheets should generally be scoped to a single CLI command (most often POSIX-compatible CLI command). + - It's not always possible. For instance pages describing shell syntax often can't avoid describing + multiple CLI commands as almost everything in traditional shells is a command. + - Don't create pages for CLI commands with a good help system like `fish`, etc because users of them already have + neat completion system/man pages written by other contributors and maintainers. - Cheatsheets should end with a newline, but not a blank line. - Code 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`. From b7ad35dec302c1699de726cfd43508aae5ca0e70 Mon Sep 17 00:00:00 2001 From: EmilySeville7cfg Date: Wed, 23 Nov 2022 22:26:50 +1000 Subject: [PATCH 4/8] Add note about grammar in descriptions --- .github/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/README.md b/.github/README.md index 3f79156..d6357f6 100644 --- a/.github/README.md +++ b/.github/README.md @@ -32,6 +32,7 @@ To take a long story short here are our guidelines for cheatsheets: - Cheatsheets should end with a newline, but not a blank line. - Code 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`. + Note for users coming from `TlDr` project: it's preferred to use `To` at the beggining of the sentence. - 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. From 34f4c4cb9140d5e70966a6c1f89f7acfb17ff0b8 Mon Sep 17 00:00:00 2001 From: EmilySeville7cfg Date: Wed, 23 Nov 2022 22:27:53 +1000 Subject: [PATCH 5/8] Remove requirenment to use variables --- .github/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/README.md b/.github/README.md index d6357f6..5a88822 100644 --- a/.github/README.md +++ b/.github/README.md @@ -36,7 +36,6 @@ To take a long story short here are our guidelines for cheatsheets: - 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. -- Instead of placeholders use variable names like `caja "$path_to_directory"`. ### License ### Cheatsheets are licensed under [Creative Commons CC0 1.0][cc0]. See From 27201891daa3972bd74111ef00e20a9ed53b6515 Mon Sep 17 00:00:00 2001 From: EmilySeville7cfg Date: Wed, 23 Nov 2022 22:31:52 +1000 Subject: [PATCH 6/8] Add note about complex placeholders --- .github/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/README.md b/.github/README.md index 5a88822..86201a1 100644 --- a/.github/README.md +++ b/.github/README.md @@ -36,6 +36,8 @@ To take a long story short here are our guidelines for cheatsheets: - 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. + It's better not write complex placeholders containing `<` or `>` inside them to demonstrate for instance how comparison + operators work in `[[`. In such cases the best option is just omit placeholders. ### License ### Cheatsheets are licensed under [Creative Commons CC0 1.0][cc0]. See From 8eedb490cb42b8a53f47a3e2301e9411f18f6b6c Mon Sep 17 00:00:00 2001 From: Emily Grace Seville Date: Sun, 18 Dec 2022 04:09:26 +1000 Subject: [PATCH 7/8] Add path placeholder and numbering naming rules - addresses https://github.com/cheat/cheatsheets/pull/207#issuecomment-1356357419 comment --- .github/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/README.md b/.github/README.md index 86201a1..d6a54cf 100644 --- a/.github/README.md +++ b/.github/README.md @@ -38,6 +38,8 @@ To take a long story short here are our guidelines for cheatsheets: - Excluding cases where it might cause confusion, commands should generally conform to [docopt][] syntax. It's better not write complex placeholders containing `<` or `>` inside them to demonstrate for instance how comparison operators work in `[[`. In such cases the best option is just omit placeholders. + - For path placeholders use ``, ``. + - Number placeholders with the following format: `` eg. ``. ### License ### Cheatsheets are licensed under [Creative Commons CC0 1.0][cc0]. See From 358f2f8fd6f50f972b96a4e77bd076a555b0cd68 Mon Sep 17 00:00:00 2001 From: Emily Grace Seville Date: Sun, 18 Dec 2022 04:14:31 +1000 Subject: [PATCH 8/8] Describe directory placeholders --- .github/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/README.md b/.github/README.md index d6a54cf..87f7425 100644 --- a/.github/README.md +++ b/.github/README.md @@ -38,7 +38,8 @@ To take a long story short here are our guidelines for cheatsheets: - Excluding cases where it might cause confusion, commands should generally conform to [docopt][] syntax. It's better not write complex placeholders containing `<` or `>` inside them to demonstrate for instance how comparison operators work in `[[`. In such cases the best option is just omit placeholders. - - For path placeholders use ``, ``. + - For path placeholders use ``, ``, or ``. Almost the same applies to directories + but instead of term `file` `dir` term is used. - Number placeholders with the following format: `` eg. ``. ### License ###