search

zmkfirmware / zmk

ZMK Firmware Repository
https://zmk.dev/
MIT License
2.82k stars 2.85k forks source link

docs: Better document the layer `display-name` prop. #2559

Closed petejohanson closed 1 month ago

Nick-Munnich commented 1 month ago

In keymaps/index, could you also edit/add on to these lines:

petejohanson commented 1 month ago

In keymaps/index, could you also edit/add on to these lines:

* L47, second sentence

I'm not sure I'd want to detract from the core concepts being explained there, IMHO.

* L133

Done.

* L148

Done.

Nick-Munnich commented 1 month ago

I'm not sure I'd want to detract from the core concepts being explained there, IMHO.

I think either we don't distract at all, in which case we should remove the sentence, or we mention both methods of naming layers. I'd be happy with either, not a big fan of the in-between especially since (arguably) display-name is the more important of the two.

petejohanson commented 1 month ago

I'm not sure I'd want to detract from the core concepts being explained there, IMHO.

I think either we don't distract at all, in which case we should remove the sentence, or we mention both methods of naming layers. I'd be happy with either, not a big fan of the in-between especially since (arguably) display-name is the more important of the two.

But both things are relevant, and I think the "refer by number" is a key part of the keymap file format that's more relevant to understand than the display-name.

Nick-Munnich commented 1 month ago

I'm not sure I'd want to detract from the core concepts being explained there, IMHO.

I think either we don't distract at all, in which case we should remove the sentence, or we mention both methods of naming layers. I'd be happy with either, not a big fan of the in-between especially since (arguably) display-name is the more important of the two.

But both things are relevant, and I think the "refer by number" is a key part of the keymap file format that's more relevant to understand than the display-name.

I'm referring to the second sentence, I'd want to keep the first. Perhaps the right approach is to move the "Defines to Refer to Layers" section that is linked into the index file as a subsection of the layer section? Might be a bit irrelevant for this PR though, and the rest looks good to me.