Opened 13 days ago

Closed 8 days ago

#33688 closed enhancement (implemented)

README cleanups

Reported by: bduszel Owned by:
Priority: Very Low Milestone: Tor: 0.4.4.x-final
Component: Core Tor/Tor Version:
Severity: Minor Keywords: doc
Cc: Actual Points:
Parent ID: Points:
Reviewer: catalyst Sponsor:

Description

Hello everyone,
I just started playing around with Tor a few days back so as one could expect I started with README.1st.md file. I realized that different *.md files are not consistent style-wise so I decided to clean them up a bit.

Brief summary:

  • no empty line at the very beginning of the file,
  • single empty line between sections (sometimes there were two)
... end of the sentence.

New Section
----

rather than

... end of the sentence.


New Section
----
  • external links use [name](url) format,
  • there is no single space in front of the section name
 Foo
===

is changed to

Foo
===

Which fixes syntax issues in editors like GNU Emacs with enabled markdown preview.

  • I tried to check all links (local and external) and fix the ones which were broken.

For example the Tor proposal process inside README.1st.md or doc/WritingTests.txt were changed to .../doc/HACKING/WritingTests.md in few places).


At the very end of README.1st.md file there are some TODO (I think?) sections. I wrapped them around in "TODO" section.

TODO
-----------------------

XXXXX also describe

doc/HACKING/WritingTests.md

torguts.git

torspec.git

The design paper

freehaven.net/anonbib

XXXX describe these and add links.

However I am not sure if these are still needed there. Most of these topics are mentioned already in this file and linked to other files (WritingTests, torspec, etc.).

Child Tickets

TicketTypeStatusOwnerSummary
#33689enhancementclosedREADME cleanups

Change History (11)

comment:1 Changed 13 days ago by bduszel

I apologize for two, identical tickets. Trac failed during creation of the first one (there was an error message) but it seems it was created anyway.

Duplicated ticket: #33689

comment:2 Changed 13 days ago by bduszel

Unfortunately I cannot upload my patch file to trac. I will push my branch somewhere and link it here when ready.

comment:4 Changed 13 days ago by teor

Component: Core TorCore Tor/Tor
Keywords: doc added
Milestone: Tor: 0.4.4.x-final
Status: newneeds_review
Version: Tor: 0.4.3.3-alpha

Thanks for this patch!
Someone should review it this week.

To help the reviewer, can you answer this question:

What dialect of Markdown are you using?
The links starting with "..." don't work on GitHub Markdown.

comment:5 in reply to:  4 Changed 13 days ago by bduszel

Replying to teor:

Thanks for this patch!

No... thank YOU!

Replying to teor:

What dialect of Markdown are you using?
The links starting with "..." don't work on GitHub Markdown.

I put internal links between backquotes to format them as a code. They should not be treated as any kind of interactive links so I assume GitHub displays them correctly.

The "..." part has been already used in a few places so I just decided to stick with it. It was there before my changes for example inside CodingStandardsRust.md in the following part:

You MUST follow the standards laid out in `.../doc/HACKING/CodingStandards.md`,
where applicable.

https://github.com/torproject/tor/pull/1832/files#diff-7cfb3aad5f33e266cf09d29e5347c58d

comment:6 Changed 12 days ago by dgoulet

Reviewer: catalyst

comment:7 Changed 10 days ago by catalyst

Status: needs_reviewneeds_revision

Thanks for the patch! It mostly looks good. I have a few minor comments:

We don't consistently use the .../doc/HACKING reference style to refer to locations in the source tree. I'm not sure if we want to adopt it. Is that a syntax that some other markdown language treats specially? I think the best alternative might be to make all pathname references be relative to the top of the source tree, e.g., doc/HACKING instead of .../doc/HACKING.

The "underline" of the section headings should be the same length as the title. After your patch, some of them are longer than their corresponding title strings. (Some of them were already longer, though.) Alternatively, we could move toward using the ## Section name style, which doesn't require variable-length underlines.

comment:8 Changed 9 days ago by bduszel

Thanks for the review catalyst.

I updated MR with your suggestions:

  • references to the top of the source tree are updated (doc/HACKING instead of .../doc/HACKING)
  • underlines are replaced with # section marks, I tried to adjust section levels along the way too

MR is the same. Please take a look when you will have a free minute or two.
https://github.com/torproject/tor/pull/1832


I found some issues with code blocks in some *.md files (some files use code blocks syntax, some do not). First of all, it's not consistent but what's really bad is when *.md file is being displayed incorrectly. You can find an example of what I'm saying in CodingStandards.md under How we log changes section.
https://github.com/torproject/tor/blob/master/doc/HACKING/CodingStandards.md#how-we-log-changes

Part of the git log output is still displayed as a regular text rather than a formatted code block. I plan to check all code blocks under doc directory later on (different ticket).

comment:9 in reply to:  8 Changed 9 days ago by catalyst

Status: needs_revisionmerge_ready

Replying to bduszel:

Thanks for the review catalyst.

I updated MR with your suggestions:

  • references to the top of the source tree are updated (doc/HACKING instead of .../doc/HACKING)
  • underlines are replaced with # section marks, I tried to adjust section levels along the way too

MR is the same. Please take a look when you will have a free minute or two.
https://github.com/torproject/tor/pull/1832

Thanks! Looks good.

It might be a good idea to open a new ticket for what I think are the remaining items on the README.1st TODO:

  • link to design paper (with description)
  • link to anonbib (with description)

I found some issues with code blocks in some *.md files (some files use code blocks syntax, some do not). First of all, it's not consistent but what's really bad is when *.md file is being displayed incorrectly. You can find an example of what I'm saying in CodingStandards.md under How we log changes section.
https://github.com/torproject/tor/blob/master/doc/HACKING/CodingStandards.md#how-we-log-changes

Part of the git log output is still displayed as a regular text rather than a formatted code block. I plan to check all code blocks under doc directory later on (different ticket).

Thanks! Please do open a separate ticket for these issues.

comment:10 Changed 9 days ago by bduszel

Tickets created:

  • #33741 (code blocks)
  • #33742 (design paper and anonbib for README.1st.md)

I plan to start working on these this weekend.

comment:11 Changed 8 days ago by nickm

Resolution: implemented
Status: merge_readyclosed

Merged to master!

Note: See TracTickets for help on using tickets.