Opened 5 years ago

Closed 5 years ago

#10978 closed task (implemented)

Decide on a source format for the Tor Browser User Manual

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

Description

In order to turn the “short user manual” into the Tor Browser User Manual, we need to decide on a source format before starting the conversion.

Requirements:

  • It needs be able to generate HTML. Ideally HTML that will embed CSS and images directly.
  • It needs either be directly understood by Transifex or by po4a in order to be translatable.
  • It needs to directly support or be easily scriptable in order to have conditional sections depending on the operating system and the target language.
  • It needs to be plain text as we want to be able to have Git reviews.

The discussion is inherently tied to the tools that are able to convert that format to something else…

Child Tickets

TicketStatusOwnerSummaryComponent
#10979closedlunarResearch if pandoc + po4a are good tools for a Tor Browser User Manual in MarkdownApplications/Tor bundles/installation
#11124closedlunarResearch if Mallard would be a good candidate for the Tor Browser User ManualApplications/Tor bundles/installation

Change History (8)

comment:1 Changed 5 years ago by lunar

Docbook is the usual suspect as it is used by many free software project already. po4a can read it nicely and we can turn it into XSLT easily: there's plenty of XSLT stylesheets to turn it into HTML.

I would rather see something based on Markdown as it is a lot nicer to edit and review. Also, Tails documentation is already in Markdown so that might encourage us to share common parts.

comment:2 Changed 5 years ago by lunar

Using po4a and pandoc might work if we want to use Markdown. That needs to be tested: #10979.

comment:3 Changed 5 years ago by lunar

Status: newaccepted

comment:4 Changed 5 years ago by lunar

Project Mallard looks quite interesting. See also the introduction manual on flossmanuals.net.

comment:5 Changed 5 years ago by phoul

Cc: phoul added

comment:6 Changed 5 years ago by lunar

I think Mallard is a very nice markup language and has all the features we want:

  • The language is well designed. Its principles are sound and likely to create good documentation.
  • Helping translators creating nice translations is all integrated thanks to W3C ITS.
  • It supports conditional text for different platforms.
  • It supports integrating outside element pretty easily (like the Tor Browser version).

The only thing we might miss, but I'm not sure, is a single HTML file. We could already ship EPUB easily and a single HTML file is only some XSLT hacking away.

Please have a look at the proof of concept and comment.

comment:7 Changed 5 years ago by lunar

It has been a week and I only had positive feedback so far. Let's wait two more days before we settle on Mallard.

comment:8 Changed 5 years ago by lunar

Resolution: implemented
Status: acceptedclosed

So Mallard it is.

Note: See TracTickets for help on using tickets.