[Docs] Add version footnote to tor.md #12384

[Docs] Add version footnote to tor.md

Added note to section 2, part -edits to /etc/tor/torrc- indicating this is only required for Tor version 0.2.7.0 and older, since section 3 states it is valid for Tor version 0.2.7.1 and newer. Added ref link from section 2 version footnote to section 3. Re-styled headings to work on GitHub -alternate heading style markup creation issue with numbered headings and thus headings and automatic heading links are broken-

Ref: Issue# 12376

Signed-off-by: Damian Williamson <willtech@live.com.au>

It makes sense to mention automatic hidden service creation and the command line options configuring it, however I disagree with the wording that it is redundant. Either specifying the hidden service yourself, or allowing it to be created automatically are still valid options, even with new Tor versions.

I haven't looked at this, but you should make the title meaningful to describe what you did, potentially why in 70 chars.

I like that "/doc/tor.md" (as in "Doctor, MD") is the filename. :D

@laanwj I had to look up the definition of redundant again after your comment and still think the word is accurate, I might be wrong. It may be that flagging the particular entries for /etc/tor/torrc as breaks things in the specific version of Tor may be more accurate with the limited testing I have performed.

The pull request has stemmed from the linked issue, I will follow up there.

EDIT: I see the heading edits, I will look at /contributing.md next.

It may be that flagging the particular entries for /etc/tor/torrc as breaks things in the specific version of Tor may be more accurate

That would mean there is another, separate issue that is not related to auto-Tor binding: the configuration directives required for setting up a hidden service changed at some version of Tor, and the old way fails?

FWIW I cannot corroborate this, the hidden services I've seen didn't require reconfiguration recently. But something might have changed when "new style" hidden services have been introduced, which are not supported by bitcoin's P2P network (see #9214). So maybe you need to choose to use old style explicitly.

I will look into it further on my installed version. The simple coverall solution seemed to be the edits I had made.

The simple coverall solution seemed to be the edits I had made.

There are various subtle privacy reasons why someone would want to configure their own hidden service instead of having bitcoind generate one. We can't just say "the manual way is deprecated". The automatic way is there for user convenience (and to get more tor-listening nodes), it does not replace it.

Alright, I do not take redundant to mean depreciated, I just understand redundant as not necessary. What would you suggest is a suitable edit?

BTW I cannot fault the given edits to torrc against either the examples in the default torrc file or the detailed configuration (of/for Tor) in nyx. No additional options lending themselves as potentially of assistance exist in nyx either.

I have updated the commit.

@laanwj re the linked issue #9214 you mentioned, I see plenty of lines like the following on Tor output:

15:10:12 [WARN] Fetching v2 rendezvous descriptor failed. Retrying at another directory.

I will add an additional commit later to reformat the document, headings to work with GitHub and check the line breaks and, add in internal ref link to section 3.

Additional commit added.

Please squash your commits according to https://github.com/bitcoin/bitcoin/blob/master/CONTRIBUTING.md#squashing-commits

You will have to excuse me a moment, that doesn't seem to be exactly the squash that I wanted. This will take some fixing.

Phew! All sorted.

utACK 8dcd724f4d8719a645606932e2a9289b521989a3

If you have a hard time finding people to review this, you might want to minimize the diff to just contain the tiny fixup.

Does that mean instead of squashing the commits I should have moved the trivial fixups to a separate PR?

utACK 8dcd724f4d8719a645606932e2a9289b521989a3

Should the A tag be removed from the commit? #12384 (review)

@Willtech yes.

That is fine but, I do not know who (if anyone) has what kind of final say here. Lots of people have contributor tags. I do understand consensus.

@Willtech if you feel that way just wait for more feedback.

Agree with @MarcoFalke - In principle I'm ok with this change in the OP ("add version mention") but please make it a minimal change. Remove the unnecessary formatting changes, and the unnecessary use of an anchor tag.

Normally something like this would be merged almost instantly. This is dragged enormously in time (and consuming needless review time) as you're seemingly trying to "rider" unrelated changes into a commit. If I may give a suggestion it is that this is not constructive - usually maintainers in open source projects will frown on this.

Done, gladly. Note that the headings are still fixed - all of them for consistency - otherwise the heading link wouldn't work on GH at least but, anywhere that I know of. FWIW my position is that it makes bollocks out of MD to remove the A tag since it makes the document operate consistently across different MD versions. HTML is valid in MD and such a careful use is warranted.

I do appreciate that I do not intend for such a simple thing to be time-consuming. This is my first interactive project on GH, my other experience working with development teams was in a company environment and admittedly a different environment in several ways.

Travis: mempool_persist.py | ✖ Failed | 9 s
on HOST=i686-pc-linux-gnu

utACK 39d2911918a90984738e90261cc272d35c60d0bc

Oh, I see the problem now: the ====== style cannot be used in combination with numbers in front of section titles, because it's interpreted as an enumeration. sorry - I still think this should have been a separate commit, but I won't hold this up longer: utACK 39d2911918a90984738e90261cc272d35c60d0bc

@laanwj The heading fixes (as well as the A tag) were originally a separate commit but, they got squashed as per requested. Generally, if I understand your reasoning, you would want to see one commit to add the text, another commit to fix the headings and, another to add the link to section 3?