Tables instead of bullet point lists in documentation #7574
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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 toBuilt-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:
CHANGELOG.mdREADME.md,docs/,demos/)cli/src/config-schema.json)