Formatting recommendations for long commands in codeblocks?

[jherrman]

Currently, for commands that would exceed the width of a codeblock on the docs page, we generally use the no-wrap parameter to make the codeblock horizontally scrollable. This has a number of advantages over segmenting long commands over multiple lines (through backslashes), including:

• Easier and more reliable copy-pasting
• Better use of screen space
• Avoiding issues with codeblocks wrapping weirdly in resized browser windows (e.g. on mobile devices)

However, recently, there have been a number of reports (such as BZ#2111837) that this is detrimental to the UX, because it forces the reader to interact manually with the doc to see all the parameters. In addition, certain browsers (such as Firefox) currently hide the scrollbar unless moused-over, so the command may actually appear as incomplete, without any indication that there is more to it.

Therefore, it would be good to agree on CCS-wide recommendations on formatting long commands (such as when to avoid no-wrap, and how many characters per line to use when you do) and list them in the Supplementary Style Guide, or elsewhere.

For further details on the issue, see the RHEL docs most-hands meeting notes (from Aug 24) or the discussion in the recording (~4:20 - 14:00).

[bergerhoffer]

We discussed this in the 31 August SSG meeting. We didn't really come to any conclusions here though. Since there seems to be a lot of factors, like what features the portal will support (copy button) or how the portal formats code blocks. And that these things could change.

@jherrman We left an opportunity for people to continue the discussion here in this issue, so we can leave some time for others to weigh in. But otherwise I'm not sure if I see a clear piece of advise that we could add to the SSG that would work for all cases. Please feel free to correct me or continue with more discussion here!

[jherrman]

@bergerhoffer that's right. There's currently far too many variables and future unknowns to come up with reasonably compact and reliable set of recommendations. So, the best course for the moment seems to be leaving this in the discretion of individual writers.

Nevertheless, I would recommend that folks who do divide their long commands into multiple lines also set up no-wrapping for the codeblock (that is [options="nowrap",role=white-space-pre] in the current publication toolchain & stylesheets). This way, if the browser window does get resized in a way that would make any of the lines wrapped awkwardly, the codeblock should become side-scrollable instead.

[bergerhoffer]

@jherrman I agree about leaving this up to the discretion of the writer then. Do you think it's worthwhile to add the recommendation of the options=nowrap, etc. to the SSG? Or just close this issue? Or actually, maybe it would be more appropriate in the asciidoc writing guide: https://redhat-documentation.github.io/asciidoc-markup-conventions/. wdyt?

[jherrman]

@bergerhoffer , I think the adoc markup conventions doc is meant to be fairly concise and high-level, and adding to it writing minutiae like this would blow it up and dilute it quite badly. Instead, I think the best place might be our adoc training book. In fact, I've already added it there :-)

As for adding this to the SSG, I'd also say this is fairly specific to current internal RH tooling and stylesheets. In asciidoctor, for instance, nowrap doesn't require role=white-space-pre. So, it would probably not fit well with the community focus of the doc.

WDYT?

[cfbryan]

RE: "how the customer portal formats codeblocks." In codeblocks as they are displayed on access.redhat.com, they are all treated the same in the CSS. There is no wrapping and they are allowed to scroll horizontally and grow vertically. I don't believe that setting options=nowrap has any effect on the display of the content. Please let me know if you find differently.

I am not certain if the style guide is used for content that drives community sites as well, but just in case this suggestion was aimed at making changes on the Red Hat customer portal, I wanted to make sure that you had that context.

[jherrman]

@cfbryan , I took a look through our docs and no-wrap really seems to be configured for codeblocks by default! :-O Is this perhaps a new setting that came with the Jupiter stylesheets change?

I know for a fact that not too long ago, it was a problem to get no-wrap to work even when specified (see e.g. CCSOPS-238), so having it work without the need to set it explicitly is a vast improvement :-D

[cfbryan]

That seems probable. I'm glad we finally gave you a full resolution to that ticket from 2019!

[jherrman]

@cfbryan thanks for the confirmation, and for implementing this improvement :-) It will definitely make the lives of our writers easier, our source code lighter, and our docs better looking :-)

[cfbryan]

I'm happy to provide the information, but the design and implementation was all the team. I'm glad it makes folks lives easier!

[bergerhoffer]

Great thanks @cfbryan for the details! It sounds like we're in agreement that we don't need to make any updates to the SSG for this item so I'm closing the issue. Feel free to reopen if there is more discussion that is needed!

[jherrman]

@cfbryan I did a bit more testing, and it actually looks like the no-wrap config in the new stylesheets works a bit too well.

To be specific, when you wrap a line that ends with a backslash in adoc, local previews (and MR auto-previews) work fine, but the CP seems to render these lines as a single line.

Example 1: https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/building_running_and_managing_containers/assembly_adding-software-to-a-ubi-container_building-running-and-managing-containers#proc_using-the-ubi-micro-images_assembly_adding-software-to-a-ubi-container (step 3)

Source: http://pastebin.test.redhat.com/1075108

Example 2:

https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/deploying_red_hat_enterprise_linux_8_on_public_cloud_platforms/configuring-a-red-hat-high-availability-cluster-on-aws_deploying-a-virtual-machine-on-aws#aws-configuring-fencing_configuring-a-red-hat-high-availability-cluster-on-aws (alternate procedure step 3)

Source: http://pastebin.test.redhat.com/1075112

This means that even if we wanted, we can't really use multi-line formatting for long commands :-) If possible, please look into this, and let me know if I'm missing something, or if this is perhaps a bug.

Cheers, J.

[cfbryan]

This is intentional, and not a bug. We want code blocks to behave the same way on the portal.

[jherrman]

@cfbryan are you sure this is a good idea? The main reason we are having this discussion at all is that there were multiple reports that long commands formatted as a single line reduce readability and usability, and even though this is disputable, completely taking away the possibility of formatting a long command into multiple lines does not really help anything or anyone, as far as I can tell. So, what am I missing here?

[cfbryan]

This type of question is always really hard to answer. At its heart, it's an ask to justify our existing choices, and using that framework, YES, I support the choices we've made in UX and FE implementation. There's a lot of thoughtwork that goes into our designs and planning, and they have been vetted, tested, and battle-hardened by CCS for a few months now.

We do iterate on decisions and choices - see the new placement of the format and language dropdowns for a visible example. But in this case I'm not sure I see an upswell of need for it. The changes have been live for a few months. I do try to keep my eye on chatter across CCS, and this is the first time IIRC that it's come up that a lack of formatting controls in code blocks have come up. I'm not discounting that it is a problem, but if this had come up in a lot of tickets, comments, in the post-launch survey, in various CCS chat rooms, or as a part of our testing process, then I'd be leaning more towards opening this up as a problem across CCS.

We have other changes that we may be making to code blocks to improve other aspects of page readability and usability. Giving individuals in CCS formatting control over the page is not as likely as some other things we are considering. The designs and choices we have today are expected to work, for example, at all breakpoints for a viewer looking at the page - various desktop widths, tablet, and mobile. I would expect that hard coding breaks into the code lines might cause problems at different widths and/or would trigger issues in the event that we implement a copy mechanism.

If you would like to still request that we change this, either in our current or future tooling, the next step is to get some additional support for this change. I would recommend documenting it quite thoroughly, such as what commands you would want to have control over and how these commands would be interpreted in desktop, tablet, and mobile. Then please take it to our internal team working on this, headed by Susan Carpenter. If she and the rest of the team support this request, then we'd evaluate it and look into implementation.

[jherrman]

@cfbryan I did a bit more digging, and it looks like codeblock lines with backslashes work as expected even on the CP (1) unless you wrap the entire command in a pair of asterisks to make it bold. Then, it works in asciidoctor and bccutil, but not in Pantheon/CP - so it might be a vagary introduced by the DocBook layer of Pantheon.

Either way, it can be worked around by using a pair of asterisks for each line of the command, which is easy enough for writers to do.

Therefore, I'll capture that in our internal how-to's for writers, and you don't have to worry about this any more... ;-)

Thanks, and have an excellent day, J.

(1) E.g. here: https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html-single/deduplicating_and_compressing_storage/index#creating-a-vdo-volume-for-performance-testing_testing-vdo-performance

[cfbryan]

Thanks. I'll take a look. If you could add as a part of your directions that authors are responsible for checking the impact of their changes at all browser breakpoints, I would appreciate it.

[wesruv]

Hello, I'm one of the CSS dorks that's styling the docs.

My hope is that codeblocks would have the same line breaks that are in the adoc source. I don't want to force wrap them, or try to come up with clever logic to reformat them. There's been a few times I was tempted to do something clever; for small screens, or the print stylesheet, or to address bugs caused by formatting. It always causes other issues.

The only exception is that we allow line wrapping for the print style sheet, otherwise most code would be missing because it's off the right side of the page.

Looking at the examples you provided, it looks like something in Pv1 is removing line breaks.

Like this example:

Example 1: https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/building_running_and_managing_containers/assembly_adding-software-to-a-ubi-container_building-running-and-managing-containers#proc_using-the-ubi-micro-images_assembly_adding-software-to-a-ubi-container (step 3)

Source: http://pastebin.test.redhat.com/1075108

If I "view source" on the portal URL, and find the code for that text block; they don't exist in the HTML: No amount of fancy styling on my part is going to get them back, and I don't event want to think about the regex's I'd have to come up with to get them back with JS 😰

Unfortunately, the rendering process has been a total black box for me, so I'm unable to track this down further. I'm clueless on why anything would ever do that, or what could be done to avoid it 😞

[jherrman]

@wesruv yep. looks like some inscrutable Pantheon arcana all right :-) Still, given that the workaround is known and is not too complicated, I don't think the tooling folks need to lose any sleep over this :-]