Opened 8 years ago

Last modified 10 days ago

#4310 needs_revision task

alphabetize torrc options within sections

Reported by: arma Owned by:
Priority: Medium Milestone: Tor: 0.4.3.x-final
Component: Core Tor/Tor Version:
Severity: Normal Keywords: documentation tor-client manpage easy
Cc: catalyst, swati Actual Points:
Parent ID: Points: 3
Reviewer: Sponsor:

Description

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.

Child Tickets

TicketStatusOwnerSummaryComponent
#32620newPut man page options in smaller sectionsCore Tor/Tor
#32621newAdd automated checks to make sure man page options stay in alphabetical orderCore Tor/Tor

Change History (14)

comment:1 Changed 8 years ago by atagar

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

comment:2 Changed 8 years ago by nickm

Keywords: documentation added
Milestone: Tor: unspecified

comment:3 Changed 7 years ago by nickm

Keywords: tor-client added

comment:4 Changed 7 years ago by nickm

Component: Tor ClientTor

comment:5 Changed 3 years ago by nickm

Keywords: manpage easy added
Points: 3
Severity: Normal
Summary: Order of Tor man page entries is confusingReorder tor manpage entries within sections
Type: defecttask

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.

comment:6 Changed 5 weeks ago by arma

Cc: catalyst added

letting catalyst know about this ticket, so they can close it if the upcoming gsod work resolves it, or else point it out to the gsod person.

comment:7 Changed 5 weeks ago by catalyst

Is this specifically about the ordering of section headings? Or the ordering of individual config option names in the config file section?

comment:8 Changed 5 weeks ago by arma

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.

comment:9 Changed 3 weeks ago by catalyst

Cc: swati added
Summary: Reorder tor manpage entries within sectionsalphabetize torrc options within sections

comment:10 Changed 11 days ago by 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.

comment:11 Changed 10 days ago by gaba

Status: newneeds_review

comment:12 in reply to:  5 Changed 10 days ago by teor

Status: needs_reviewneeds_revision

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.

comment:13 Changed 10 days ago by teor

Milestone: Tor: unspecifiedTor: 0.4.3.x-final

comment:14 in reply to:  10 Changed 10 days ago by teor

Replying 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 and #32621 for these tasks.

Note: See TracTickets for help on using tickets.