I do man parsing for one of my projects and it is as painful as HTML parsing. OK the syntax is less complex but you still end up with the problem that the body of text is designed for human consumption so the formatting doesn't always follow the same rules from one man page to the next (tokens aside).

This means that while it is easy enough to pull flags from the man pages, offering usage suggestions is something too tricky to handle in an automated on-demand fashion.

I did toy with the idea of starting a new project porting man pages to a new document format designed specifically for utilities parsing (eg a JSON format with standardised fields). However even that would be a massive job to maintain without the support from other developers upstream.

But I'm open to other suggestions if anyone has any?

We kind of experimented with parsing man files, but it'll never be as good as manually crafted suggestions: you can do stuff like suggest changed files for "git add", tokens from diff for "git commit" message, show process names for "kill", and much more. The vision is to have manual suggestions for at least the most popular tools.