ipinfo man page

[Taimoor-12]

Includes the man page written in roff markup, parsing the man page to print formatted --help output on the terminal and handling the installation of the man page to the user's local machine.

[Taimoor-12]

@UmanShahzad

[UmanShahzad]

• Can you show how the new -h looks now?
• We've made our "source file" be the actual manpage format now basically, and it's actually not a very good format to write in, as compared to markdown for example.

I'm looking at this with fresh eyes and thinking it may not be worth the maintenance burden to maintain the docs like this. If we change things, even testing the CLI's -h will become cumbersome as we'd have to re-build and re-run each time.

What I recall the original motivation on this was, it was to allow ipinfo's help to be similar as git - when you do -h, it gives a short help, and when you do --help, it opens up a reader like less and shows extremely detailed documentation with many examples and explanations.

Can you check how git does --help like that but keeps -h as a short desc? It's actually using a manual page for --help but how do we just 'open' the manpage with --help transparently like that?

[Taimoor-12]

This is how -h or --help for ipinfo looks like:

Currently, git --help also prints something on the terminal instead of opening the man page:

This is what git -h looks like:

Upon further research into how Git maintains documentation for its git command, it appears that the source file is a plain text file written in AsciiDoc format—a more human-readable option. This text file contains the same sections as the man page, including NAME, SYNOPSIS, DESCRIPTION, COMMANDS, OPTIONS, EXAMPLES, etc. This file serves as the source for both the man page (often converted from AsciiDoc format) and the --help output. In either case, we would need to custom-parse the source file to extract the desired sections for printing the --help output. Instead of parsing the potentially cumbersome man page format, we can parse this more human-readable file.

[Taimoor-12]

@UmanShahzad should we proceed with this new approach where the source file is in the AsciiDoc format?

[UmanShahzad]

@Taimoor-12 let's try an approach that doesn't involve any actual man file, but acts like one.

The main benefit I personally find from a man page is that it's very detailed and searchable using commands you find in pagers like less.

So can we find a way where -h (short help) is the same as today, but --help (long help) ends up printing a different help string for the same command that's the "full detailed" one and that runs in a pager? The key part I don't know myself is how would a CLI open something in a pager. I've seen e.g. psql open up a pager when the results returned from making a query are too long, for example, so it must be possible.

[Taimoor-12]

@UmanShahzad If I understand correctly, we want to put all the information about the ipinfo command and its subcommands, including examples and options, into a simple text file. When --help is passed, we will pipe the contents of that file to less. For -h, we can continue using the current hard-coded string version. Is that accurate?

[UmanShahzad]

Even for --help it can be a hardcoded string inside Go (or embedded via Go embed), but just paged instead of printed, so we can freely write pages and pages of details and examples.

[Taimoor-12]

What kind of a structure should we follow for the hardcoded string that will be paged with less when --help is used?

[UmanShahzad]

@Taimoor-12 we can follow our own structure at this point - anything that just allows us to communicate a lot more examples than currently. It could be the same structure but with just more details, explaining all edge cases, etc.

[Taimoor-12]

The output for --help after the new commit is this:

[UmanShahzad]

Oh we're just executing less quite literally. Is that how this is done in CLIs like psql or something to achieve the pager?

[Taimoor-12]

I think yes. I encountered a CLI called pgcli and went through their docs on the website. They mentioned that the default pager for displaying long result sets is less. In their config file, users can explicitly specify the pager value, and the specified pager would be executed to display result sets (or simply less if nothing is specified). That's what I understood

Through the use of flags and when --help is invoked, I directly executed less on the long string.

[UmanShahzad]

Alright it's good, but note that the pager is configurable I believe by some env var - can you research if that's the case and then use that? If not lemme know

[Taimoor-12]

Yes the pager can be set through an env var called PAGER which is a common name to set the pager tool. We can read its value and use that pager for the string. If the user has set no PAGER value, we can then use less as a pager.

[UmanShahzad]

Alright let's incorporate that!