From owner-freebsd-doc Tue Jan 7 21:13:43 1997 Return-Path: Received: (from root@localhost) by freefall.freebsd.org (8.8.4/8.8.4) id VAA13088 for doc-outgoing; Tue, 7 Jan 1997 21:13:43 -0800 (PST) Received: from fallout.campusview.indiana.edu (fallout.campusview.indiana.edu [149.159.1.1]) by freefall.freebsd.org (8.8.4/8.8.4) with ESMTP id VAA13083 for ; Tue, 7 Jan 1997 21:13:40 -0800 (PST) Received: from localhost (jfieber@localhost) by fallout.campusview.indiana.edu (8.8.4/8.8.4) with SMTP id AAA02225; Wed, 8 Jan 1997 00:13:37 -0500 (EST) Date: Wed, 8 Jan 1997 00:13:37 -0500 (EST) From: John Fieber Reply-To: John Fieber To: Sean Kelly cc: doc@FreeBSD.ORG Subject: Re: Typographic conventions In-Reply-To: <32D2D2C5.700C@fsl.noaa.gov> Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@FreeBSD.ORG X-Loop: FreeBSD.org Precedence: bulk On Tue, 7 Jan 1997, Sean Kelly wrote: > As a general rule, I prefer to see as little variation in typography as > possible; some computer books out there have so many different > conventions for so many different things that a page appears as > something not too unlike dog vomit. Oh, thanks for reminding me. How about falshing blue bold italic text on a red background for warnings? (just kidding...) Generally I agree with typographic conservatism for technical documents, but after thumbing through more books, I think more of these elemnts should deviate (slightly) from body text. That said, boldface is typically too LOUD to hit in the middle of the body text. Italic works out okay in print, but not so hot on screen. The books I liked best mostly use fixed space fonts for text that might be involved in your interaction with the computer. This includes commands, command options, filenames, function names, variables and the like. > > Abbrev- Abbreviation, especially one followed by a period > > Chicago probably says small caps ... I say normal body all caps. Chicago devotes 27 pages to the topic of abbreviations and although a select few are subject to small caps treatment, a majority are body text, mixed case. > > Command- Executable program, or the entry a user makes to execute a command > > Urg. Good question. I vote fixed space. Same for command options. > > Emphasis- Emphasized text > > Bold. Italic emphasis is nice, but often too light. I don't think anyone will agree here. :) I hate bold, but a good friend hates italic.... > > FirstTerm- First occurrence of a word in a given context > > Italic? Italic. :) > > ForeignPhrase- Word or words in a language other than that of the containing document > > Chicago probably says italic. There are so many foreign words in > English now that we can probably do without. Body copy font. Italic. There are so few in English that people recognize as being foreign, I seriously doubt too many will be marked up. > > GUIIcon- Graphic and, or, text appearing as a icon in a graphical user interface > > Tufte would recommend using a copy of the icon itself as any other > glyph. I agree. Graphics are a bit of a thorny issue logistically speaking, although I would agree that a copy of the icon itself is more or less manditory. > > GlossTerm- Term outside a Glossary that is defined in some GlossEntry > > Italic. Depends on how it is used. If taken to the logical extreme where every term in the body also found in the glossary is mared up, an on-line version would have hypertext links which don't need any other typographic treatment. A print-only version with every 10th word italic would drive you batty. (Personally, hypertext documents with every 10th word a link would drive me batty as well. Somone here just finished a dissertation on optimal hypertext link density and found it to be quite low. Too many links interfere with reading and understanding the text.) I would tend to say copy text and leave the italics to foo. > > InterfaceDefinition- Specification for a graphical user interface > > Huh? Ditto. I have to find an actual example before I get this one. > > KeyCap- Text printed on a physical key on a computer keyboard, not > > necessarily the same thing as a KeyCode > > Small caps? A pain to do in HTML, but possible. > > Parameter- Part of an instruction to a computer > > What's the difference here with Replaceable? Maybe italics, maybe body > copy font. Not exactly sure, altough they definately have different content models. I'll have to try and find some more docs on this. The sample document that I've been working on lately can be found at: http://fallout.campusview.indiana.edu/~jfieber/mydevel.docb and formatted at: http://fallout.campusview.indiana.edu/~jfieber/mydevel.html -john