Opened 9 years ago

Last modified 8 days ago

#4310 new task

alphabetize torrc options within sections

Reported by: arma Owned by:
Priority: Medium Milestone: Tor: 0.4.4.x-final
Component: Core Tor/Tor Version:
Severity: Normal Keywords: documentation tor-client manpage easy 043-can
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
#32620closedPut man page options in smaller sectionsCore Tor/Tor
#32621newAdd automated checks to make sure man page options stay in alphabetical orderCore Tor/Tor
#32708closedcatalystmanpage: alphabetize General OptionsCore Tor/Tor
#32846closedTor Manual: Alphabetize Client OptionsCore Tor/Tor
#32928closedTor Manual: Split Circuit Timeout options into their own subsectionCore Tor/Tor
#32929closedTor Manual: Split Node options into their own subsectionCore Tor/Tor
#33188closedTor Manual: Alphabetize Server and Directory Server OptionsCore Tor/Tor
#33275closedTor Manual: Alphabetize Remaining Tor ManualCore Tor/Tor
#33339closedcatalystAdd script to check ordering of options in manpageCore Tor/Tor

Change History (18)

comment:1 Changed 9 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 9 years ago by nickm

Keywords: documentation added
Milestone: Tor: unspecified

comment:3 Changed 8 years ago by nickm

Keywords: tor-client added

comment:4 Changed 8 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 7 months 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 7 months 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 7 months 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 7 months ago by catalyst

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

comment:10 Changed 6 months 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 6 months ago by gaba

Status: newneeds_review

comment:12 in reply to:  5 ; Changed 6 months 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 6 months ago by teor

Milestone: Tor: unspecifiedTor: 0.4.3.x-final

comment:14 in reply to:  10 Changed 6 months 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.

comment:15 in reply to:  12 Changed 6 months ago by swati

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.

Last edited 6 months ago by swati (previous) (diff)

comment:16 Changed 6 months ago by catalyst

Status: needs_revisionnew

Moved the General Options alphabetizing work into child ticket #32708. We should create other child tickets for alphabetizing other sections.

comment:17 Changed 5 months ago by ahf

Keywords: 043-can added

comment:18 Changed 8 days ago by nickm

Milestone: Tor: 0.4.3.x-finalTor: 0.4.4.x-final

0.4.3 was released: Move non merge-ready 0.4.3 tickets to 044.

Note: See TracTickets for help on using tickets.