hi,
synthe:
> Dear Tails-dev/documentation team,
There's a lot to be said about the proposed documentation changes
(e.g. style & spelling); I'll mention a few issues below but this will
need a full review by our technical writers at some point (and when
we're there you'll want to follow
https://tails.boum.org/contribute/merge_policy/#submit).
> Please find below an initial proposal for a (for now) documentation-only approach for
> this issue.
Thanks a lot!
I think this approach is good enough for a first iteration if, and
only if, there's a solid plan to come up with something better soon
after, because this approach has a few serious issues that I don't
want to see in Tails for more than a major release cycle (~3 months):
- The security slider level is not configurable.
- It's hard to make the code evolve, e.g. if the content of the
Desktop file has to be adjusted later on: there will be numerous
copies of the code in places we don't manage ourselves.
- It makes the doc unnecessarily complicated for the vast majority of
users who'll have to skip the added tip.
Now, our next major release is scheduled for March 6, so you have
plenty of time to implement something better :)
> The first part creates the gnome autostart directory under /live/.../.config , and touches a .desktop file, set executable. The second command adds six lines to the file:
> [Desktop Entry]
> Path=.tor-browser/profile.default
> Exec=bash -c 'echo -e "user_pref(\"extensions.torbutton.security_slider\", 1);"'>prefs.js
Do we really need bash (as opposed to a more POSIX'ish shell like
/bin/sh → dash)?
Do we really need -e here?
How about using ">>" instead of ">", to be compatible with whatever
similar hack users might already have implemented?
> +can use the dotfiles persistence feature to
> +implement this.
I think we need to point to the corresponding documentation.
> The two bash commands below can be copy-pasted into a Terminal
> +window, at the <em>amnesia@amnesia:</em> prompt.</p>
This sentence does not match our doc style guide (passive voice) and
more generally is inconsistent with the rest of our doc. See how we
tell users to run commands elsewhere.
> +<p><em>Be aware that this results in much functionality, including Javascript and
> +HTML5 playback, being completely disabled,
If there's some doc online about the security slider (in the Tor
Browser manual perhaps?), let's point to it.
> thus rendering numerous websites
> +unusable until the slider is set back to its default setting Low</em>.</b></p>
I would say "unless you set the slider to a lower level" (avoid
passive voice, take into account that some websites work just fine at
Medium level).
> +<p>Create a new Gnome autostart folder containing an empty, executable file
> +named <b>torbutton.desktop</b>:</p>
s/Gnome/GNOME/ (or simply drop it: I'm not sure it's useful)
+ see my comment above wrt. how to introduce commands.
> +<p><code>mkdir -p \
> +/live/persistence/TailsData_unlocked/dotfiles/.config/autostart \
> +&& touch $_/torbutton.desktop && chmod 700 $_</code></p>
I believe the same result can be achieved with one single command
(instead of 3) and without the $_ bashism:
install -D --mode 0700 /dev/null \
/live/persistence/TailsData_unlocked/dotfiles/.config/autostart/torbutton.desktop
> +<p>Now populate the <b>torbutton.desktop</b> file with the necessary parameters,
> +so that the Torbutton slider is set to High as Tails boots up, and the <em>amnesia</em>
> +user is logged in to the Gnome desktop environment:</p>
I think we use "start" instead of "boot", please check the terminology
we commonly use elsewhere in our doc. Also, please avoid passive voice
and technical details that are not needed (e.g. I bet most users don't
know that "the amnesia user" is themselves, so "you" would be more
straightforward to understand).
> +<p><code>echo -e '[Desktop Entry]\nPath=.tor-browser/profile.default
I would suggest dropping -e and passing the string within
double-quotes. Incidentally, this would probably simplify a lot the
quoting of the next lines, which is quite hard to follow currently.
> +Exec=bash -c '"'"'echo -e "user_pref(\"extensions.'\
> +'torbutton.security_slider\", 1);"'"'"'>prefs.js
I don't get it: you're calling bash only to call echo, and the command
output redirection is outside of the argument passed to bash -c.
Either we need bash to do the ">" (and then >prefs.js must be passed
to -c) or we don't (and then we can drop "bash -c"), no?
Note that I didn't test this so I might be confused :) So first,
let's clarify: did you try following this doc (compiled with ikiwiki)
step-by-step from Tails?
Cheers,
--
intrigeri
