TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:RE: Boxes for Code: Summary From:KMcLauchlan -at- chrysalis-its -dot- com To:janice -dot- gelb -at- eng -dot- sun -dot- com, techwr-l -at- lists -dot- raycomm -dot- com Date:Thu, 18 May 2000 13:20:47 -0400
Janice G. said:
> I got ten responses, and only two people said they
> are still using boxes around code examples, and
> that using a monospace font (generally Courier,
> which we also use), especially combined with an
> indent, was enough. Most people said that use of
> boxes was old fashioned.
I still haven't landed on a method I like.
I use boxes for command-line interactions. We still
have tools that use character-based menus... not
much GUI happening yet... mostly in-house tools,
slightly fixed-up for our toolkit customers to use.
I use Courier 9pt among 11-point body text, for
Problem is, most programmers see code in programmer's
editors, spread wider than my margins can handle.
So, that's how they write it, too. Their editors
usually have default tab settings that just won't
fit on my printed pages.
I don't like to go really tiny on the Courier, to
make the samples fit. Sometimes I re-format, chop
spaces out of tabs, etc., but that's very tedious
and often doesn't work. I'll have a three-page
code sample and set it up so that all the lines fit
without inappropriate wrapping... and then, on the
third page I'll discover the programmer used an
extra-long variable-name that blows my careful scheme
out of the water.
I literally cannot remember even a two-line sample
from the past two years that could fit in my 3-3/4 inch
text area WITH an additional indent. I guess other
folks must use wide pages if they can consistently use
an indent from the body-text margin as one of the
formatting signals for code-sample text.
When wrapping is unavoidable, what do you folks use
as your standard for how a line of code should break?
After the break, how far do you indent? The programmer
uses an editor that auto-indents depending on which
field (and maybe what type of structure) he was in,
and has rules about how a line of code is permitted to
break. Certainly nesting can use up a lot of page
real-estate in a hurry.
I seem to be constantly battling to reconcile
space considerations with readablity. My page layout
-- which works fine in other respects -- is usually a
right-hand main-text column with a left-hand side-head
area. Too often, I give in and let a code sample
spread from margin to margin (i.e., not respecting the
column/side-head layout), and that's when a box of
some sort becomes attractive.
I've looked at commercial work, and the samples often
seem to be suspiciously ... well... sanitized for
presentation on a printed page. Hardly anybody uses
a statement with eight or ten arguments, stretching
clear across the screen... twice. Usually, other
people's samples seem to fit neatly on a page, with
lots of lovely white-space all round. Looks nice, though. :-)