Review pull request: reorganized Tor manual

Trac:
Username: swati

changed milestone to %Tor: 0.4.3.x-final

added component::core tor/tor documentation gsod milestone::Tor: 0.4.3.x-final owner::swati priority::medium reporter::swati resolution::implemented reviewer::catalyst severity::normal status::closed type::enhancement labels

Created the Pull request - https://github.com/torproject/tor/pull/1391.

Please review the Tor Manual for the following updates:

• Created a table of contents for this page. Users can navigate to different sections of the Tor Manual easily.
• Regrouped the following topics under the umbrella Reference section - Signals, Files, See Also, Bugs, Authors.
• Arranged the information in the Files section in tabular format. Please review whether this format works.
• Rearranged and formatted information in the Command-Line Options.
• Ongoing process - editing, proofreading and formatting the existing content to ensure correct grammar usage, standard terminology usage, and correct formatting of command/option names etc.

Trac:
Username: swati

Trac:
Username: swati

Trac:
Status: new to needs_review
Milestone: N/A to Tor: 0.4.3.x-final
Summary: Review pull request to Review pull request: reorganized Tor manual

Trac:
Keywords: N/A deleted, documentation, gsod added

We're still making a few changes to the Tor manual in 0.4,2, how are we going to avoid conflicts with this re-organisation?

Trac:
Type: defect to enhancement

Trac:
Status: needs_review to assigned
Owner: N/A to swati

Trac:
Status: assigned to needs_review

Replying to teor:

We're still making a few changes to the Tor manual in 0.4,2, how are we going to avoid conflicts with this re-organisation?

If there are conflicts with this merge in particular, I think we should resolve them by hand, unless Swati knows how and would rather do it.

In general, I think that maybe we should limit the number of manual changes we make while Swati is working on the reorganization, and we should encourage Swati to make frequent PRs so that the possible conflicts don't build up over time.

Trac:
Reviewer: N/A to nickm

Trac:
Reviewer: nickm to catalyst

Thanks for contributing these changes! I've taken most of the changes to the FILES, SEE ALSO, and BUGS sections and put them in a separate ticket, #32176 (moved). We can work on incorporating your other changes once we have that merged.

Generally, we tend to use imperative tense when describing things like command line options. (We also use imperative tense when documenting what C functions do.) For example, we prefer "Specify a file..." to "Specifies a file...". If we're not consistently using imperative tense for command line options, it might be better to fix the exceptions rather than change everything else to not use the imperative. What do you think?

I did notice that somehow the changes in e5cf1423fdc1707093885e5d74f0691de3365b55 got reverted in your patch. I think it would be good for us to understand how that happened. Please feel free to reach out to me or ahf for help with that if you need.

Created a separate ticket, #32277 (moved), containing the changes to the DESCRIPTION and COMMAND-LINE OPTIONS sections.

The only remaining changes seem to be some minor restructuring of section headings. Swati, please let me know if I've missed anything.

Need to check with swati if there are additional changes that we haven't yet incorporated that need looking at.

Trac:
Status: needs_review to needs_information

Implemented by #32277 (moved), #32176 (moved). Thanks, swati!

Trac:
Status: needs_information to closed
Resolution: N/A to implemented

closed

mentioned in issue #32176 (moved)

mentioned in issue #32277 (moved)

moved to tpo/core/tor#31943 (closed)