alphabetize torrc options within sections
Once upon a time the man page entries were alphabetical. Then we started adding a few near the other ones when it made sense. Now it's a mishmash of alphabetical-except-when-we-decided-not-to-do-it-that-way.
We should take a step back and think about a way to organize the options into categories so it's possible to a) get a sense of what all you can configure, and b) find the thing you're looking for.
Activity
changed milestone to %Tor: unspecified
This isn't entirely right - the man page is organized by categories. I have some interest in this since arm scrapes the man page's content, though worst case scenario is that arm falls back to the bundled configuration information.
I've filtered the options down to a few for a 'config.important' flag (totally subjective) and written short summaries for all of the options (accuracy may vary due to some very cryptic man descriptions) in case that helps: https://gitweb.torproject.org/arm.git/blob/HEAD:/src/settings.cfg
I think the a little work here might go a long way.
If you want to submit a patch, please make sure that it does nothing else besides reorder the manpage entries; otherwise, it will be hard to review.
Trac:
Summary: Order of Tor man page entries is confusing to Reorder tor manpage entries within sections
Points: N/A to 3
Keywords: documentation tor-client deleted, documentation tor-client manpage easy added
Reviewer: N/A to N/A
Type: defect to task
Severity: N/A to Normal
Sponsor: N/A to N/A
It's not about section headings. It's about each little piece of the man page (RelayBandwidthRate, Nickname, etc) being in a seemingly random order within their section. Like, they used to be alphabetized, and then they became "alphabetized but with some exceptions", and then it became mostly exceptions. Why is Sandbox right before Socksport? Maybe because "sa" comes before "so". Why are both of those after HTTPSProxyAuthenticator? Maybe because Socksport came after HTTPProxy back when there were far fewer torrc options. But then later we've got LogTimeGranularity in between RunAsDaemon and TruncateLogFile. Like, what the heck is our reasoning for the order we've picked. And the answer is that it just all accumulated.
I think this is a good first step, but I'd like to suggest some useful next steps:
- put some options into smaller categories, or sub-categories, so related options are near each other, and
- add automated checks to make sure the options stay in alphabetical order (within categories)
These might be tasks for other tickets, or long-term tasks. That's ok.
This is the PR to review: https://github.com/torproject/tor/pull/1567 .
Trac:
Status: new to needs_reviewHi swati,
Replying to nickm:
If you want to submit a patch, please make sure that it does nothing else besides reorder the manpage entries; otherwise, it will be hard to review.
This patch re-orders manpage entries, but it also makes whitespace changes, for example: https://github.com/torproject/tor/pull/1567/files#diff-53a84e5af0d074614e6d722a25038cb7R277
Some of these whitespace changes appear to be incorrect: https://github.com/torproject/tor/pull/1567/files#diff-53a84e5af0d074614e6d722a25038cb7R283
Please make a pull request that only re-orders manpage option entries, and doesn't make any other changes.
If you are using git, all the changes should be highlighted as "moved" with
git diff --color-moved.Trac:
Status: needs_review to needs_revisionReplying to teor:
I think this is a good first step, but I'd like to suggest some useful next steps:
- put some options into smaller categories, or sub-categories, so related options are near each other, and
- add automated checks to make sure the options stay in alphabetical order (within categories)
These might be tasks for other tickets, or long-term tasks. That's ok.
I opened #32620 (moved) and #32621 (moved) for these tasks.
I am sorry. My intention was to only re-order man page entries. I didn't realize how in the process of copying and pasting, the whitespace changes emerged. I'll try to figure out how this happened. Should I close the PR and submit this again?
This again is the drawback of not being able to see the man-pages being rendered. In HTML, these whitespaces do not show up as errors. They look fine.
Replying to teor:
Hi swati,
Replying to nickm:
If you want to submit a patch, please make sure that it does nothing else besides reorder the manpage entries; otherwise, it will be hard to review.
This patch re-orders manpage entries, but it also makes whitespace changes, for example: https://github.com/torproject/tor/pull/1567/files#diff-53a84e5af0d074614e6d722a25038cb7R277
Some of these whitespace changes appear to be incorrect: https://github.com/torproject/tor/pull/1567/files#diff-53a84e5af0d074614e6d722a25038cb7R283
Please make a pull request that only re-orders manpage option entries, and doesn't make any other changes.
If you are using git, all the changes should be highlighted as "moved" with
git diff --color-moved.Trac:
Username: swatiMoved the General Options alphabetizing work into child ticket #32708 (moved). We should create other child tickets for alphabetizing other sections.
Trac:
Status: needs_revision to newmentioned in issue #32620 (moved)
mentioned in issue #32621 (moved)
mentioned in issue #32708 (moved)
mentioned in issue #32846 (moved)
mentioned in issue #32928 (moved)
mentioned in issue #32929 (moved)
mentioned in issue #33188 (moved)
mentioned in issue #33275 (moved)
mentioned in issue #33339 (moved)
moved to tpo/core/tor#4310 (closed)
mentioned in issue tpo/core/tor#32620 (closed)
mentioned in issue tpo/core/tor#32621 (closed)
mentioned in issue tpo/core/tor#32708 (closed)
mentioned in issue tpo/core/tor#32846 (closed)
