On Mon, Nov 15, 2021 at 12:45:18AM +0000, Thomas Adam wrote: > On Mon, Nov 15, 2021 at 01:36:15AM +0100, Dominik Vogt wrote: > > While we're at it, much of the markup could be removed. The > > manpage is partially unreadable because too many words have markup > > (especially for the style command). > > Yeah. I suspect this is a holdover from when the original man page was in raw > Groff format, where such markup was quite common, and that's carried over from > Dockbook -> Asciidoc.
Yes, it's mostly my fault. I'm super correct with such things, but bad at writing readable technical documentation. > > (Also, the Style docuementation should possibly be put in a > > separate manpage. The monolithic manpage is intimidatingly large. > > Even I am reluctant to use it. Maybe like the zsh manpages: One > > manpage per larger topic, and if you really insist on an ugly big > > one, there's also "man fvwmall". Should be generated from a > > single source though.) > > That's now significantly easier thanks to Asciidoc being in use, I agree -- :-) I love Asciidoc. Since I became aware of it around 2000, I've not ever used anything else (unless forced by customers). > and it's a subject which has come up over the years. I like the idea -- and > we can definitely start with styles. As you say, that's the bigger area of > documentation. > I've also never been a fan of styles being documented like this: > > Foo / Bar / Baz > > Where the last one in the group (Bqz, in this case) is meant to be the > default. I suspect that convention hasn't been honoured properly for years, > and we can certainly regroup these things to make it mor readable. The good new is: Since I'm almost the only person who ever wrote styles in the last two decades, this should mostly be good. I always was very pedantic with that. > > > I think it's best to try and keep line length to <=80 characters > > > > Sounds good. If we could add the emacs config for that at the > > start of the file that would help. (Just press alt-q to reformat > > a block.) > > I've been trying to move away from that convention in favour of using > editorconfig: > > https://editorconfig.org/ > > There's already a .editorconfig file in the top-level git repo. Interesting. Need to read up on how to use it from emacs. > We could add > the relevant section for .adoc files and then that would also apply to Vim as > well (which is what I use). Ciao Dominik ^_^ ^_^ -- Dominik Vogt
