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.
> > - breaking lines yourself
> > Tedious, but I've done it using a backslash as
> > the last character before the "natural" line
> > break - add spaces to line the backslash up
> > with the right hand margin, as it would appear
> > in a console window and some text editors (vi,
> > emacs). Don't forget to let your readers know
> > what the backslash is in the Text Conventions
> > section in the intro.
>
> Yeah, well.... in the mix of stuff that gets (currently)
> my mono-font treatment is the command-line command
> with filespec... ya don't wanna be inserting extra "\" or
> "/" or "-" characters into a commandline that needs to
> be letter-perfect.
It depends on your environment ... I've seen shell (ksh, csh) windows
in fvwm on Solaris
that use a \ to show when your command extends beyond the viewable
characters in your window. Putty SSHed into my ISP's OpenBSD system uses a
> to do the same thing. I suppose it depends on your assumption about your
users/readers (are they smart enough to recognize that they shouldn't type
that char?), letting them know what the char is used for (and choosing one
that's *not* used in any commands/sample code), and using the convention
consistently.
> (Speaking of which, when all your steps are grammatically
> correct, and end with periods, and then you have a
> step that ends with a command, what do y'all do?
> In most OSes, a trailing period means something.)
I put the command on a separate line by itself ("Enter the following:") or
put it in the same font that I use for sample code and assume that my
readers are smart enough to figure out that they should only type the
command and not the accompanying punctation. This seems rather basic to
me, but then I don't know your audience.
> The code that I'm usually reproducing has "//" as
> the "everything after this point in the line is comment"
> indicator. But then, by convention, the comments begin
> at a particular tab. I usually shrink the tab settings, in
> order to make as much as possible fit, but what usually
> happens is that I end up with something // that looks
> // annoyingly
> // similar
> // to this.
>
> (All the "//" should have been vertically aligned, if
> your tabs are like my tabs...)
And that's why I replace tabs with spaces - a space is a space (well, most
of the time) regardless of the settings in you paragraph tag/style, your
printer settings, etc.
> > > 1. Put the tabular matter in a figure and
> > > turn the figure on the page--make a landscape
> > > page, in other words.
> > As a reader, I shudder to think of having to
> > deal with a landscaped page or section ... I
> > avoid this unless, well, it can't be avoided,
> > as with wide tables that simply can't be made
> > narrower.
> Well, as a reader, I don't like it, but I still prefer it
> to being required to page to some appendix in
> order to view what's referred to in the main text.
I agree, especially if you going into detail about the sample code.
> An idea that I may resurrect is to use triple-wide
> pages in the appendix. The first section is blank,
> while the table or illustration is on the second and
> third panels. When the page is folded out, the
> entire table or illustration is visible, even when
> the book is open to a different page.
> It works very well, but has the drawbacks of
> requiring special (expensive) folding and positioning,
> and it makes the printed document thicker. It's also
> not a good solution for onscreen PDF viewing...
But it still sounds useful. If only the Larousse people had thought of
that when I was in college and needed both the dictionary and an appendix
to write some of my papers. I ended up using an exacto knife to cut the
appendix out.
> > A good suggestion, although I'd like to add
> > that I replace tab stops with spaces to get
> > things to line up properly. First, I replace
> > the tab stops in one line to get the columns to
> > line up properly, usually a line with the
> > longest content in the columns. Then I search
> > and replace the tabs with the magic number of
> > spaces.
>
> Why? The whole point of tabs is that they line
> up, regardless of individual character widths and
> font quirks. Besides, there are always headings
> for the numeric bits, and those are not "monospace
> by design" as he suggested.
Well, the sample code we were bringing in didn't have consistent tab
stops. To indent the same amount, some of the developers would use tabs,
others would use a tab and a space, others all spaces. In other cases, the
indents weren't consistent and the sample code from different developers
on the same page would look ... well, messy. Instead of futzing with the
tab settings in individual paragraphs, introducing overrides galore to the
template, it was easier for me to replace tabs with spaces. Easier in the
sense that it took less concentration that adjusting tab settings in each
paragraph and (I think) it took less time to get the code to look right.
I also have to add that the developers let me adjust the spacing/tab stops
in the source file (sample application files, not the source files for the
libs).
> Probably I can work out something with a rotated
> table (if the rotation doesn't ruin anything), cuz
> then I might be able to just import other people's
> code without touching it.
This, of course, is ideal.
> But that will be something to figure out in OpenOffice.
> I keep trying to leave Frame and Word behind,
> so I don't need to keep adding more techniques
> that I have to leave behind... :-)
It comes in handy to develop techniques to deal with specific situations
and applications - sometimes you can use them elsewhere.
Mandy Kinne
wistfully remembering using Frame on Unix, now doing daily battle with
Word et al on Windows.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Help Authoring Seminar 2003, coming soon to a city near you! Attend this
educational and affordable one-day seminar covering existing and emerging
trends in Help authoring technology. See http://www.ehelp.com/techwr-l2.
A new book on Single Sourcing has been released by William Andrew
Publishing: _Single Sourcing: Building Modular Documentation_
is now available at: http://www.williamandrew.com/titles/1491.html.
---
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.
