API, docs, and the universe

[edwinsage]

I recently decided that I could be useful by helping to reorganize the documentation, as MC has grown a lot and there's an immense amount of info that has sort of just gotten glommed in to the readme/help. It turns out this is opening up a lot of rabbit holes, so I figured I'd start talking about what I'm seeing and thinking before going too far. This is a messy brain-dump, as I think I need to do this before I can figure out how to consoliate these ideas.

Initial idea: Organize the various command-line arguments into groups, such as "General Options" and "Messaging". This is working, but it's also turning up a number of ideas of how to refactor how some of the arguments work, which would be an API change.

Questions this opens:
Using semantic versioning can feel weird with major version changes popping up frequently for seemingly minor changes, but I think it really draws attention to the fact that every time you change your mind about how to handle input or output, you quite possibly break other programs that rely on yours. While updating version numbers helps communicate that, the real thing it pushes is being very deliberate about how your API works. I feel like MC is at the point where it needs a rethink of how to structure itself so that future changes are unlikely to change the API.

What are your feelings on adopting more of a git flow or github flow? I keep waffling on how necessary this is, and it's also largely a question of how much structure is too much for you personally. Really I think the problem I'm trying to solve is how to avoid the situation where a new minor feature is added, but then needs a small tweak that is an "API change" that would force a version bump.

Since the documentation is huge, what about making --help output just a terse explanation of arguments, and put the full explanation in a man page or other document? Man pages are a rabbit hole all their own, but one I've been meaning to go down for some time. A good example of this split is wget, which is similarly a complex program that must handle many options dealing with external servers; compare wget --help with man wget.

I'm interested in putting work into any/all of these, but don't want to get too far ahead of myself.

[8go]

adopting more of a git flow or github flow?

Can you @edwinsage explain this further? What do you mean by that? Example?

Some CLI programs distinguish between -h and --help with -h being short and --help being the full longer help info.

And yet others have something like --help --foo giving then the help details on argument --foo.

Having a man page adds complexity. Installation, ... How would man pages work on Windows? On Mac? I personally think the fewer pieces, the better. I think the question is more on "how to present the info". Having or not having a man page, I think, is not the issue, because just having the same info in a man page solves little to nothing, IMHO.

maybe we can give the user a few choices what kind of help info she/he wants:

• -h short summary (like a table of contents)
• --help <topic> only arguments relevant to a specific topic like room, settings, send, listen, user, ...
• --help the full details
• --examples examples

[edwinsage]

I'm personally not a fan of making -h and --help have different behavior. This breaks the user expectation that short options are just abbreviations of long names. Also, I think it works just as well to make --help display either the default help with no arguments, or a subcategory if given an argument.

So, it sounds like a traditional man page is not the way to go, for the reasons you listed. I still think it's worth considering making some sort of external document for the verbose details and examples; this could be Markdown, HTML, text, or some other simple to read format, and be included alongside the README... actually, it would probably make the most sense to just keep using the README and not add a new document at all.

I think my real goal is to see the --help output be short and to-the-point. When I just want a quick reminder whether the argument is --get-room-state or --room-get-state, I don't want to scroll through a thousand lines of output to find it; I should be able to look at a hundred line summary of all options. But if I'm trying to understand what features MC has and how they might interact, I want a full, detailed explanation. Two use cases, two different help texts. I don't feel it's important to have all the information accessible directly from the command line, do you?

[8go]

I'm personally not a fan of making -h and --help have different behavior.

Just pointing out a fact. clap is by far the most-used Rust package for CLI argument handling, sort of like argparse in Python. And clap distinguished between -h and --help, resulting in all/most Rust CLI programs to have this behavior. I did not know this until recently, I also always thought -h and --help would be identical.

When I just want a quick reminder whether the argument is --get-room-state or --room-get-state, I don't want to scroll through a thousand lines ...

Good point.

• a good terse summary is useful
• aliases can be set so that BOTH --get-room-state and --room-get-state will work

I don't feel it's important to have all the information accessible directly from the command line, do you?

I personally enjoy it, to have all or nearly all information accessible directly from the command line.
A preference. But that does NOT exclude that it is available somewhere else.
You can see it as in addition it is available also via CLI.

Only available via CLI is obviously not a good idea, because how would you read the installation instructions then? Or decide whether or not you actually want this tool or not. Hence, README and hence installation instructions on pypi.org.

could be Markdown, HTML, text, or ...

I personally prefer Markdown. Web browsers are not available everywhere or in all situations, like remote work, headless servers, etc.

How do other people consume this kind of info? In general, for other projects I mean. Without evaluating, listing all, good or bad:

• man page
• --help CLI
• README on Github
• something like https://matrix-nio.readthedocs.io
• ???

While you @edwinsage miss a terse summary, sometimes I miss a better description of which arg goes/affects which arg. Sort of like "if you use --foo, then consider using --bar, but --foo collides/incompatible with --baz".

Above all it would be nice to get the opinion of other matrix-commander users. People, please chime in and give feedback!

[edwinsage]

I've already spoken up, but to state it clearly I like to have quick access to basic syntax with --help, and usually resort to a man page for more detailed information. That said, it's not rare for me to use a web browser to read an online version of a man page, or to read other related documentation.

As far as the way forward, I agree that using Markdown for detailed documentation is probably a reasonable way forward. It's common, rendering tools already exist, and it's even designed to be readable in its plain text form. Putting it in README.md seems good, because then it's rendered on GitHub by default and it's in an obvious place.

So here's what looks to me like the best option right now:

• Put complete usage details in README.md, possibly including examples.
• If it's possible to do so in a sensible way (considering that there are multiple distribution methods at the moment), maybe add a --manual option that just prints the contents of README.md to the screen. Alternatively, maybe have that part of README.md somehow get generated via a script from the help text inside MC?
• Put a terse help output on --help. Add a note at the end that "For more detailed information, see README.md or run matrix-commander with --manual."

I think this achieves several things:

• Information is not duplicated. Terse help and detailed help are fundamentally different pieces of writing, and each exists in just one place (though automated duplication such as Markdown->HTML is totally fine).
• It should be fairly low-surprise for users. Many users will see the README first; it will have all the details and mention the short help on --help. Many users will try --help, which will include instructions on how to get more information. Both of these things are fairly common practice, so it should be a low mental load on users to remember where to look for what.
• It provides the documentation in two importantly different forms. No one should miss having terse or verbose documentation, because they both exist.

I think we're at least in agreement that it probably makes sense to have both verbose and terse help somewhere, so I'll probably start working on organizing the content and pointing out design/API considerations I see as I do.

[8go]

Just a few more remarks,

• I am not necessarily against HTML or webpages, as long as they can be generated automatically. Maybe something like Markdown-to-html or some other tool. I am against manual labor. Automation is the key.
• general feeling, we should follow Linux philosophy. Instead of putting logic into mc, let's be modular and use other small existing tools; e.g. summary? Why not create a summary via matrix-commander -h | grep -e "^ -" or matrix-commander -h | grep -E "^ -" | awk -F ' ' '{print $2}' or something similar. A script could generate this summary and automatically put it into README and into an option --help-summary. Wow, 91 options!
• what are good tools to automate documentation? Most Py documentation tools are geared towards documenting APIs like functions, methods, datastructures. Is there tools for documenting CLI?

[8go]

Just as a side note, I stumbled across mdbook https://github.com/rust-lang/mdBook, it converts Markdown into HTML and is used by all Rust programs. I assume all of https://docs.rs is generated with it. I am not implying or suggesting to use it now. I just thought it useful background into. It has smart search built into it, etc.

One can write books with it too (see Rust by Example).

[8go]

The "Usage" section of README.md is currently auto-generated during the release process via a script in ./scripts.

[8go]

check out v5.1.0

• file help.short.txt : https://github.com/8go/matrix-commander/blob/master/help.short.txt
• new tool matrix-commander-tui
  • please test it, see also announcement note, or search readme.md for tui

[8go]

check out v5.2.0

there are now 4 levels of granularity for documentation:

• usage
• help
• manual
• readme

all 4 are "inside" mc, as well as in form of online files on Github.

[8go]

@edwinsage What is your feedback on the new --help ?

Do you feel like improving the README.md file?

Things like:

• creating TOC
• creating links to jump back and forth between section ends and TOC
• restructuring
• improving in general

I found this on how to make links in Github MD.

[Custom foo description](#foo)

# Foo

In the above case, the Foo header has generated an anchor tag with the name foo

Note: just one # for all heading sizes, no space between # and anchor name, anchor tag names must be lowercase, and delimited by dashes if multi-word.

[click on this link](#my-multi-word-header)

### My Multi Word Header