add indentation guide - #116
Conversation
FichteFoll
left a comment
FichteFoll
left a comment
There was a problem hiding this comment.
Since this is a draft PR, I just took a very brief look at what you were going for here and added a few comments
|
|
||
| Sublime Text can perform automatic indentation when you type. | ||
| It can also reindent text according to the indentation rules on demand. | ||
| Note that it will not perform auto-formatting, like adding newlines or adjusting spaces around parenthesis and the like. You would need an external tool or plugin for that. |
There was a problem hiding this comment.
Please consider adding more line breaks at positions that make sense semantically. I assume you're still in the process of revising this, however, since some sections already use shorter lines.
There was a problem hiding this comment.
The plural is "parentheses."
There was a problem hiding this comment.
| Note that it will not perform auto-formatting, like adding newlines or adjusting spaces around parenthesis and the like. You would need an external tool or plugin for that. | |
| Note that it will not perform auto-formatting, | |
| like adding newlines or adjusting spaces around parentheses. | |
| You would need an external tool or plugin for that. |
Mostly fixing the plural of "parenthesis," but also breaking into phrases like the contributing docs ask.
| This is also potentially useful for incomplete statements (split over multiple lines), for example some languages require statements to be terminated with a semi-colon `;`, and visually indenting them makes it more readable. | ||
| ```js | ||
| a.b().c.d.e.f | ||
| .g().h.i(); |
There was a problem hiding this comment.
This is actually a bad example here because this exact use case breaks when a statement is broken over more than just two lines. A better idea would be to cover C-style bracket-less if statements.
| Indentation rules are defined using metadata files. | ||
| However, because metadata for indentation rules is complicated and | ||
| is commonly required by packages which add syntax definitions, | ||
| it's discussed separately in this page |
There was a problem hiding this comment.
As a general style thing, I tend to refrain from using shortenings like "it's" in prose. But this is an optional thing and just an FYI. I will most likely do a full pass on the page once it's ready for a more detailed review and commit it directly.
|
|
||
| ## Indentation when pressing <kbd>Enter</kbd> | ||
|
|
||
| The main aspect of auto indentation increasing the indent level occurs when pressing <kbd>Enter</kbd>, anywhere on a line. |
There was a problem hiding this comment.
We have a custom tag for key bindings. Usage is <Key k="enter" />.
michaelblyons
left a comment
michaelblyons
left a comment
There was a problem hiding this comment.
Learned some things, reading this. I almost want a set of flow charts now. 😅
|
|
||
| Sublime Text can perform automatic indentation when you type. | ||
| It can also reindent text according to the indentation rules on demand. | ||
| Note that it will not perform auto-formatting, like adding newlines or adjusting spaces around parenthesis and the like. You would need an external tool or plugin for that. |
There was a problem hiding this comment.
The plural is "parentheses."
|
|
||
| ### other built-ins | ||
|
|
||
| The user preference `indent_to_bracket` adds whitespace up to the first open bracket when indenting. It also affects unindenting too, the close paren is placed in the column after the open paren. |
There was a problem hiding this comment.
| The user preference `indent_to_bracket` adds whitespace up to the first open bracket when indenting. It also affects unindenting too, the close paren is placed in the column after the open paren. | |
| The user preference `indent_to_bracket` adds whitespace up to the first open bracket when indenting. It also affects unindenting, too; the close paren is placed in the column after the open paren. |
|
I tried to send someone to the community docs for this info and realized this PR wasn't incorporated yet. 😅 |
|
ah sorry, I never really got round to finishing, so little time and more interesting and beneficial (to me) things to do... |
3 participants
Fixes #107