PROJECTS: BSD STUFF: FreeBSD docproj tips

Page last modified Mon Dec 6 14:22:43 2004

``Always True'' Tips

• It is probably a good idea to avoid whitespace around — entities. Having whitespace around long dashes is probably going to bite us when the text happens to wrap immediately *before* the dash, resulting in text like this:

         Kerberos provides only one function
         -- the secure authentication of users
         on the network.
  

  This doesn't look too good. One way to avoid it is to precede every — with a non-breaking space (an   entity) instead of plain whitespace. Another is to entirely avoid whitespace around em-dashes. (Giorgos Keramidas)
• Or consider using a colon instead of a dash.

Contentious Tips

• <application> tags look horrible in tables of contents. They render as bold in most CSS-aware browsers and really hurt the eyes of the reader, standing out as they do from the rest of the text. In general, I try to avoid application tags in titles. This is not a hard rule of the Doc Project IIRC; just a personal style note. (Giorgos Keramidas)