Skip to content

Conversation

@arialdomartini
Copy link

This is surely a personal preference, but I find tables more readable and convenient to reference than bullet point lists.

So instead of having list of operators and functions like this:

https://github.com/jj-vcs/jj/blob/master/docs/revsets.md#operators
https://github.com/jj-vcs/jj/blob/master/docs/revsets.md#functions

I find this layout more tidy and easy to consult:

https://github.com/arialdomartini/jj/blob/tables/docs/revsets.md#operators
https://github.com/arialdomartini/jj/blob/tables/docs/revsets.md#functions

When descriptions are too long, though (see function remote_bookmarks, for example), it could be nice to have a shorter description in the reference table, with a separate paragraph with further details. Reason why I refrained from applying tables to Built-in Aliases.

Finally, unfortunately Markdown does not support multi-line cell contents, so you might hate the resulting source code of this PR.

Checklist

If applicable:

  • I have updated CHANGELOG.md
  • I have updated the documentation (README.md, docs/, demos/)
  • I have updated the config schema (cli/src/config-schema.json)
  • I have added/updated tests to cover my changes

@arialdomartini arialdomartini requested a review from a team as a code owner September 23, 2025 08:55
@google-cla
Copy link

google-cla bot commented Sep 23, 2025

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

@glehmann
Copy link
Contributor

I think it wouldn't help in all the situations. Is it still readable in jj help -k revsets, with ~80 terminal width?

@arialdomartini
Copy link
Author

Good question. I haven't checked.

I also don't like how the line in each table cell stretches so long.

@mnil
Copy link

mnil commented Sep 24, 2025

Isn't this change going against the Google markdown styleguide regarding tables?

Avoid using tables when your data could easily be presented in a list.

https://google.github.io/styleguide/docguide/style.html#tables

@arialdomartini
Copy link
Author

Seems so. It should be closed then.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants