24
comment style that tells text editors to fold sections of text (programming.dev)
submitted 1 year ago by to c/programming@programming.dev
10 comments fedilink hide all child comments
 

I noticed that the developer of kitty terminal uses this style of comments I have rarely if ever seen elsewhere:

outside
#: section {{{
inside
#: }}}

Kate text editor recognize sections for purposes of highlighting, folding etc. It's really nice for me because I sometimes I have a difficult time navigating large text files. And it lets you nest them.

  • what is this called?
  • are there other ways to do it?
  • is it standard among text editors? I believe Kovid the dev for kitty is a vim guy so presumably there is support there also.
  • why don't more people use it? are there problems?

Screenshot that shows the code folding.

  • Cursor is at the end of line 7 so the whole section line 7-22 is highlighted
  • lines 12-16 are folded in a 3rd level comment
  • I also included tab indents just to make it easier to see what's going on (Kate treats it the same way regardless of indents)
  • Highlighting/Mode > Scripts > Bash

I also like his style of distinguishing between narrative comments (starting with #:) and commented-out code (starting with #). Although in my example, Kate doesn't treat them differently. Is there a term for this? Any conventions, support etc?

plain text used for screenshot


#: Comment level 1 {{{
	#: Comment level 2 {{{
		#: configure something
		key value
	#: }}}
	#: Another Comment level 2 {{{
		#: Comment level 3 {{{
			#: Helpful explanatory comment
			file location
		#: }}}
		#: Comment level 3 with hidden text {{{
			you_cant see_this
			hidden_emoji "๐Ÿ‘๏ธ"
			hidden_emoji2 " ๐Ÿ‘๏ธ"
			hidden_emoji3 "   ๐Ÿ‘๏ธ"
		#: }}}
		#: let's set some things up
		# setting yes
		# other_setting no
		different_setting maybe
	#: }}}
	# regular comment
#: }}}

# regular comment outside anything

For a real world example, see sample kitty.conf file provided on project website.

you are viewing a single comment's thread
view the rest of the comments
[โ€“] [S] 2 points 1 year ago

I am very rarely working in other people's stuff because I am too rudimentary but of course I try to follow their rules when I do.

For my own purposes, I would do it in one of the below ways. I made the case more complicated by changing the lengths. I mostly choose consistent levels of indentation using tabs over per-character alignment but not always.

[--] = tab, ~ = single space (and double space = double space in front of comments for legibility here)

function() {
[--]var = 1
[--]another_var = 2
[--]indented(arg, arg2, arg3)
[--]indentedTwo(arg, 
[--]~~~~~~~~~~~~arg2,
[--]~~~~~~~~~~~~arg3)  #: aligned by spaces to match specific charecter length
[--]indentedThree(
[--]~~~~~~~~~~~~arg,
[--]~~~~~~~~~~~~arg2)  #: aligned by space to arbitrary charecter length, same as the previous
[--]indented4(
[--][--]arg,
[--][--]arg2)  #: aligned by tabstop by level
[--][--]~~~~~  #: this would be my preference overall if I had to chose
[--][--]~~~~~  #: (which so far I haven't)
}

Kate has a great feature called "insert smart newline" which I shortcut to shift+enter. If you are typing for example on the penultimate line above and "insert smart newline" it'll automatically fill the line with [--][--]~~~~~ #: and put the cursor at the end. This feature really enables a lot of these habits for better or worse.

When I write output to terminal I really like being able to use tabs to modify the length of tabs according to what is the content. Sometimes I wish I could set tabs in my editor (like a word processor), it would make things simpler. But then there's portability issues for non standard features like that so.

  • permalink
  • fedilink
  • source
  • parent