Let's document: pacman

[navarroaxel]

The pacman command is a Swiss army knife to manage packages in Arch Linux-based OS and we should extend the current pacman page in tldr creating specific pages for its subcommands.

The issue with pacman is that its subcommands are arguments in uppercase and the lowercased arguments are specific for that subcommand. If we review the pacman -Syu command to upgrade the system: -y/--refresh and -u/--sysupgrade are specific arguments for pacman -S or we can run the same command in its long form: pacman --sync --refresh --sysupgrade.

• -D/--database (pacman-database: add page #5302)
• -F/--files (pacman-files: add page #5303)
• -Q/--query (pacman-query: add page #5269)
• -R/--remove (pacman-remove: add page #5273)
• -S/--sync (pacman-sync: add page #5268)
• -T/--deptest (pacman-deptest: add page #5304)
• -U/--upgrade (pacman-upgrade: add page #5295)

How should we name the page for -S/--sync argument? Maybe pacman-sync.md.

[bl-ue]

How should we name the page for -S/--sync argument? Maybe pacman-sync.md.

I thought of somthing else, pacman--sync.md. It's slightly uglier, but it would clearly distinguish between pacman sync and pacman --sync.

But maybe that distinction is not necessary.

[nikisix]

The git man documentation uses a single-dash separator between man <command>-<subcommand>.

Wouldn't the --sync flag be defined within the top-level pacman.md file?

I definitely understand pacman-sync.md being a thing.

[bl-ue]

@nikisix in an ordinary command, yes, but pacman doesn't have what are normally considered "subcommands"; instead -S/--sync is used just like a subcommand.

There are a lot of other options that are only available in the scope of the subcommand-like options (e.g. -T/--deptest, -D/--database, -F/--files), so there's not nearly enough space in pacman.md to document the useful capabilities of those "subcommands."

[sbrl]

Since I assume that pacman has long-form options for each of the "subcommands", I think pacman-SUBCOMMAND_NAME is a good option. e.g. pacman --sync becomes pacman-sync for example.

A bit unusual yes, but pacman doesn't appear to follow norms established by other subcommand-based applications.

[bl-ue]

@sbrl did you see my pacman--sync.md idea?

[sbrl]

I did, but I think keeping it similar to the existing subcommand system is perhaps better. But I do like the distinction you make there, I just think we should keep it simple.

[bl-ue]

Wow great job @navarroaxel—you actually got it all done and really quickly (less than a week!)

You get a 🥇 and ⭐✖️5️⃣   🌟✖️7️⃣!

[bl-ue]

Oops I forgot to close this 😄

[waldyrious]

Just logging my opinion, after the fact, that I'd initially be inclined to agree with @bl-ue's suggestion to name the pages pacman--sync.md, etc.

At the moment we use hyphenated page names for three command formats:

• Actual hyphenated commands, e.g. docker-compose.md --> $ docker-compose ...
• Space-separated subcommands, e.g. git-commit.md --> $ git commit ...
• flag-based subcommands, e.g. pacman-sync.md --> $ pacman --sync ...

Maybe we should consider a different convention to make things clearer? E.g.

• docker-compose.md
• git_status.md
• pacman--sync.md

Of course, that may break down if additional patterns come up (who knows, there may be some obscure tool that uses an even weirder format). Anyway, I thought I'd throw the idea out there to hear your thoughts.

[bl-ue]

It's a good idea, because things can start becoming complex if you want to use the names in some way ( subcommand suggestion, etc.) and you have parent commands with dashes and subcommands, e.g. virt-admin server-update-tls (#5425) 😄

[sbrl]

Hmm, interesting ideas here @bl-ue, @waldyrious!

It's an awkward one, because there's no set standard for how it's done. If we included any underscores, I'd suggest a client update because it's extra work to do shift + - as opposed to just hitting the space as we have currently.

Currently clients basically do echo "${page_name}" | tr ' ' '-', so perhaps pacman--sync would be the better solution to this issue here?

We could even do 3 dashes, because then you'd be able to do this:

tldr pacman --sync

....and it would be translated into this:

pacman---sync.md

Thinking about it some more here, I think I'd actually suggest that 3 dashes would be the most optimal solution because it wouldn't require a client update or require users to learn any new syntax.