Wednesday, December 12, 2012

Publishing Code on Digital Platforms

I plan to write a new book next year (Effective C++11, about which I'll have more to say later, probably in January), and I'm laying the groundwork for it.  Part of that groundwork is doing what I can to ensure that the book looks good on all target platforms, by which I mean ink on paper as well as various digital representations (e.g., PDF, HTML, ePub, etc.)  I've noticed that many books containing code examples display, er, suboptimally on one or more digital devices, and I want to avoid that.  To that end, I've started a list of characteristics I think code displays should have, i.e., that readers should be able to take for granted in code displays.

A "code display" is code sitting in a paragraph on its own, i.e., like this:
// This code display consists of a class definition and a free function
class Widget {
public:
  explicit Widget();
  Widget(const Widget& rhs);
  Widget(Widget&& rhs);
  ...
};

std::ostream& operator<<(std::ostream& s, const Widget& w);
Here's my list so far:
  • Code should be syntax-highlighted.
  • Code should be copyable and pastable as text. This rules out using images for code displays.
  • Code should be copyable and pastable as code. For example, if the code display has line numbers, there should be a way to copy and/or paste such that the line numbers are omitted.
  • Code should be searchable. This also rules out using images for code displays.
  • Viewing Code displays should not require horizontal scrolling.
  • Code displays should have no bad line breaks.  This means no automatic wraparound due to the code not fitting in the available horizontal space.
There's a caveat to this "code reader's bill of rights." If you choose to view a code display in a "pathological" way, you lose the last two guarantees.  In general, this means that I expect you to have some reasonable horizontal width available on whatever device you're using.  If you view a code display on an iPhone in portrait mode, you're on your own.  If you view code on 10" tablet and set the font size to 200, you're on your own. If you view code on a giant PC screen and set the viewing window to 10 pixels wide, all bets are off.  As an author, I'm willing to do what I must to offer you these guarantees, and I'm willing to browbeat my publisher into offering them, too, but you have to give us a reasonable field to play on.

Are there other things you, as a reader, would like to be able to take for granted when viewing code displays in a technical publication?  Are there problems with code displays on digital devices that you've run into and that are not addressed above?  If so, let me know. Bear in mind that I'm trying to identify basic characteristics you should be able to take for granted, but currently cannot.  I'm happy to hear about nice-to-haves, too (e.g. it'd be nice to be able to click on or gesture over some code and have it automatically sent to an online site such as ideone or Live Work Space to be compiled and executed), but what I'm really interested in are things you should be able to take for granted.

Thanks,

Scott




21 comments:

Jerry Coffin said...

Although it probably falls more into the "nice to have" bucket than the "absolute necessity", one more thing that would be really nice would be some way to see diffs/changes to the code.

Hard though many of it find it to believe, it's barely possible that the initial version could be slightly less than perfect, and being able to see changes directly rather than trying to compare to what we think we remember.

On the other hand, you might want to apply that to everything, not just the code.

Brian said...

E-ink displays are (for the most part) grayscale, so syntax highlighting will have limitations on those devices; also, they tend to be in portrait orientation. Text lines are around 45 characters at a comfortable font size for me. Bad line breaks may be the only option, but with obvious exceptions like long // comments and literal strings, C++ should be fairly tolerant of line breaks.

Scott Meyers said...

@Brian: Back in the bad old days before color displays were the norm, syntax highlighting took the form of things like displaying keywords in bold. There's more than one way to skin that particular cat.

As for text lines being around 45 characters long, presumably you have some particular device in mind. If there's a limitation, it doesn't come from E-ink, it comes from the package the E-ink display is part of.

Billy O'Neal said...

I know this is kinda obvious -- but a fixed-width rather than a variable-width font is usually a requirement for readable code. (Which unfortunately makes the space problem worse)

Luckily, even on a 6 inch (Kindle-esque) display, rotating to landscape mode is usually fine. (At least, Effective C++ 3rd Edition and Effective STL look reasonably good that way)

Billy O'Neal said...

(Oh, and I would say that I would rather see unreadable mess in a 6 inch display in exchange for good looking code on more reasonable displays rather than the reverse.)

Scott Meyers said...

@Billy O'Neal: Both EC++/3e and ESTL use a proportional font. Do you think that detracts from the code's readability? (It's a neutral question. Probably the most common request I get from people is to use a fixed-width font for code.)

As for the trade-off between attractive code on some devices and unattractive code on others, my goal is that the code looks good on all devices (other than pathological ones). There are various ways to do that, but the problem, if there is one, is mine and my publisher's, so don't be so quick to make concessions. Trade-offs are necessary only when you can't come up with a way to satisfy all the constraints, and my goal is to find solutions that obviate the need for trade-offs.

Yuri Khan said...

Another basic reader right that rules out images is the right to configure the font face. And yes, I take that for granted, for code as well as prose.

I also take for granted that the code will use my display space efficiently. That is, if I am reading from a desktop monitor at 1600×1200, it won’t be hard-wrapped at 45 characters.

In fact, I think it would be not too hard to develop a client script that would smart-wrap code to the allotted width, with line continuations properly indented.

Lastly, please do not regard PDF as a digital form. Layout-wise, it is still ink on paper in a digital disguise.

Scott Meyers said...

@Yuri Khan: I don't know of a way to automatically wrap code that produces sufficiently good results to publish, and if one exists, I'd be concerned about its availability on ereader platforms (e.g., iOS and Androd tablets, Kindle, Nook, etc.). Having said that, if you can point me to such software, I'd love to play around with it.

As for PDF, it's clearly a digital form. You can search it, you can copy from it, you can link from it, you can send it via email, etc. Those characteristics clearly distinguish it from print publications.

Billy O'Neal said...

@Scott:

Perhaps I stand corrected about the font. I think it looks fixed-width here; but that could just be the Kindle mangling it. (The default Kindle font is almost fixed anyway)

My comment was made in general; not a statement about your books in particular.

Phi Pig said...

Sometimes, sample code on a specific subject (say "smart pointers") will also show something defined elsewhere (say "explicit constructor").
The usual way is simply to put a comment in the "smart pointer" sample :
explicit Widget(int value) // See chapter 3
It would be better if it was a link to the chapter.

Bernhard Merkle said...
This comment has been removed by the author.
Bernhard Merkle said...

I think also looking at existing examples we can learn a lot e.g. take Dave Abrahams book "C++ Template Metaprogramming: Concepts, Tools, and Techniques from Boost "

and lets compare the hardcopy, google books and the kindle version i have:

Pros:
-the source code is extracted from the book and hence is consistent. During the creating of the book I think Dave asserted that it always can be compiled e.g. with gcc.
-the source code is available additionally as separate zip

Cons:
-layout format
is totally different, e.g. kindle uses block record format while the pdf/google books uses left adjusted format.

-font sizes and ratio between them
for different things, e.g. math formular, source code, normal text, different fonts and sizes are used which is good and ok.
However the problem is that in the kindle version source code font size is bigger and e.g. the math formular are actually pictures.

-there are tables containing source code these are pictures, so no copy of source code out of table.

Yuri Khan said...

I am not very familiar with book reader software. My reading expectations are based on the experience with HTML+CSS+JavaScript in a desktop browser.

Re: PDF, yes you can search and copy/paste (if not restricted by the publisher), but in the majority of cases you cannot reflow.

Scott Meyers said...

@Phi Pig: Certainly you should be able to take for granted that cross references are links. As far as I know, in electronic versions of my books, they always have been and always will be.

Scott Meyers said...

@Billy O'Neal: I'll ask my publisher about font limitations on Kindle and other digital platforms. If we have to play games to get code to look good on Kindle (or elsewhere), and if it's practical to play those games, we'll play them. If different platforms require the use of different fonts, so be it. It's not like C++ developers are unfamiliar with the idea of platform-specific code :-)

Scott Meyers said...

@Yuri Khan: Your expectations should be in accord with the platform you are using. You should not expect color on a monochrome device, you should not expect to be able to copy and paste on devices that don't support copying and pasting, and you should not expect dynamic line breaks from a format not designed to support them (e.g., PDF). On the other hand, I expect my books to be available in a variety of formats on a variety of devices (e.g., Safari (the online book service, not the browser), Kindle, Nook, PDF, etc.), so you should be able to choose the format and device that gives you the feature set you want. At least that's my hope. My publisher and I are talking about this kind of thing now, and there may be format or device limitations I'm not aware of that will require some dialing down of my ambitions. But my goal is that EC++11 looks good everywhere it is available, where "good" is affected by the capabilities of the device you, as a reader, choose to use.

Scott Meyers said...

@Bernhard Merkle: Can you please elaborate on what you mean by "block record" and "left adjusted" formats? As for Kindle, my impression is that some books where ported there without any regard for the appearance of code displays. Avoiding that kind of problem is the motivation for my publishing this blog post. If I know what kinds of problems have arisen in the past, I can work with my publisher to avoid them.

_ _ said...

Hey Scott,

I'm working in the team responsible for the module which renders content for some platforms at Amazon.com. I agree with you, the experience of reading some code snippets is not optimal. Let me know if I can help you with some rendering features.

Thanks,

Augusto

Scott Meyers said...

@_ _: I'd be grateful if you'd send me email to start a conversation on this topic. I'd love to get your insights into what's possible on Amazon-backed platforms. My email is smeyers@aristeia.com.

Thanks!

Todd Greer said...

I do sometimes find myself reading on "pathological" devices, such as my phone (Samsung Galaxy S3) in portrait mode. It's a very convenient way to read the prose portion of books. While it certainly can't be made perfect, anything that can be done for those devices would be appreciated. Perhaps some of the work that has gone into making highly scalable web pages with liquid layouts and scripting can help.

Given the difficulty, it might work well to let me tap the code sample to 'zoom in' and view only it. That way, when I then rotate to portrait mode, I don't have to scroll to find it. (My Kindle app seems to have difficulty putting me in the right place when I rotate the device.) A way to switch easily back and forth would help with another problem that is more pronounced the smaller the device. That is that the sample often gets positioned far enough from the discussion that it can be hard to even find what sample is being discussed.

In short, we all recognize that it will be far from perfect, but please do what you can to make code samples at least comprehensible, even on difficult displays.

Scott Meyers said...

@Todd Greer: Thanks for your comments regarding reading technical books on phones. My natural inclination is to downgrade the importance of such devices as targets for my books, but I realize that phones are the device you always have with you, and it's good to remind me how powerful an incentive that is to do what can be done to make technical material both look good and behave well on such devices.