RE: Code examples in a document?

[John Posada <JPosada -at- book -dot- com>]

Hi, Geoff...Any minute, my post on how I resolved this should be coming
across your mail reader, but in summary, I did use the handing indent.

BTW...since this is documenting an internal system rather than an installed
application, it doesn't apply that I include the code on the CD. However,
what I've done close to that is give the location in VSS where the actual
code is maintained, with a statement to the reader that the enclosed code is
for information purposes only and that if they are going to do anything with
the code, do it from the code stored in VSS.

Thanks for your input.

John Posada
Senior Technical Writer
Barnes&Noble.com
jposada -at- book -dot- com
212-414-6656
 "Be accurate...the 4am wakeup call you prevent could be your manager's"



-----Original Message-----
From: Hart, Geoff [mailto:Geoff-H -at- MTL -dot- FERIC -dot- CA]
Sent: Wednesday, November 06, 2002 9:36 AM
To: Techwr-L (E-mail); 'John Posada'
Subject: Code examples in a document?


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.


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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

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!

---
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.