Open ghost opened 4 years ago
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:
-
(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 https://github.com/chubin/cheat.sh/issues/127
but the question is still open. It would be very interesting to hear your opinion on it
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:
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.
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.
navi - the new kid on the block also proposes some syntax: https://github.com/denisidoro/navi#syntax-overview
@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.
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 outputtags
(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 :slightly_smiling_face:
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
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.
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
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.
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
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?
+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:
# To
(As in, prefer # To foo the bar:
over # Foo the bar
)(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.
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
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!
We also should standardize quotes usage in comments:
backticks
— for verbatim names and code?After that, at least for backticks, we could use other output format
Was thinking of something like that earlier, so I'm on-board, for sure. Here's my suggestion:
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.
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:
Or this, apt-cache(1)
search
style:Or this:
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?