User Guide

[gagbo]

Hello!

Is there a user guide for people who want to make layouts?

What's the importance of specifying the geometry? (why does it matter to use ERGO or ANSI or ISO?)

What's the difference between using base + altgr keys vs. using the full key in the toml file? Does it change the signification of each corner in the keys in the layout? How so?

How are working dead keys? Are they always using "Compose" feature and nothing else? Does that mean that *μ always means "greek compose" somehow? I don't know if that exists though. Or should I provide the matching list of dead keys manually ?

Looking forward to playing with this!

[fabi1cazenave]

This is a very valid concern. Thanks for raising it, and sorry for my latency.

I tend to think that nobody ever reads the documentation unless it’s exactly where it’s needed. So I’d be in favor of writing this documentation as TOML comments, directly in the template files in the layouts directory:

• layouts/ansi.toml is simple template with no AltGr, no dead keys
• layouts/prog.toml is a good template with AltGr and standard dead keys
• layouts/intl.toml is a specific template to explain what the 1dk layer is about

And to make sure the documentation is there for the user when they edit a TOML layout, we could have a kalamine create command with a few options in order to create the template with all the relevant documentation comments:

kalamine create layout.toml
kalamine create layout.toml --altgr --geometry=iso
kalamine create layout.toml --altgr --1dk --geometry=ergo

This create command could also start the web server that has just been added to kalamine (#38), either with a --watch flag or by default.

WDYT?

[gagbo]

Yeah seems good. As one of the few people who actually read manuals/docs when trying new things out I’m a bit sad, but if I’m the only reader in the end that’s fair not to want to bother

[fabi1cazenave]

Out of curiosity, where would be a good place for such a documentation for you ?

I’m not really a Python person, but is there a place where such a documentation would be expected in a PyPi module ?

[gagbo]

Not sure since kalamine really is a binary and not "just a lib", so I suppose making the --help bigger might be an option, otherwise I don't really think it's possible to have it in the source in a way that's easily accessed, so a man page or a readthedocs (or any) website might be the way.

Or just have the help message point a link to the repo with the example files (or a path to demo files installed locally when used with pip)