Login | Register
My pages Projects Community openCollabNet

Discussions > users > Re: Style guide

style
Discussion topic

Back to topic list

Re: Style guide

Author todd fahrner <tfahrner at collab dot net>
Full name todd fahrner <tfahrner at collab dot net>
Date 2002-05-20 10:13:27 PDT
Message On Tuesday, May 14, 2002, at 08:08 AM, Chen Helen - Sun Microsystems
wrote:

> I'm just checking to see if you found the style
> guide for HTML tags within Source Cast pages.

First: apologies for my delay in replying. I tend to get a little worked
up about Web authoring practices, and edit myself into knots.

Apparently the reference was to our style *sheet* (CSS), which isn't
intended to guide the markup process the way a style guide might. While
we have a number of internal documents (and an oral tradition!) covering
style for our application interface per se, we don't impose any system
on client-provided HTML, especially if it already exists. That said,
some kinds of HTML will tend to work better than others, and harmonize
best with the overall production design scheme of SourceCast's UI.
Respond to as much or little of the following explanations and resources
as you can happily accommodate in your editing environment:

For performance, maintainability, and accessibility's sake, SourceCast's
application UI per se is written in a dialect of HTML designed to
support maximum reliance on Cascading Style Sheets (CSS-1, 1996) for
visual formatting, while still accommodating many of the
standards-support foibles of the Netscape 4.x and Internet Explorer
(Windows) families of browsers. It is largely a hybrid of the W3C's
XHTML 1.0 Transitional and Strict DTDs, and formally described in a
Document Type Definition (DTD) hosted here:
<http://style.tigris.​org/nonav/tigris_tra​nsitional.dtd>. Since XHTML 1.0
is merely a syntactical variant of HTML 4, most of HTML 4 is directly
descriptive of our usage as well: <http://www.w3.org/TR​/html4/>.

Validating HTML content against this DTD will help minimize the
likelihood of trouble. It will also serve as a crash course in
real-world CSS-savvy Web authoring, drive you insane, or thrill you with
a godlike sense of omniscience and law-giving power over a mess of
pointy brackets, depending on your experience and temperament. Here is a
validator interface that includes some documentation of the Tigris HTML
DTD and related resources:

   <http://style.tigris.​org/nonav/docs/valid​ator.html>

If you're new to validation, DTDs, etc, the "starter" template below
should help you explore.

<!DOCTYPE html PUBLIC "-//Tigris//DTD XHTML 1.0 Transitional//EN"
"http://style.tigris.​org/nonav/tigris_tra​nsitional.dtd">
<html>
  <head>
   <style type="text/css">
    /* <![CDATA[ */ @import
"http://style.tigris.​org/nonav/css/tigris​.css"; /* ]]> */
   </style>
   <link rel="stylesheet" type="text/css"
href="http://style.tigris.​org/nonav/css/print.​css" media="print" />
   <script src="http://style.tigris.​org/nonav/scripts/ti​gris.js"
type="text/javascrip​t"></script​>
   <title>My title</title>
  </head>
  <body>

  </body>
</html>

Note that it also contains links to our CSS at stable Web addresses, so
you can anticipate the interaction of our styles with your markup in the
body element. Note also that since Netscape 4.x hasn't seen any progress
in the Web standards support department since 1997, I strongly recommend
you investigate in a modern browser (Mozilla derivatives, Opera, IE) for
the sake of seeing the whole picture quickly.

A tool to bring existing HTML quickly into striking distance of validity
against this DTD is HTML Tidy, using one of the versions that supports
use of a configuration file to set several obscure preferences. HTML
Tidy is here: <http://tidy.sourcefo​rge.net/>. Here is a recommended
configuration (paste into a plain text file):

<cut/>

tidy-mark: no
markup: yes
wrap: 0
wrap-attributes: no
wrap-script-literals: no
wrap-asp: yes
wrap-jste: yes
wrap-php: yes
literal-attributes: no
tab-size: 1
indent: auto
indent-spaces: 1
indent-attributes: no
hide-endtags: no
input-xml: no
output-xml: yes
add-xml-pi: no
add-xml-decl: no
output-xhtml: no
doctype: auto
char-encoding: ascii
numeric-entities: yes
quote-marks: no
quote-nbsp: yes
quote-ampersand: yes
assume-xml-procins: no
fix-backslash: yes
break-before-br: no
uppercase-tags: no
uppercase-attributes: no
word-2000: yes
clean: yes
logical-emphasis: no
drop-empty-paras: yes
drop-font-tags: yes
enclose-text: yes
enclose-block-text: no
fix-bad-comments: yes
add-xml-space: no
alt-text: ""
write-back: yes
keep-time: no
show-warnings: no
quiet: yes
gnu-emacs: yes
split: no

<cut/>


While using Tidy and validating will bring HTML into syntactical
regularity and fix many errors, it is not much help in the area of
usage. It will let you know, for instance, that font tags and color and
align attributes are disallowed because redundant with CSS, but not what
to use instead. Here are some generic usage notes:

Think plain, simple, structural. Concentrate not on making things look a
certain way, but on identifying each element of your document using
HTML's element space and nesting rules. Whether or not you care about
accessibility/Section 508 per se, the W3C's Web Accessibility
Initiative's guidelines are an excellent guide to the kind of usage that
works best with SourceCast: <http://www.w3.org/TR​/WAI-WEBCONTENT/>​. Try
to hit all Priority 1 and 2 checkpoints. WAI-compliant content is
incidentally easiest to write and maintain, among other things:
<http://www.w3.org/WA​I/bcase/benefits.htm​l>.

Mark paragraphs with <p></p>, not runs of <br>. In fact, there are very
few uses of BR not better served by an HTML structural block element
with opening and closing forms.

Use HTML's list constructs (UL/OL/LI, DL/DT/DD) instead of, e.g.,
tables/images of bullets, etc.

Use HTML headings (e.g., h3, h4) instead of b/strong/font tags to
describe document hierarchy. SourceCast's application UI hierarchy
begins with h2 (primary heading, unique per document) and ends with h4,
and can be extended one level deeper using DL/DT/DD. For content
appearing within an SC page, h3, h4, and DL/DT/DD are the natural
choices for headings.

About tables: avoid using them except to describe tabular data. A quick
test to determine whether tables are legit in a particular case is to
ask about the row or column headings. If there are none, chances are
your table is bogus. Always use a row or column of table headings (th),
not, e.g., tds with b or strong. Tables that contain row and colspan
attributes are probably overcomplicated, and should be broken into
smaller simple tables interspersed with HTML structural elements like
headings or paragraphs.

That's a lot to start with. Ask in case of difficulty. Specific
questions/problems usually don't send me off into the weeds for so
long. :^)


--------------------​--------------------​--------------------​---------
To unsubscribe, e-mail: users-unsubscribe@st​yle.tigris.org
For additional commands, e-mail: users-help at style dot tigris dot org

« Previous message in topic | 1 of 1 | Next message in topic »

Messages

Show all messages in topic

Re: Style guide todd fahrner <tfahrner at collab dot net> todd fahrner <tfahrner at collab dot net> 2002-05-20 10:13:27 PDT
Messages per page: