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 almost 2 years ago. Updated 3 months 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 #16711: Core work 2019Q3 → 2019Q4: Technical writing Confirmed 01/08/2016
Blocks Tails - Feature #17229: Convert ASCII typography into HTML entities using SmartyPants (libtext-typography-perl) Confirmed

History

#1 Updated by sajolida almost 2 years ago

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

#2 Updated by sajolida almost 2 years 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 almost 2 years ago

  • Assignee set to cbrownstein

#4 Updated by cbrownstein almost 2 years 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 over 1 year ago

  • Target version set to Tails_3.7

#8 Updated by sajolida over 1 year ago

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

#9 Updated by sajolida over 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 over 1 year ago

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

#11 Updated by intrigeri about 1 year ago

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

#12 Updated by sajolida about 1 year 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 about 1 year ago

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

#14 Updated by sajolida about 1 year ago

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

#15 Updated by sajolida about 1 year ago

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

#16 Updated by sajolida 11 months ago

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

#17 Updated by sajolida 10 months ago

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

#18 Updated by sajolida 8 months ago

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

#19 Updated by CyrilBrulebois 6 months ago

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

#20 Updated by CyrilBrulebois 4 months ago

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

#21 Updated by sajolida 4 months ago

  • Blocks Feature #16711: Core work 2019Q3 → 2019Q4: Technical writing added

#22 Updated by sajolida 4 months ago

  • Blocks deleted (Feature #15941: Core work 2018Q4 → 2019Q2: Technical writing)

#23 Updated by intrigeri 3 months ago

  • Target version deleted (Tails_3.16)

Hi!

We've set up an automated process to ask our fellow contributors to update some tickets of theirs, in order to:

  • better reflect your plans;
  • bring down your amount of work-in-progress to a sustainable level;
  • encourage team work and increase the chances that someone finishes the work;
  • avoid a human doing ticket triaging and asking you the same questions on each such ticket.

In particular, this process identifies:

  • Stalled work-in-progress
  • Reviews waiting for a long time

However, in the current state of things, this process is not able to notice those tickets when their Target version has been repeatedly postponed by our Release Managers. Therefore, the ticket triaging team decided on #16545 to remove the Target version whenever in such cases, when it does not feel realistic. This is what I'm doing on this ticket.

You now have a few options, such as:

  • Deassign yourself. That's fine. If it really matters, someone else, possibly you, may pick it up later. Then, if this ticket is relevant for a Tails team, bring it to their attention; else, forget it and take care of yourself :)
  • If you think you can realistically come back to it and finish the work in the next 6 months, say so on this ticket, for example by setting a suitable "Target version". This will communicate your plans to the rest of the project and ensure the task pops up on your radar at a suitable time. Of course, you can still realize later that it is not going to work as planned, and revisit today's choice.

Cheers!

#24 Updated by sajolida 3 days ago

  • Blocks Feature #17229: Convert ASCII typography into HTML entities using SmartyPants (libtext-typography-perl) added

Also available in: Atom PDF