Opened 6 months ago

Closed 5 months ago

#20885 closed defect (fixed)

Portions of the tor.1 man page and html doc formatted incorrectly

Reported by: jryans Owned by: jryans
Priority: Medium Milestone: Tor: 0.3.0.x-final
Component: Core Tor/Tor Version:
Severity: Normal Keywords: man, doc, review-group-14
Cc: Actual Points:
Parent ID: Points:
Reviewer: Sponsor:

Description

Some portions of the tor.1 doc don't join paragraphs correctly, leading to strange output styles, especially in html view, which appears to default to <pre> blocks when asciidoc is confused by the syntax.

Child Tickets

Change History (7)

comment:1 Changed 6 months ago by jryans

  • Owner set to jryans
  • Status changed from new to assigned

comment:2 Changed 6 months ago by jryans

  • Status changed from assigned to needs_review

comment:3 Changed 6 months ago by dgoulet

  • Keywords man doc added
  • Milestone changed from Tor: 0.3.??? to Tor: 0.3.0.x-final
  • Status changed from needs_review to needs_information

Thanks jryans! Question:

Why SocksPortFlagsMisc and ExitPolicyDefault and ORPortFlagsExclusive don't show in the generated man page or HTML? So what are they for?

I'm asking because those could be confused with torrc option so I would be careful not to introduce section title that looks like such :S.

comment:4 Changed 6 months ago by jryans

  • Status changed from needs_information to needs_review

Sorry, I should have explained that up front!

These "fake" sections were the only way I could see to have a paragraph be indented in the style of a first-level list item when it comes after a second-level / nested list item. All the other approaches I attempted led to the paragraph glued onto the content of the last second-level list item or formatted as a code sample, both of which are not what's intended. (There seems to be no explicit way to "end" the second-level list, so you have to find some way to trigger that implicitly. asciidoc is strange.)

I noticed there is a pre-existing usage of this technique with OtherSocksPortFlags. So anyway, these sections could really be named anything, since they don't appear in the output. Any suggestions for less confusing names, or do they seem okay?

comment:5 Changed 5 months ago by jryans

Maybe <X>Footer is a good name for these "hidden" sections?

comment:6 Changed 5 months ago by nickm

  • Keywords review-group-14 added

comment:7 Changed 5 months ago by nickm

  • Resolution set to fixed
  • Status changed from needs_review to closed

This looks good to me. Merging; thanks!

Note: See TracTickets for help on using tickets.