Cheat sheet standardized formatting

[ghost]

Hi @chubin !

I don't recall seeing a method by which I or another can contact you -- might be nice to set up an E-Mail for that, for these awesome projects of yours, if you haven't already done so. It would save creating issues like this.

Okay, so my question, regarding the formatting of the sheets, is whether this is preferred:

# CMD
# Short description

...

Or this, apt-cache(1) search style:

# CMD - Short description

...

Or this:

# CMD
#
# Short description

...

Reason being, my OCD screams at me when I see inconsistencies (lol), and I was hoping to, if you'd like, go through each of the cheets to make it either one of those styles, or perhaps another of your choosing.

What think you?

[chubin]

Hi! I have twitter (igor_chubin) and email (igor@chub.in). Feel free to use any of them, but I prefer email.

I have the same problem too, and I would be glad to standardize that.
I think that the first, and the third options are the best ones,
because the second one has several disadvantages:

1. If the topic name and the description are long enough, it can easily happen, that 80 characters will not suffice for the whole line.
2. Theoretically, it can be possible, that the topic name itself contains - (even with spaces).

I tend to something like this:

# TOPIC
# Short description
#
# Long multi-line description
# when needed

Another interesting option to discuss, is usage of the front-matter format in the cheat sheets, for example for adding interlinks (like see also) etc.
We discussed it with @chrisallenlane in chubin/cheat.sh#127
but the question is still open. It would be very interesting to hear your opinion on it

[chrisallenlane]

For what it's worth, @chubin, the front-matter approach has been working well for cheat so far. In my opinion, it has two primary advantages:

1. This pattern is well-understood by a lot of folks, given that most "static-site generators" employ the same approach for attaching metadata to pages.

2. Even if our respective implementations support different subsets of metadata, the front-matter pattern allows cheatsheets to be portable among projects. There need be only one rule - never display the front-matter metadata as output. Beyond that, different implementations would be free to add/remove/use/ignore any front-matter as desired.

[dufferzafar]

navi - the new kid on the block also proposes some syntax: https://github.com/denisidoro/navi#syntax-overview

[chubin]

@chrisallenlane Chris thank you for the feedback. I think that the we should adopt the front-matter approach as well. cheat.sh must support the cheat upstream repository anyway, so why not use the same format for this repository too. We should probably also standardize the names of the meta properties, at least the most important of them. What properties do you already have?

@dufferzafar At least we should add navi cheat sheets as yet another cheat sheets upstream repository, and for that we need a initial implementation of the navi format on our side.

[chrisallenlane]

Hi, @chubin

Sorry for the delay once again. Things have been hectic.

Currently, cheat only supports two properties in front-matter:

• syntax (string): the syntax highlighter to use on output
• tags (array of strings): tags to associate with a cheatsheet (can be used as a filter, eg: cheat -l -t <tag>

It's possible cheat will eventually support more properties, but so far, I haven't encountered a need. The front-matter solution is quite flexible, though, so it would not be difficult to add support for more properties if we discovered a need.

Just shout if I can help 🙂

[chubin]

I'm also thinking about limiting the maximum cheat sheet width
by 80 characters, and adding this (and maybe some other)
check to pull-requests checks

[ghost]

I'm all for that, Chubin! :D Or, and I'm willing to help migrate the sheets over, you could incorporate wrapping into the site, so that it would no longer matter how long lines are, but I think that might just get confusing (comment lines would then go on forever, and code could end up wrapped) and mean more work. I like the 80-column limit, though.

[chubin]

I my opinion, it is better to enforce the width before the merge, so that the files in the repository are already formatted properly, and do not require post-processing. There can be some exceptions (links, embedded data, etc), but in general it should be ok

[ghost]

I agree, to a point.

With a complete forcing of <=80 columns, you have the issue of whether GitHub knows the difference between code (acceptable to be long lines, such as for one-liners) and comments. I'm not even remotely familiar with these checks GitHub performs, as I don't use them, so I'm not sure how easy that'd be to set up.

Is there a way to have GitHub look only for the column length of comments and not code? That would be good. Then again, this project deals with different languages, so different commenting characters.

Then you also have the issue of GitHub picking up on comment lines with, say, a link in it which is long; there's simply no sensible way to shorten that, so it has to stay long. EDIT: Just realised you mentioned links already, my bad.

[chubin]

Actually, the checks work very easy: they are just script, that test the repository for compliance.
In our case it could be something like:

grep -rP '^#.{80}' sheets/

and if anything is found, the test is failed.

Wow, bad:

$ grep -rP '^#.{80}' sheets/ | wc -l
137

[ghost]

Lol Noice. That's an awesome system I had no idea GitHub had in spades. So, would GitHub (I know grep only looks) just check but not actually make any changes to that effect?

[chrisallenlane]

+1 for linting cheatsheets.

I've been considering doing the same in cheat/cheatsheets as well. I've been considering linting along the following lines:

1. Comment lines should begin with # To (As in, prefer # To foo the bar: over # Foo the bar)
2. Max line length (likewise at 80 columns)
3. Disallow/trim trailing blank newlines

(I'm not sure about 1, because not all sheets necessarily should conform to this format.)

I've been thinking about using Github Actions to implement this. I've been experimenting with these recently, and I'm happy with them so far. In the near-term, I'll likely move cheat CI from Travis to Github Actions as well.

I'll gladly share any progress I make on that front (when I get around to it), if you folks are interested in it.

[chubin]

We will probably use GitHub Actions too. I am using them in some other projects, and I am pretty happy with it.

I like your list of checks. I would also add aspell’ing of the comment lines

[ghost]

I disagree with you on point 1, Chris, because words like to are redundant, in this case. Also, it takes unnecessary room for the comment, which could mean the difference between a nicely-presented comment on one line, or one on two lines. A similar approach is often used in the usage output of commands.

I think the use of things like 'To' make sense when the subject isn't implied, but the subject here is the associated code. I guess you could think of it like using self in code.

@chubin, offering me a position as a collaborator means a lot, but I have to decline due to anonymity reasons. Thank you very much though, and know that I'm happy to contribute whenever I can. :) I wish I could contribute to your other projects, but they're in languages I know diddly-squat about. lol

By the way, I think this whole discussion about Actions and GitHub's checks is really going to up my GitHub game, so thank you, guys!

[chubin]

We also should standardize quotes usage in comments:

• backticks — for verbatim names and code?
• 'single quotes' — for ???
• "double quotes" — for ???

After that, at least for backticks, we could use other output format

[ghost]

Was thinking of something like that earlier, so I'm on-board, for sure. Here's my suggestion:

• `backticks` - Code, or when referencing command, unless its man page is used, such as man(1).
• 'single quotes' - Paths, filenames, and the usual English rules.
• "double quotes" - Usual English rules. Can't think of anything specific to put here.

I think we should work on one thing at a time, though. We have a lot of work getting through everything lenchk picks up. Lol That's what I'm thinking, at least.