-
Notifications
You must be signed in to change notification settings - Fork 1.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Organize main highlighters alphabetically #839
base: master
Are you sure you want to change the base?
Conversation
Thanks for the patch. I don't think alphabetical sorting would be the best choice. Instead, we could group the entries semantically — e.g., all styles related to the command word together — as in Please use meaningful log message ( |
@danielshahaf Thanks for taking a quick look and the reply :)
Sure, most of the repos I've contributed to have squashed and used either their own commit message or the commit message in the PR title. I'll be mindful of your practices moving forward. |
I think the question is if the docs are intended more for reference or pedagogy. For the former I would strongly argue alphabetical is best. For the latter grouping semantically would be better (perhaps with different levels of bullet points to denote fallback?). The rest of the file doesn't feel like a reference; so while I am fond of alphabetized lists, I think @danielshahaf is correct. Perhaps something like Commandsarg0 etc Argumentspath ... Expansionscommand substitution Not sure what to call things like assign, redirection, comments and the like. |
I assume that by "reference" you mean a random-access use case ("What's the
"Miscellany"? "Other syntactical elements"? |
For better readability and usability (seeing all possible options), alphabetical sorting is easier for users.