Project

General

Profile

Feature #15120

Feature #14548: Fix issues identified in the expert review done by jaster on our installation instructions

Improve styles of command lines and their output

Added by sajolida over 1 year ago. Updated 8 days ago.

Status:
In Progress
Priority:
Low
Assignee:
Category:
-
Target version:
Start date:
12/27/2017
Due date:
% Done:

0%

Feature Branch:
web/15120-improve-command-line-presentation
Type of work:
Website
Blueprint:
Starter:
Affected tool:

Description

We are using them for different things:

  • Commands to execute
  • Example commands (not to be exectured as such)
  • Output of commands
  • Placeholders inside commands

These could have different styles.


Related issues

Related to Tails - Feature #15126: Improve visibility of the difference in the two runs of diskutil Rejected 12/27/2017
Blocks Tails - Feature #15941: Core work 2018Q4 → 2019Q2: Technical writing Confirmed 09/11/2018

History

#1 Updated by sajolida over 1 year ago

  • Related to Feature #15126: Improve visibility of the difference in the two runs of diskutil added

#2 Updated by sajolida over 1 year ago

  • Feature Branch set to web/15120-improve-command-line-presentation

Great work! This proof-of-concept looks much better than what we had in the past.

I think we should apply this everywhere and:

  • Do a bit or archaeology to see what should be cleaned up or replaced in our CSS and other documentation pages regarding pre, code, p.pre, p.code.
  • Apply the same improvements to other documentation pages.
  • See if we want a different treatment for command line examples (the ones we give as examples with the placeholders replaced but that are not meant to be executed as such). For example, is it possible to make that text impossible to select?

#3 Updated by cbrownstein over 1 year ago

  • Assignee set to cbrownstein

#4 Updated by cbrownstein over 1 year ago

  • Status changed from Confirmed to In Progress
  • Assignee changed from cbrownstein to sajolida
  • QA Check set to Info Needed

Hello,

See if we want a different treatment for command line examples (the ones we give as examples with the placeholders replaced but that are not meant to be executed as such). For example, is it possible to make that text impossible to select?

What do you think about this?

https://github.com/cbrownstein/tails/tree/web/15120-improve-command-line-presentation

Output and examples are no longer selectable. I've tested in Chrome and in Firefox.

N.B. In Firefox, even though the text can't be selected, the pointer turns into an I-beam (text selection) cursor. This doesn't happen in Chrome.

#5 Updated by sajolida over 1 year ago

  • QA Check changed from Info Needed to Ready for QA

#6 Updated by sajolida over 1 year ago

  • Blocks Feature #15411: Core work 2018Q2 → 2018Q3: Technical writing added

#7 Updated by sajolida about 1 year ago

  • Target version set to Tails_3.7

#8 Updated by sajolida about 1 year ago

  • Target version changed from Tails_3.7 to Tails_3.8

#9 Updated by sajolida about 1 year ago

  • Assignee changed from sajolida to cbrownstein
  • Priority changed from Normal to Low
  • QA Check changed from Ready for QA to Dev Needed

Sorry for taking so long to review your branch.

I added two commits on top of it and merged it because it's already much better than what we had. I added a42c12a6fc and d66d5d7cf3.

Now, if you're still interested in doing a bit more work on this, here are some more stuff that you could improve in our CSS:

  • I like how you prevented selecting example commands. But I'm not sure we should apply the same to command-output. I mean... we added this as a safety mechanism to prevent people from copying commands that could break their system if they didn't replace the placeholders correctly. But this safety measure doesn't apply so much to command output.
  • I'd try to get rid of the 'pre' class. It's used almost only for command line output and using only your new classes would reduce the overall amount of code and complexity. To spot them: git grep 'class="pre' -- "*.*m*"
  • Maybe move 'pre, p.pre {' (and others?) in local.css closer to your new styles.
  • But we should keep the style of the pre tag as we'll continue using it in other places (for example contributors documentation and blueprints).
  • We'll need a different class for commands run as root since the prompt is then '#' instead of '$'. It's a detail but otherwise it might confuse people who are used to interpret '$' as a command to run as non-root.
  • I'm wondering why we use both span class="code" and the code tag. Could we use only one of them? To spot them: git grep 'class="code' -- "*.*m*".
  • We also have span class="command" which is used in some places but also seems to partly duplicate span class="code" and the code tag. How could we clean this up a bit? Maybe it still makes sense to be able to differentiate commands from code in some occasions... I like how Google use a light gray background to mark code embeded in text. See: https://developers.google.com/style/code-in-text
    To spot them: git grep 'class="command' -- "*.*m*"
  • Could we make the code tag look more like p.command?
  • I think that 'p.code' which is defined in local.css is not used anywhere and could be removed. Can you double-check?

That said, all this is probably lower priority... And CSS is a big time eater, so don't get hooked too much on this.

Something more important could be to check how to improve the rest of our instructions to benefit from your improvements. But it might be easier to do so after fixing the CSS a bit more. I'm not sure which order is the best... Maybe a mix.

Another strategy could be to mark some older styles as deprecated in the CSS itself. For example, you could move old CSS styles closer to the new section that I created for your style and mark some of them as deprecated, as a way of remembering not to use them anymore in the future.

As a general note, our CSS is super messy so don't try to clean it up entirely. Whenever I work on it I only aim at my additions or modifications being cleaner than the rest of it :)

And last but not least, beware of not breaking too many translations while working on this. Tell me if it's unclear to you how our translation system works and how to prevent translations from being marked fuzzy unnecessarily. When I work on CSS like this, it's usually a very good start to use sed to rename CSS classes in both the original source (.mdwn or .html) and the .po files for the translations. But sed don't always catch them all.

#10 Updated by intrigeri about 1 year ago

  • Target version changed from Tails_3.8 to Tails_3.9

#11 Updated by intrigeri 11 months ago

  • Target version changed from Tails_3.9 to Tails_3.10.1

#12 Updated by sajolida 10 months ago

  • Assignee changed from cbrownstein to sajolida

If you don't mind I'll take over the rest of this ticket.

#13 Updated by sajolida 10 months ago

  • Blocks deleted (Feature #15411: Core work 2018Q2 → 2018Q3: Technical writing)

#14 Updated by sajolida 10 months ago

  • Blocks Feature #15941: Core work 2018Q4 → 2019Q2: Technical writing added

#15 Updated by sajolida 9 months ago

  • Target version changed from Tails_3.10.1 to Tails_3.11

#16 Updated by sajolida 7 months ago

  • Target version changed from Tails_3.11 to Tails_3.12

#17 Updated by sajolida 6 months ago

  • Target version changed from Tails_3.12 to Tails_3.13

#18 Updated by sajolida 4 months ago

  • Target version changed from Tails_3.13 to Tails_3.14

#19 Updated by CyrilBrulebois about 2 months ago

  • Target version changed from Tails_3.14 to Tails_3.15

#20 Updated by CyrilBrulebois 8 days ago

  • Target version changed from Tails_3.15 to Tails_3.16

Also available in: Atom PDF