Make .no-line-numbers the default

[ang-zeyu]

My observation is that line numbers are really not useful in 90% of cases and add unnecessary distraction to the content.

Suggestions:

• make .no-line-numbers the default
• introduce line-numbers option
• show line-numbers when using markbind serve for development, allow forcefully hiding it with .no-line-numbers nevertheless
• introduce a style.line-numbers global config key of sorts to ease the migration / suit user preferences

[tlylt]

Looking through the initial conversations for this feature at PR: #991, it seems like prof Damith requested the line number version to be the default.

I suppose in an educational/instructional context, line numbers are helpful when referring to specific details of a code block. I can recall one occasion when the line numbers were helpful as I needed to refer to a piece of code on the CS2103T course website and talk over it.

Another point for consideration is that in most code editors(my estimate), line numbers are shown by default. At least for me, I am used to seeing a piece of code with line numbers on the left. Eg VSC:

(my 2 cents on this:)

[damithc]

After using the feature for a while, I'm split in the middle. I sometimes disable line numbers because they feel odd (e.g., when showing output rather than code, or when the code block has only a few lines) or to save space.
It's more like
20% of the cases : better to have line numbers
20% : better not to have line numbers
60%: OK either way

[tlylt]

Looking at a few code highlight/formatting services that I know, it does look like they go with no line number as a default.
E.g. Carbon

gatsby-remark-highlight-code

I think having a global line number setting will be useful. If we do change the default from line number to no line number, we might need to warn the user as this is somewhat a breaking change? I suppose the migration will be smooth as the user can simply use the global setting to keep line number as a default to keep everything the same.

On a side note, I just saw this feature of showing hidden characters in code blocks:

perhaps we can also consider this under #1496 ?

Edit:

show line-numbers when using markbind serve for development, allow forcefully hiding it with .no-line-numbers nevertheless

For this point, I feel that this may not be necessarily desired. In the two cases that line numbers are important:

• for aesthetic:
  • showing line numbers when using markbind serve may be weird as some user might specially want to see it without
• for actual need to refer to the line-number
  • user might assume that line number is shown when deployed but its actually shown only during development

[ang-zeyu]

I can recall one occasion when the line numbers were helpful as I needed to refer to a piece of code on the CS2103T course website and talk over it.

After using the feature for a while, I'm split in the middle. I sometimes disable line numbers because they feel odd (e.g., when showing output rather than code, or when the code block has only a few lines) or to save space.

I guess this is somewhat subjective.

I think one thing we can agree on is a global style.line_numbers config key of sorts though; (and then overridable on a case-by-case basis by line-numbers / no-line-numbers)

Many of our code examples in the user guide don't need line numbers, it would be quite convenient to hide them globally with this option. #1093

As for the default value, perhaps we can leave it be for now there isn't really a consensus. Might be nice to let new users know that "line numbers" are a feature as well.

show line-numbers when using markbind serve for development, allow forcefully hiding it with .no-line-numbers nevertheless

Same lines as above if we leave the default value be.

It might be helpful if the global configuration is flipped however, primarily for the more complex line highlighting features we have.

showing line numbers when using markbind serve may be weird as some user might specially want to see it without
for actual need to refer to the line-number

Also slightly more complex to configure, and line number highlighting is rather rare as well (but would be cumbersome to add .line-numbers before on the off-chance).

I don't really have a preference for this, and would be ok with the status quo! (1 global configuration for build/serve)

[tlylt]

Hi @ang-zeyu, to clarify the tasks for this issue:

• Enable a global config for line numbers
  • will style.codeLineNumbers be ok as oppose to style.line_numbers, to be aligned with variables like codeTheme?
  • it will default to true if not specified
  • e.g:
  • 
• Update docs and test cases
• Set line numbers for UG to be off by default

[ang-zeyu]

will style.codeLineNumbers be ok as oppose to style.line_numbers, to be aligned with variables like codeTheme?

👍, seems more consistent.

to clarify the tasks for this issue:

• a .line-numbers class option for overriding when style.codeLineNumbers=false

[damithc]

After using the feature for a while, I'm split in the middle. I sometimes disable line numbers because they feel odd (e.g., when showing output rather than code, or when the code block has only a few lines) or to save space.

After working on past code some more, I'm leaning more towards 'no line numbers' as the default behavior. :-p