#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 12 months ago by jryans

Owner: set to jryans
Status: newassigned

comment:2 Changed 12 months ago by jryans

Status: assignedneeds_review

comment:3 Changed 12 months ago by dgoulet

Keywords: man doc added
Milestone: Tor: 0.3.???Tor: 0.3.0.x-final
Status: needs_reviewneeds_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 12 months ago by jryans

Status: needs_informationneeds_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 11 months ago by jryans

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

comment:6 Changed 11 months ago by nickm

Keywords: review-group-14 added

comment:7 Changed 11 months ago by nickm

Resolution: fixed
Status: needs_reviewclosed

This looks good to me. Merging; thanks!

Note: See TracTickets for help on using tickets.