Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs

Dashboard
Notifications
Mark all as read
Q&A
Post

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 does this post require moderator attention?
You might want to add some details to your flag.
Why should this post be closed?

1 comment thread

General comments (1 comment)

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

General comments

Skipping 1 deleted comment.

Monica Cellio‭ wrote over 1 year 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.)

This community is part of the Codidact network. We have other communities too — take a look!

You can also join us in chat!

Want to advertise this community? Use our templates!

Like what we're doing? Support us! Donate