Indicate available subcommand pages

[dreua]

For rarely used command like nmcli it would be nice to indicate the availability of tldr pages for subcommands. (The current nmcli page is not adding much value imo and I did not expect it to have subcommand pages until I stumbled upon them here on the repo.)

I checked git and aws for examples but couldn't find an indication. May I add something like "See also: tldr nmcli device or tldr nmcli connection" to the nmcli page and is there a style guide for that?

Can/Should this be implemented client side? Including it in the pages however has the advantage that we can hand-pick the most important subcommands (i.e. those that someone not knowing the subcommands by heart would find most helpful) and choose the order they appear in.

[bl-ue]

I would love for this feature to be implemented client-side. 👍🏻

Of course, with our monolith network of clients, it would take a while to get them all updated...but since it's just an optional feature we could probably add it at any time to the tldr-node-client, and maybe the tldr-python-client, too.

[schneiderl]

If we decide to do this, how would it be done?

Should we assume that any pages that start with the current page name are subcommands of the command the page describes? (I'm sorry about how this sentence was written, I could not find any way to make it clearer haha)

[dreua]

Sounds reasonable to me, do you see a problem with that approach?

[bl-ue]

Also, for the pages that seem to be possible subcommands, check if the title has a space or dash—a space would indicate a command and a subcommand like git status while a dash would indicate a command only like gpg-zip.

Of course, we would need to check for cases where there's a dash and a space, e.g. in my-cmd-subcommand.md the title would be my-cmd subcommand, etc.

[bl-ue]

I wonder if we would ever introduce YAML frontmatter into our markdown files...I know that's a big change (@waldyrious @sbrl) but it would be really useful for this sort of thing, and also for marking translated languages, supported OS's, etc.

[sbrl]

Some clients have a search feature, that allows you to search for a specific substring in a page. This could be used as a workaround for now.

For indicating a see also, we do have a general convention on that. It goes in the description directly above any more information link like this:

> See also `foo`.

...optionally with a description:

> See also `foo`, which does bar.

Obviously this isn't useful for a large number of subcommands though - for that I'd suggest using a search feature if one is built into your client (I use tldr-bash-client, which has a search feature)

[iTrooz]

Would you accept a PR implementing the approach discussed above in https://github.com/tldr-pages/tldr-python-client ?

[kbdharun]

Hi, this is the first time I stumbled upon this issue (since I started watching all repos in org, honestly I should check the backlog more often xD).

---

Regarding referencing subcommands, we have three approaches we can take in this repo:

• When there is a main page where we need to show some quick commands or global flags (i.e git) but need additional pages for subcommands, in that case, we use a subcommand mention to highlight the commands.
• We use See also: `command1`, `command2`. template to reference similar commands, aliases and subcommands (and occasionally we couple them with a description as @sbrl suggests).
• We convert the whole page to reference the subcommands i.e the nmcli page referenced in this issue has been converted to follow this approach.
  • We do the same for commands having name collision. (i.e. just).

We have documented this in the style guide and the contributing page will go through them again and update it if any of the above approaches aren't documented.

---

Should this be added on the client side?

I think this would probably cause redundant work as we already reference most of them directly here (so I am closing this issue). While we can't reference all the commands of a large utility, we already reference the important commands.

Let's say a client implements matching the subcommands based on the main command name (i.e git-clone.md is related to git.md) and displays them along with the command output then it would cause issues for utilities/tools with hundreds of commands like aws.

For clients to still show/reference all commands you can build an index (along with completion support for it, but it would make the client a bit slow as observed in the Node client) and show below the command's output like:

Similar commands: `command1`, `command2, `command3`, `command4`, `command5`, ...

This can't be implemented with the Python client as it directly fetches the page from GitHub and doesn't build an index or use our existing index. Since the syntax can change on different pages we can't do this in the render side either. If you are interested, feel free to work on adding search flag support to our Python client using the existing index (maybe with autocompletion too).

---

Miscellaneous (note for maintainers)

• The node client has support to display the See also: line separately while the main output shows it too, IMO this is redundant and we should remove the additional separation from the rendered output. Will work on a PR to change the behavior soon.

Reference image:

• We should remove the additional index-building step in the Node client and update it to use our prebuilt index instead this would almost half reduce the time to view a page not in old cache. I could work on this, but I am not familiar with Node myself so leaving it up for grabs 😄. Seems like the building index step does additional things for autocompletion i.e. checking work frequency, etc. So we can leave it as it is and focus on improving the time instead.

[sbrl]

Ref client-specific changes, I recommend opening an issue against their repositories to discuss those. But generally seems cool!

[kbdharun]

Ref client-specific changes, I recommend opening an issue against their repositories to discuss those. But generally seems cool!

Yeah, Will open up issues in the node client tomorrow.