Notifications
Sign Up Sign In
Q&A

How can we format code examples so that they work on a range of devices?

+2
−0

We use Madcap Flare to produce a large documentation set that contains many code examples (primarily SQL, but also C++, Java, and Python) and command-line operations. When the doc set was first planned, years ago, the people designing the layout assumed desktop browsers, as was the norm back then. We know how to make most aspects of our doc set more responsive to viewport size and platform, but I'm not sure what to do about the code examples.

Flare uses a slightly augmented HTML for its source. Our examples are all in <pre> blocks, with styling for syntax highlighting. Regular text flows to fit the viewport, but you can't just wrap a Linux command line, and the results of wrapping code would sometimes be confusing unless a continuation character were used in ways that browsers usually don't. Within the <pre> blocks we sometimes reformat unwieldy code or command lines onto multiple lines, using continuation characters and indentation to make things clear. But we're doing that based on what looks good in the browser windows we're currently using, so none of this solves the tablet problem (let alone the phone problem). And yes, we have heard from customers that they want to be able to consult our documentation on these devices.

How should we be approaching code examples in a multi-device world? If we insert those manual line breaks to accommodate phones the doc will look terrible on a desktop; if we design for desktops then people using phones or some tablets have to scroll horizontally (which is a pretty terrible UX). We host our documentation publicly and distribute an HTML archive; ideally we would like a solution that works in both contexts. We can modify CSS, add Javascript, and adjust how we use Flare, but we cannot replace Flare or build separate versions for each target platform. Being part of a larger corporation, we don't have full control of our webserver; server configuration changes might be possible but will certainly involve bureaucracy.

Is there, perhaps, some Javascript we can insert that detects the viewport size and automatically does "something reasonable" -- and what would "something reasonable" look like?

Why should this post be closed?

2 comments

Do you need to use specifically <pre> in the rendered HTML, or are you simply trying to make code blocks use a monospace font and possibly preserve things like whitespace, and <pre> happens to be a handy way to do that? Because the content of a <pre> element is meant to be, well, pre-formatted, so if you want to allow the browser to reflow the content, it might not be the best choice. For example, might a <div> with some appropriate CSS for presentation meet your needs? ‭aCVn‭ about 1 month ago

@aCVn <pre> is what we're using now (actually inside a <div class="example"> for some other styling; don't know why). It doesn't have to be that specifically; I don't know whether this was intentional or an artifact of porting from a prior tool, but either way it was ten years ago and we can certainly revisit. (We'll need to be able to script the change, though; there are thousands of these.) ‭Monica Cellio‭ about 1 month ago

1 answer

+1
−0

I've seen this problem even on desktop - particularly if a blog with some code has a relatively narrow center section due to wasted space on the left and right (typically with stuff on the left and right at the top but then wasted on the rest of the page, but that really doesn't matter for this particular question).

Anything manual is pretty much guaranteed to be a mess. But maybe there is a CSS way of having a continuation marker on the left for any line that has wrapped. Not a simple + (or similar) continuation character but rather a solid colored line, sort of like you often have to indicate a quoted blob of text, but have it only show on the continuation lines. That would be clear visually (all within the <pre> block of code, but with some lines having this "prefix" and some having blank space in the same location.

A little searching and it looks like the key may be first-line, like:

p::first-line {
  background-color: yellow;
}

The catch is that this would need to be applied to every line within a <pre> as if it were a separate <span> (or something) because we don't want this for "the first line of the pre different from the other lines of the pre" but rather "for every single "source line", have a first-line and all other lines based on wrapping. I am sure this can work, the only question is how much adjustment to typical markdown or other HTML generation needs to be done to make it work.

4 comments

I might be misunderstanding, but how does this account for the different line lengths needed on different devices? This looks like a way to style wrap, but how do you get automatic wrapping inside a pre? ‭Monica Cellio‭ about 1 month ago

I'm not 100% of "how". But I think that this may get towards it. I think the solution is a combination of: Get a pre or similar element to provide "code style formatting" + "with wrap" plus use "first-line" to style first line of each wrapped code line one way and the subsequent lines another way (i.e., with a visual continuation indicator) plus figure out out to automatically make each "line of code" be a separate element so that "first-line" will work one each line of code ‭manassehkatz‭ about 1 month ago

of just once for the entire blob of code. I see the problems, I have a hunch on the solution, but not 100% there yet. And if someone else comes up with a solution first, that's fine with me. ‭manassehkatz‭ about 1 month ago

For "wrap inside a pre" by itself, see: https://stackoverflow.com/questions/248011/how-do-i-wrap-text-in-a-pre-tag ‭manassehkatz‭ about 1 month ago

Sign up to answer this question »