Opened 5 years ago

Closed 5 years ago

#10979 closed task (implemented)

Research if pandoc + po4a are good tools for a Tor Browser User Manual in Markdown

Reported by: lunar Owned by: lunar
Priority: Medium Milestone:
Component: Applications/Tor bundles/installation Version:
Severity: Keywords: SponsorO
Cc: Actual Points:
Parent ID: #10978 Points:
Reviewer: Sponsor:


Pandoc can turn almost any markup into another markup. The HTML output can be made self-contained using the --self-contained command-line option.

po4a will extract content and merge translations for plain text. It can also do that for Docbook which might be more precise.

The pipeline would be: Markdown → Docbook → Extract / merge translations → HTML.

The --filter option would allow use to easily select sections based on OS or language but is not available on wheezy or the TBB build VM. “Pragma style comments” and sed might do the trick in the short term.

Child Tickets

Attachments (1)

tor-browser-user-manual-markdown-poc.tar.gz (4.8 KB) - added by lunar 5 years ago.
Quick PoC of Markdown + pandoc + po4a

Download all attachments as: .zip

Change History (3)

comment:1 Changed 5 years ago by lunar

Status: newaccepted

Changed 5 years ago by lunar

Quick PoC of Markdown + pandoc + po4a

comment:2 Changed 5 years ago by lunar

Resolution: implemented
Status: acceptedclosed

The attached PoC used one of Tails' documentation page. It looks like it could work. But I am now convinced that it will need a certain amount of manual fiddling to take care of conditionals (parts that should only be seen on the Windows version of the manual) and external content (TBB version numbers). It doesn't feel like the best option.

Note: See TracTickets for help on using tickets.