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:Code examples in a document? From:"Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Wed, 6 Nov 2002 09:36:15 -0500
John Posada wonders: <<For those who place code in their document, how do
you handle code lines that are so long that they wrap in the document. I
have script codes that I need to include in one of my sections...all in all,
about 75 lines of code.>>
I'd break the lines at a logical place (e.g., URLs should break after the
/), then wrap the second line with a hanging indent (so it's indented from
the first line). Some programming languages use a special character such as
the sideways L to indicate that the line continues; your SMEs can probably
tell you whether that's acceptable and what character is preferred. If not,
you can sometimes use a character combo such as <BR> or an iconic character
such as the character for carriage return (the curved arrow that points back
the way it started) to indicate a line wrap, provided you define the
character in the title of the listing. Avoid using typeable characters such
as - because typing these could lead occasional users to type the character.
Thinking a little further outside the box: Can you provide the script
samples as text files on the installer disk? That lets you provide a printed
version for reference, but a correctly formatted and wrapped line ready for
reuse by the programmer.
<<Use 9pt Courier New to eliminate proportional spacing and to get maximum
line length.>>
Although Courier is a standard font for code, consider using a proportional
font instead; you'll usually fit considerably more text on a line without
compromising readability. Boxing the code samples (literally, with lines, or
figuratively, with white space) provides all the separation from the body
text that you'll need.
--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html
"The skill of writing is to create a context in which other people can
think."--Edwin Schlossberg, designer (1945- )
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check out SnagIt - The Screen Capture Standard!
Download a free 30-day trial from http://www.techsmith.com/rdr/txt/twr
Find out what all the other tech writers, including Dan, already know!
Order RoboHelp X3 in November and receive $100 mail in rebate, FREE WebHelp
Merge Module and the new RoboPDF - add powerful PDF output functionality
to RoboHelp X3. Order online today at http://www.ehelp.com/techwr-l
---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
