SUMMARY: Courier for filenames etc.

[Thomas Michanek <tmi@xxxxxxxxxxxx>]

A few weeks ago, I asked for opinions on how to format names 
of files, variables, functions, etc. within normal body text.
I received a large number of private replies with many
varying opinions and experiences: Thanks to all of you!
This is an attempt to summarize the replies. (I can forward
a text with all replies for those who wishes to see them all.)

*** My original problem was:

> We write software manuals in which the body text is set with a
> proportional, serif font, like Times. In the body text, we often
> have to insert the names of files, variables, command-line tools,
> functions, etc. Examples (made up, not actual):
> 
> "This information is stored in a file called license.dat ..."
> "Set the path variable ..."
> "At the OS prompt, use the command stat ..."
> "In the source code, the function SetCommunication ..."
> 
> In all such cases, we set the filename, variable, etc. in a
> fixed-width font, like Courier, to make it stand out and be more
> easily spotted. We think this is motivated in many cases, especially
> if the word is small or similar/identical to a normal English word.
> We use a fixed-width font for it's common use when listing source
> code, textual input/output, files, etc. (I mean that both in the
> general sense and how we actually format such listings.) We use
> italic and bold formatting for other purposes.
> 
> The small problem is that the surrounding, proportional Times text
> often gets too close or "tight" to the more spread-out Courier text,
> thereby making the text harder to read, both on-screen and printed.
> This can be solved by also setting the surrounding spaces in Courier,
> thereby increasing the distance between the two text types (fonts).
> The problem with this is that it's difficult to get the writers to
> do it consistently, and it's much more easy to simply double-click
> a word (without the spaces) and change the formatting.

*** My questions were:

> Is this use of Courier "standard" and recommended?

It seems to be a standard to use a fixed-width font for separate
paragraphs containing code examples, file listings, etc., but not
necessarily for parts of body text. 
To quote "Snavely, Deborah" <dsnavely@visa.com>:
"This use of Courier is not as common today as it was ten years ago,
 for just the problems you describe. In general, style guides I've
 worked with and created confine the use of Courier to code samples 
 used in figures (sample listings, sample reports, etc.)."


> What other type setting method would you use for this?

Most people recommended using another font than Courier, etiher
another typewriter-style font, or a sans-serif font without
typewriter looks. What font to use depends on your body text font
and I refrain from quoting all suggestions here :-)

Others still used Courier, but together with a body text font like
Palatino or Garamond that seems to give less spacing problems.
Again, I quote "Snavely, Deborah" <dsnavely@visa.com>:
"In the instances where I've used Courier in body text, a character tag
 has defined the Courier font with a negative spread, and often uses a
 smaller size Courier typeface relative to the body typeface as well.
 Example:
 Body = 11-pt New Century Schoolbook
 Code = 9.5 Courier with -5% spread"

A few people recommended simply using bold or italics (without
changing fonts). To quote David or Marian Cortesi <cortesi@dsp.net>:
"It is much more common, I believe, to use italic or bold for this.
 Either style sets off the word(s) as having a different intent
 from the running text."

An interesting observation: noone referred to or recommended the
style used in the FrameMaker documentation: no change at all...


> If you use Courier, do you also include the surrounding spaces,
> or do you think it's unnecessary?

This apparently depends on the body text font and the relative
font size. A few people did include spaces, but find it, as we
do, cumbersome and problematic.


> How do you enforce/check this formatting and make it easier
> to apply in FrameMaker?

The answer seems to be: switch formatting method and then only
apply a pre-defined Character Tag to the word (not the spaces).


I end with quoting Peter Ring <pri@ddf.dk>:

"Resources that I have used and abused for inspiration:
* Read Me First! Sun Technical Publications 1996, Prentice Hall
  Includes a cd-rom with the FrameMaker source files
* Manual of Style for Technical Publications, Microsoft Press 1998
* Texinfo documentation Edition 2.23
* DocBook, http://www.oasis-open.org/docbook/documentation/

"While gathering inspiration and examples for this, I felt the 
need for an organized comparison of different style guides and 
conventions for presenting computer related text (code, syntax, 
examples, printout etc.). Well, I didn't make it, and I still 
feel the need. There's a specific set of problems related to 
these matters, e.g.,
* how is this type of information customarily handled in 
  Texinfo, DocBook, HTML etc.?
* synopsis, printout and screen literal samples should not 
  wrap long lines, but my body text use a rather narrow column 
  (for readability and to make room for sideheads), how do I 
  handle that?
* which monospaced fonts mix well with my body text?
* when *must* I use a monospaced font, and when should the body 
  typeface or e.g. roman italic for emphasis be preferred?


Thanks again to all!

- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Thomas Michanek, Documentation Manager, Telelogic Tau
Telelogic AB, Teknikringen 9, SE-58330 Linkoping, SWEDEN
PHONE:  +46 (0)13 211450   <--  *** new from April 1 ***
EMAIL:  mailto:Thomas.Michanek@telelogic.com
WWW 1:  http://www.telelogic.com
WWW 2:  http://hem1.passagen.se/framers
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
See you at the Telelogic User Conference '99, May 19-21, in
Barcelona, Spain: http://www.telelogic.com/news/userconf.asp


** To unsubscribe, send a message to majordomo@omsys.com **
** with "unsubscribe framers" (no quotes) in the body.   **