Decide how to incorporate Tor Browser Manual pages into Tor Browser
We want the Tor Browser User Manual to ship with Tor Browser. We need to decide how the manual will be presented to the user, including what file format the user will be accessing.
Activity
In https://trac.torproject.org/projects/tor/ticket/11124 we decided on using the mallard markup language to build the Tor Browser User Manual.
Mallard pages can be opened with a program called yelp. One option might be to ship yelp with the Tor Browser, and let the user open the manual with yelp. The advantage is that this takes full advantage of Mallard's capabilities and intuitive workflow. I do not know if there are working Windows and Mac yelp packages, or how big they are. If someone finds this out before I do, please post the answer here.
Another option is to compile the mallard pages into html format. An advantage is that these pages could be linked to from the about:tor page and viewed in the browser. The drawback is that users need to be able to find and access the manual in the event that Tor Browser fails somehow, which means we'll need an alternative to the in-browser experience. Encouraging users to open the Tor Browser manual in Firefox or Chrome leads to grave security issues.
It's been suggested the manual be converted to pdf format either using html2pdf or compiling the mallard files to Latex and converting to pdf. The advantage is that we would have one file which would be intuitive to click on and read. The drawback is that a pdf file would detract from some of the interactive aspects of mallard that influenced us to select it as the user manual framework in the first place.
From http://en.flossmanuals.net/introduction-to-mallard/prerequisites/
Currently, the yelp‑tools package is not available for OS X or Windows operating systems.
Trac:
Parent: N/A to #10974 (moved)-
I believe the manual should be shipped in the Tor Browser as HTML files. There should be an option inside the Tor Browser to access the manual, and also a link in the folder.
With the manual entirely self-contained and not using any external resources by default, I would need you to elaborate on:
Encouraging users to open the Tor Browser manual in Firefox or Chrome leads to grave security issues
Replying to lunar:
I believe the manual should be shipped in the Tor Browser as HTML files. There should be an option inside the Tor Browser to access the manual, and also a link in the folder.
With the manual entirely self-contained and not using any external resources by default, I would need you to elaborate on:
Encouraging users to open the Tor Browser manual in Firefox or Chrome leads to grave security issues
Here's my concern: the user downloads Tor Browser. After it's installed, she clicks on the HTML files she finds to read them. Her default browser opens. The user mistakes the default browser for Tor Browser, and begins browsing, thinking she is anonymous. https://trac.torproject.org/projects/tor/ticket/10399 is not-entirely unrelated.
I could see this situation arising especially in cases where Tor Browser fails to open. When users are frustrated, they prioritize getting online above thinking through the possible technical issues. A frustrated user is more likely to convince herself that her problem has been solved "somehow" when it hasn't been. The familiar browser interface and network capabilities contribute to her confusion.
My current thought is that we reduce this risk by shipping the Tor Browser manual as a PDF file. The manual can still be accessed in browser, linked to from about:tor, and opened with PDF.js.
If Tor Browser fails to open, the manual is still easily accessible and located in a visible place (in the Tor Browser folder). Users will also not be forced to resolve conflicting cognitive clues from the application interface.
Replying to mttp:
My current thought is that we reduce this risk by shipping the Tor Browser manual as a PDF file. The manual can still be accessed in browser, linked to from about:tor, and opened with PDF.js.
I tend to agree that PDF might be the best choice... but are the common PDF readers (e.g., Adobe Reader) trustworthy from an anonymity point of view? I suppose most people are using them already.
If Tor Browser fails to open, the manual is still easily accessible and located in a visible place (in the Tor Browser folder). Users will also not be forced to resolve conflicting cognitive clues from the application interface.
Note that after #11641 (closed) is fixed, the Docs subdirectory will be a little harder to find (on Linux and Windows it will be inside Browser/TorBrowser/ and on Mac OS it will be inside Tor Browser.app/TorBrowser/). We could add an "Open Docs Folder" button to Tor Launcher's setup wizard if we can find a place for it in the UI.
-
Replying to mttp:
Here's my concern: the user downloads Tor Browser. After it's installed, she clicks on the HTML files she finds to read them. Her default browser opens. The user mistakes the default browser for Tor Browser, and begins browsing, thinking she is anonymous. https://trac.torproject.org/projects/tor/ticket/10399 is not-entirely unrelated.
I could see this situation arising especially in cases where Tor Browser fails to open. When users are frustrated, they prioritize getting online above thinking through the possible technical issues. A frustrated user is more likely to convince herself that her problem has been solved "somehow" when it hasn't been. The familiar browser interface and network capabilities contribute to her confusion.
Understood. How about having a specific HTML file to offer the manual outside the Tor Browser that would contain an
<iframe>surrounded with “Tor Browser User Manual” and a big fat warning “This is only the manual, not the actual Tor Browser. This browser provides no anonymity.”? I guess we could even use JavaScript to provide a warning if users try to browse somewhere else.I'm not necessarily opposed to a PDF, but I fear that it will be far less convenient to read given Mallard's design goals.
Replying to mcs:
Note that after #11641 (closed) is fixed, the Docs subdirectory will be a little harder to find (on Linux and Windows it will be inside Browser/TorBrowser/ and on Mac OS it will be inside Tor Browser.app/TorBrowser/). We could add an "Open Docs Folder" button to Tor Launcher's setup wizard if we can find a place for it in the UI.
We can still make a shortcut/symlink in the main folder to something deeper in the tree, right?
-
Replying to lunar:
We can still make a shortcut/symlink in the main folder to something deeper in the tree, right?
Yes. The only problem is that we will not be able to update links at the top (outside of the Firefox/Browser directory) via the upcoming automatic update mechanism. But if we include a link to the Docs/ folder that should be OK for now.
Replying to mcs:
I tend to agree that PDF might be the best choice... but are the common PDF readers (e.g., Adobe Reader) trustworthy from an anonymity point of view?
Evince, which is free software, is available for Mac and Windows, as well as Linux, so the Tor Project does not necessarily have to endorse proprietary, closed source software.
Replying to lunar:
Understood. How about having a specific HTML file to offer the manual outside the Tor Browser that would contain an
<iframe>surrounded with “Tor Browser User Manual” and a big fat warning “This is only the manual, not the actual Tor Browser. This browser provides no anonymity.”? I guess we could even use JavaScript to provide a warning if users try to browse somewhere else.This will require the user to process additional information than if the manual were presented as a pdf. It would also require additional work to implement. What benefit do you think we would we get in exchange for this additional cost?
I'm not necessarily opposed to a PDF, but I fear that it will be far less convenient to read given Mallard's design goals.
I've looked at a few different applications for generating PDF files. Using wkhtmltopdf seems like a pretty good option to me. Once the Mallard .page files are built to html, they can be fed into wkhtmltopdf as arguments. The output pdf file is fully linked according to Mallard's design. I'm attaching an example pdf file for your consideration. Note that for the PDF file to be linked, one must create it using the binary available from the project's website, NOT the package available in the Ubuntu or Debian repositories.
-
To generate a PDF, the mallard2latex converter should be investigated. It would be better than requiring an external application.
I doesn't appear to me that PDF significantly address the threat model that has been described earlier. If a PDF contains a link to an external website, clicking on that link will open the system browser. We could make all external links inactive, but then we could do the same when generating HTML…
Anyway, I'd rather continue discussing options when the manual is thicker and we can actually try stuff.
-
Ok, here's another idea that I wish to run here. Dear M. Claus Santa (isn't what
mcsstands for?), your opinion would be well appreciated.In the Tor Browser archive, let's add another program labeled “Tor Browser User Manual”. The program would be a lot like the “Start Tor Browser” one. But instead of starting the Tor Browser, it would start a locked down browser to display the manual, using a dedicated profile or a
-appthingy. This locked down browser would look quite like Yelp, with no menu, no address bar It would be prevented from making any network connection. Instead, when an external link is clicked, it would ask the user to copy the URL and paste it manually somewhere else.The manual would also be available from the Tor Browser and would not have the later restriction.
I believe we would get the most flexibility out of this. One downside is that when Tor Browser doesn't load at all (e.g. WebRoot or wrong Linux arch), users will have to browse the online version. Or maybe we also ship a PDF with external web links inactive.
Replying to lunar:
Ok, here's another idea that I wish to run here. Dear M. Claus Santa (isn't what
mcsstands for?), your opinion would be well appreciated.In the Tor Browser archive, let's add another program labeled “Tor Browser User Manual”. The program would be a lot like the “Start Tor Browser” one. But instead of starting the Tor Browser, it would start a locked down browser to display the manual, using a dedicated profile or a
-appthingy. This locked down browser would look quite like Yelp, with no menu, no address bar It would be prevented from making any network connection. Instead, when an external link is clicked, it would ask the user to copy the URL and paste it manually somewhere else.Although I am not Santa Claus I think this sounds like a lot of overkill for the purpose of letting the user view a manual. Especially as you still are dependent on a loading Tor Browser as you noted.
-
Replying to gk:
Although I am not Santa Claus I think this sounds like a lot of overkill for the purpose of letting the user view a manual. Especially as you still are dependent on a loading Tor Browser as you noted.
I agree that lunar's proposal sounds like quite a bit of work. And I worry that we will miss something and there will be a hole that leaks info to the network if we attempt to create a locked down/specialized browser (Firefox is pretty good at accessing the network even when we don't want it to do so).
What about opening the help in viewers included with the operating system, e.g., within Yelp, or Mac OS Preview, or [something else] on Windows? If you are worried about people following links, don't include any external links in the manual. But I guess PDF is also OK with those restrictions.
-
We had a discussion about what exactly we need to decide in this ticket in our weekly meeting yesterday. We came up with three distinct topics:
-
What format should the manual included have (It seems so far HTML is the favorite one?)?
-
Where should it be made visible to the user? Ideally, the user would be able to consult the manual even if Tor Browser is not properly starting-up due to censorship restrictions.
-
We need a process for shipping an up-to-date manual in every Tor Browser release. Especially shipping outdated translations seems like a thing we need to avoid. How could that process look like? Who would be responsible for which part in this case?
Let's start from the questions/ideas above taking the previous comments in this ticket and the respective thread on tbb-dev (https://lists.torproject.org/pipermail/tbb-dev/2014-May/000051.html) into account.
Trac:
Cc: Lunar, Phoul, mrphs, Sherief, karsten, mcs, brade, arthuredelstein to Lunar, Phoul, mrphs, Sherief, karsten, mcs, brade, arthuredelstein, lnl, isabela -
Replying to gk:
- What format should the manual included have (It seems so far HTML is the favorite one?)?
My feeling is HTML is preferable, because we already have an HTML version at https://tb-manual.torproject.org. Having two versions (say, HTML and PDF) would be an extra maintenance burden. Also it seems to me that PDFs are harder to read on-screen.
- Where should it be made visible to the user? Ideally, the user would be able to consult the manual even if Tor Browser is not properly starting-up due to censorship restrictions.
I think we should be able to add a help button in the initial tor launcher dialog that opens a window to display the HTML manual pages. This could be a XUL window containing a widget, but no location bar, toolbar, tabs, or extensions. I think such a window won't risk proxy bypass, as Tor Browser's networking prefs are already set to use a SOCKS proxy, and will simply fail if tor is not yet ready.
- We need a process for shipping an up-to-date manual in every Tor Browser release. Especially shipping outdated translations seems like a thing we need to avoid. How could that process look like? Who would be responsible for which part in this case?
My suggestion would be to have two versions: a stable and an alpha manual (#20665 (moved)). When a user-facing change is made in stable or alpha browsers, the authors or committers of the browser patch should notify Phoul with a ticket under component Community/Tor Browser Manual. My understanding is that we are going to rely on Transifex translators to keep the translated manuals up to date. If we continuously update the alpha manual as features are added or changed, then it will generally give the translators more time to translate each new piece of text. When an alpha version becomes stable, then the alpha translations can be promoted to stable as well.
-
Replying to arthuredelstein:
I think we should be able to add a help button in the initial tor launcher dialog that opens a window to display the HTML manual pages. This could be a XUL window containing a widget, but no location bar, toolbar, tabs, or extensions. I think such a window won't risk proxy bypass, as Tor Browser's networking prefs are already set to use a SOCKS proxy, and will simply fail if tor is not yet ready.
Data point: this won't help when users are prevented to start Tor Browser entirely by anti-virus softawre (WebRoot is one of them, IIRC). Maybe it's ok to not cover all cases.
Replying to lunar:
Replying to arthuredelstein:
I think we should be able to add a help button in the initial tor launcher dialog that opens a window to display the HTML manual pages. [...] Data point: this won't help when users are prevented to start Tor Browser entirely by anti-virus softawre (WebRoot is one of them, IIRC). Maybe it's ok to not cover all cases.
Thanks for this good point. Maybe we could also add a shortcut to the html pages somewhere for users to click and open in another browser? I guess that would mean we probably shouldn't bundle them in the torbutton xpi, but somehow locate them inside the Tor Browser directory.
-
Could still be worthwhile to do. Adding additional folks for getting the ticket on their radar
Trac:
Keywords: N/A deleted, ux-team added
Parent: #10974 (moved) to N/A
Cc: Lunar, Phoul, mrphs, Sherief, karsten, mcs, brade, arthuredelstein, lnl, isabela to Lunar, Phoul, mrphs, Sherief, karsten, mcs, brade, arthuredelstein, lnl, isabela, pili mentioned in issue #18905 (moved)
mentioned in issue #20639 (moved)
mentioned in issue #28526 (moved)
mentioned in issue #31539 (moved)
mentioned in issue #34451 (moved)
mentioned in issue tpo/applications/tor-browser#18905 (closed)
