search

tulir / gomuks

A Matrix client written in Go.
https://maunium.net/go/gomuks
GNU Affero General Public License v3.0
1.37k stars 123 forks source link

gomuks manpage #333

Open aabacchus opened 2 years ago

aabacchus commented 2 years ago

I've translated the information about commands and keybindings from the wiki at https://github.com/mautrix/docs/tree/master/gomuks into a manpage. Information about environment variables and files is also included.

One part of the documentation was unclear: is markdown supported when sending rainbow text with the /rainbow command? It says "(markdown not supported)".

aabacchus commented 2 years ago

I tested gomuks, and markdown is supported in /rainbow mode.

tulir commented 2 years ago

Is there some way to convert the docs into a manpage automatically, or does it just have to be maintained by hand? (if it's the latter, maintaining the manpage might be a problem)

aabacchus commented 2 years ago

There's not really a satisfactory way to automatically convert them, but I have done the bulk of the work and further changes will only be minor. mdoc(7) is a very understandable language (http://manpages.bsd.lv/)

aabacchus commented 2 years ago

Comprehensive offline documentation is probably worth maintaining anyway...?

10leej commented 2 years ago

You can use pandoc to convert markdown to groff

aabacchus commented 2 years ago

Pandoc has a roff ms output device, but it probably requires a specifically-formatted markdown document to produce a usable manpage (I tried). Furthermore, the existing markdown documentation is split across a number of files with some extra information and some missing, compared to that desired from a manpage. You could use pandoc to convert to ms, then edit them together, but mdoc is a much easier language to use and much better suited to writing manpages. It is easy to only add any updates to the documentation I have written here. If it still seems like too much effort, I am very happy to change the necessary lines when needed, but you can learn mdoc here: https://mandoc.bsd.lv/mdoc/ and here: https://manpages.bsd.lv/mdoc.html. I'm not sure what to recommend to start learning ms.

mcepl commented 2 years ago

Pandoc has a roff ms output device, but it probably requires a specifically-formatted markdown document to produce a usable manpage (I tried).

Pandoc has man output format. See for example https://raw.githubusercontent.com/roddhjav/pass-import/master/share/man/man1/pass-import.md for an example of Markdown-based manpage.