OpenOffice.org Style Guide

-Louis Suarez-Potts

Last modified 26 August 2001

Preface

This style guide has grown from it initial short version to something much longer. However, thanks to the wonders of hypertext, one need not read all of it; just the relevant sections. The three most important sections are featured in the "Quick Start" and include: The Project Index Page, Linking, and style sheets (CSS). Other sections describe the OpenOffice.org website, our style, how to do OpenOffice.org tables, and so on.

This guide is meant to be viewed by a Web browser, or by a WYSIWYG HTML editor. If you do look at it through an editor such as HomeSite or BBEdit, things will look strange, as I wrote it presuming people would see it from a browser's perspective. I have tried to include as many "cut-and-paste examples" as I could think of; these are clearly labeled as such below. You can also just copy from the existing website.

If you have questions, please send them to me: louis@collab.net.

Contents

Quick Start

Introductory

Overview: HTML

About the OpenOffice.org Website

The OpenOffice.org Style

Using Tidy

Style Sheets (CSS)

Linking, Or, How to Write Links That Work

Absolute vs. Relative Links

The Project Index Page

Index Page Templates

Samples: Viewed as HTML

Tables

The Simple Table (Bordered)

Sample

Table Formatting: General

Table Formatting: Particular

What this table looks like in HTML

Cut 'n' Paste Sample

The Simple Table (Unbordered)

Sample: Unbordered Simple Table

Simple, Unbordered Table, in HTML

The Nested Table

Table Formatting, Exterior, General

Table Formatting, Exterior: Particulars

Table Formatting: Interior Table

Interior Table Particulars

Here is what this table looks like in HTML

Sample Nested Table

Conclusion

Another style guide: recommended!

Quick Start

What to do

Use our index page template. Or, use StarOffice or OpenOffice.org to create your index page. Either way, follow these conventions:

• Headings: No h1. Use h2 for the largest heading, with h3 and h4 for subheadings. If you use h1, nothing bad will happen, it will just look odd.
• Leave fonts as default. Exceptions: code font.
• No document title. It won't appear, or it may appear in an ugly fashion at the top of the page
• Use relative links.

That is about it. There is no need for h1 heading, as it is rather too large. If you use StarOffice/OpenOffice.org, you can conform your page to OpenOffice.org standards using Tidy. Tidy will configure the page so that it does not disrupt the operation of SourceCast. For more information about the OpenOffice.org website, please read below, "About the OpenOffice.org Website."

Introduction

Overview: HTML

I won't bore you with a definition of HTML, but basically an HTML page or document is comprised of plain, unformatted text with embedded commands in the text adjacent to the target text that stipulate the way the target text should look when viewed according to certain conventions by certain technologies. These commands are called "tags," come in paired sets, and look like regular text: <b>bold</b>, for instance, gives you bold. Not terribly complicated, the idea is simplicity itself. A browser constructed and instructed to view these tags according to the accepted standards and conventions will thus read the tag for bold as indicating that the characters within the brackets should be represented in boldface. More involved tags do the same logical thing only more elaborately.

Note: When coding in HTML you have to tell the browser when to start reading something and when to end reading it: The opening and closing tags. These tag pairs may be separated by any number of characters, but must be nested. Thus: ABC...CBA.

Almost all modern word processing software such as StarOffice are able to convert formatted text into HTML pages that look the same (or close enough), when viewed by a suitable browser (less suitable: older browsers that are not equipped to read the latest HTML conventions). As well, really rudimentary word processors and text editors can be used. In fact the HTML hackers among us prefer dumb programs that don't add any extra formatting, because they rightly want to be in control of what it is they are creating, and have no nasty surprises in store. A bugbear of HTML coders is that different browsers read code differently, which makes sense, if you think of a browser as a mechanical renderer of text that proceeds according to certain conventions.

(If you are interested in learning more about HTML construction, a good place to start is http://www.W3C.org)

In short, you can create your Web (HTML) pages using StarOffice (or OpenOffice.org) or some other text processor...but there are some caveats. I'll deal with them in the next section.

Back to top

About the OpenOffice.org Website

We have a fairly simple architecture in which there is static element framing a dynamic element. The static element comprises the header, footer, title, and navbars. The dynamic only consists of the content in the middle: the body of the text. Using the latest technology, these static and dynamic elements are composited together, producing a coherent Web page.

Because of this arrangement, you cannot (or at least should not) create pages that also have those parts the static section supplies. That is, any page created for the OpenOffice.org website should start with whatever you have to say--the content--and that's it. No<head>, <title>. <body> tags. Only your content.

And if you do include such tags, what will happen? Probably nothing exciting. Browsers read from left to right, top to bottom, so it will read the static tags first (which is why all our pages are dumbly remembered in the browser as "www.openoffice.org" no matter what their content), and will very likely simply ignore your redundant tag. At most the text between the title tags will appear at the top of your page in black default font.

There are exceptions. If you write a "meta" tag and are stipulating XHTML or something else that deviates from the kind of HTML declared in the static tag, the browser will likely understand your stipulation and proceed accordingly. And, you can certainly use page-local cascading style sheets (CSS). (StarOffice, like Microsoft Office, saves formatted documents using styles.) However, unless the styles are clearly defined in the document or in a page loaded with the document, they may not be read appropriately, as they may conflict with OpenOffice.org's own styles. (See below, Style Sheets.)

Note: For various reasons, please only use lower case not UPPER CASE HTML formatting. Thus: <bold> not <BOLD>. If you use upper case, nothing bad will happen. However, XHTML (which is a more flexible form of HTML) does see case differences, so our preference now is for lower case tags.

Back to top

The OpenOffice.org Style

As already mentioned, our pages are simple, with very few jpgs, gifs, or any other graphics, and no animation of any sort. We use a simple three-color scheme of blues and lots of white spaces. This makes the pages easy to read. We also use a kind of reddish-brown for h2 headings. All these attributes are determined by our style sheet. See the above "Styles" and "Sample" for further insight.

For general pages

• Background: Do not specify a color. Our style sheet in the static element does that for you. You can specify a background color for a table; see below.
• Text: Black and default font
• Page Heading:
  • Format: Heading 2 (h3) for big headers (page names, say), heading 3 (h3) for smaller subheadings; heading 4 (h4) for below that
  • Face: Default
  • For example, the heading to this page looks like this in HTML: <h2>< > Style Guide</font></h2>
• For smaller headings (section headings, for instance) use the same face color/style, but diminish the size appropriately. (See below, example 1.)

Back to top

Using Tidy

Get and configure HTML Tidy for your editing environment. This terrific utility cleans up broken HTML instead of merely complaining about it. As Todd Fahner, who is generally deemed one of the leading experts in HTML composition writes, "I strongly recommend using it to achieve the initial xhtmlification of the files. Unfortunately, markup-oriented tools turn Velocity (formerly WebMacro) logic into hamburger, so you can't run the tool on the source. But you can run it on the output and then manually merge it back into the source. It's better than re-keying it all. Use this config file for Tidy.

I recommend you use Tidy if you have created your Web page using a text-processor such as StarOffice or OpenOffice.org, or, if you have used a WYSIWYG HTML editor such as Dreamweaver or Go Live, both of which impart their own characteristics. (A good WYSIWYG editor that is quite clean is Amaya, which is preferred by the W3C. Amaya runs on Windows.

Back to top

Style Sheets

OpenOffice.org now uses style sheets. This is good, as style sheets allow us to place all the formatting information on one sheet which a browser then refers to. As a result, both page size and access time are reduced, dramatically so. But there are some consequences. If a user has turned off the style sheet option in their browser, they will not see the page as it has been designed. They will see something considerably drabber, but still perfectly functional.

Consequences. Our style sheet determines the font and font-face: of the Arial, Helvetica, sans-serif family; h1 is black, h2 is #cc3300 (a reddish brown), h3, h4, black. If you stipulate your own fonts and font-faces, your page may not display properly, as the browser will essentially pick and choose syntagmatically from the options presented it. Your page may look a mess, in short.

Therefore: do not stipulate any font or font-face. Leave it blank. If you have created a page that's a conversion from a StarOffice or OpenOffice.org document, see if you can use Tidy to clean it up. If you cannot, see if you can strip the font and font-face information by hand, so that only the font heading information (h1, h2, h3, etc.) remains. And if that fails, don't worry, probably nothing bad will happen, your page will just look a little odd.

Note. If you would like additions to the style sheet, please let me know by sending mail to louis@collab.net.

Back to top

Linking, Or, How to Write Links That Work

Absolute vs. Relative Links

We now use relative links.

Note: Please use relative links of the form described below:

• For top-level, "index.html" pages, use : "/[directoryname]/[doc.html]" when referring to documents in the directory below the one in which the index.html is located. That is, if you have an index.html page that refers to, say, "specialstyles.html" in the directory "special," you would use "/special/specialstyles.html". Failure to use this convention will routinely result in broken links.
• In contrast, when referring to documents within a directory, please use: "[doc.html]," without a preceding slash. If you precede the filename with a slash, you will take the browser to top-level directory.
  • Thus, if you are writing a link from within the index.html page of the "main" directory referring to a document in a subdirectory, it would be /foo/foobar.html. And if you aer writing a link from the "paper.html" page within the /main/ directory to the /foo/foobar.html page, you would write as: "<a href="foo/foobar.html">", without the preceding slash. This is because if you include it, it tells the browser to go to the root directory, which unless you are writing from the root, is not what you want.
• Do not precede the filename with a period, as in "./[doc].html". Doing so will result in unpredictable behavior (of SourceCast).
• When referring to links above the directory in which you are working, use the standard convention of "../" per directory rung. Thus, if you are in /foo/ and you want to refer to "whee.html in /main/ you would write: "<a href="../whee.html">" ; and so on, with ../ denoting a move up to the root index of that directory.

Longer explanation. The tendency in OpenOffice.org has been to use absolute links. That is, links of the form, "http://www.openoffice.org/styles/index_template.html" referring to a file in the same directory as this document, rather than "/styles/index_template.html" (written in the www/index.html page). Both addresses refer to the same document--the index template; the former is, however, is called "absolute" because the path won't change to reflect any movement of the directory in which the documents live. In contrast, a "relative" link, "/index_template.html" allows for greater flexibility. All documents in the /styles/ directory can be moved along with the directory, and HTTP addresses will work, no matter where they are subsequently placed.

Thus, if I were to relocate "http://www.openoffice.org/styles/index_template.html" to, say, the /betterstyles/ directory, I'd have to rename each and every HTTP address, which would be a real pain. But if I did the same for "/index_template.html" I wouldn't have to rename anything, as long as I kept the logic of directories and indexes straight.

Back to top

The Project Index Page

SourceCast has transformed some of the features of the project index page, or homepage. The most important: we no longer use a table to represent all the mailing lists, archives, and subscription information. Instead, the top navbar has a link that more than adequately provides this information. See below, Sample Page, for a more or less typical index page. You can also go directly to the project index page template: http://www.openoffice.org/styles/index_template.html.

As well, the project owner's name is now automatically generated by SourceCast, meaning that you do not have to provide it.

Index Page Templates

An "index page" is the homepage of a directory. It is what is delivered when someone enters, say, "http://www.openoffice.org/". The server will look for the index page and serve it up; if it is lacking, nothing will happen. SourceCast allows you to configure your index page while you are creating a project, or even to use the HTML text that you enter in a box in the project creation page. But for better homepages (and ones that will more reliably be served up), we recommend you create and load to CVS an index page.

Regardless of whether you intend on using the SourceCast provision or creating an index page, the same question obtains: What should you put on your index page? Enough so that visitors and prospective developers will know something about the project, the goals, the things that have to be done. Accordingly, I have created an index page template. It is for generic projects, and has sections for statements about the mission of the project, history, a table for to-dos or modules, and so on. Configure it by deleting or duplicating some elements.

Note. SourceCast has made it trivially easy to subscribe and unsubscribe to mailing lists and to view and search mailing list archives. Visitors need only click on the "Mailing Lists" link on the project's top navbar to view the options. However, consider encouraging participation in the project by having a brief description of the mailing lists, and what they are about. You need not have links for subscribing or viewing archives, as those are taken care of by the project navbar Mailing List link.

The template below should provide you with a quick means of starting a new index page. If, however, you prefer to create your index page using StarOffice or OpenOffice.org, please at least follow the conventions described above and presented below. To use this, simply

• Generic project index template

Back to top

Sample: Viewed as HTML

If you are curious about how the above page looks like in "HTML," the below Whiteboard index template exemplifies how simple the coding is.

Note: You will notice the absence of header and footer tags; the static element takes care of that.

Back to top

Tables

We have two primary table structures. One is simpler than the other; use it when you have fewer headings to cover. Depending on the nature of the information to be displayed, it can consist of two nested tables: the outside table provides the border, the inside the data. The more complex table has no border and uses only one table to supply the content.

The Simple Table

Most of our tables are of a simple design and are unbordered. That is, the border is either left blank

Not all of our tables have borders. Indeed, most of our tables do not have borders. The logic that determines your aesthetic decision: the nature of the information that must be represented in the table. A table needing a header and column heads will not need the border. The final call, however, is up to you. For what it is worth, mailing list tables (such as the example below) have no borders, but informational tables, such as news tables, do. As a rule, avoid replicating information, e.g., don't have a table title outside the table and also within the table, as a heading.

Sample: The Simple Table

From the homepage of the UDK Project, I have taken a sample table that is neatly laid out. The same table, with the HTML coding shown, is displayed below. (By the way: the legacy trend is to center the heading, etc.; I am moving away from that, and urging all to position the headers on the left.)

Interesting modules outside the UNO Development Kit Project
Module	Function
sal	The System abstraction layer implements a basic abstraction of the underlying system. For your components to be system independent you should you SAL. SAL includes abstractions for thread creation and synchronization. Mechanisms for process communication and file system access are also part of this library. Management of libraries and profiles is also included. Functions for creating and manipulating strings and wide strings belong to SAL. SAL only exports functions conforming to the c calling convention. So, it should be suitable to be a system abstraction for any language.
store	This project provides the hierarchical storages for the component registry.

Particulars

• Table width: 100%
• Cell Pad: 4
• Cell Space: 1
• Border: Leave blank
• Border Color: Leave blank
• Background: Leave blank
• Cell Color: #fofofo

Note how white lines structure the table cells? That's because the page background is white (#ffffff) but each cell's background is off-white (#fofofo). You can achieve the same effect by setting the table's background to off-white (#fofofo) and setting the border to white (#ffffff). The table below, from the Mirrors page, does just that.

Particulars

• Table width: 100%
• Cell Pad: 4
• Cell Space: 1
• Border: 1
• Border Color: #ffffff
• Background: #fofofo

Note: You can cut 'n' paste this table into any document needing a mailing list table. (And, by deleting the elements, you can use the table for other purposes.)

Back to top

Simple, Unbordered Table, in HTML

<table cellpadding="4" cellspacing="1" bgcolor="#ffffff" width="100%"> <tr> <td colspan="2" bgcolor="#00315A" align="CENTER"><font color="#ffffff" size="2"><b> Interesting modules outside the UNO Development Kit Project </b> </font></td> </tr> <tr> <th bgcolor="#99CCFF" align="CENTER"><font color="#00315A" size="2"><b> Module </b> </font> </th> <th bgcolor="#99CCFF" align="CENTER"><font color="#00315A" size="2"><b>Function </b></font></th> </tr> <td bgcolor="#f0f0f0" valign="top"><code><a href="cpp/ref/sal/index.html">sal</a></code></td> <td bgcolor="#f0f0f0" valign="top"> The System abstraction layer implements a basic abstraction of the underlying system. For your components to be system independent you should you SAL. SAL includes abstractions for thread creation and synchronization. Mechanisms for process communication and file system access are also part of this library. Management of libraries and profiles is also included. Functions for creating and manipulating strings and wide strings belong to SAL. SAL only exports functions conforming to the c calling convention. So, it should be suitable to be a system abstraction for any language. </td> </tr> <td bgcolor="#f0f0f0" valign="top"><code><a href="cpp/ref/store/index.html">store</a></code></td> <td bgcolor="#f0f0f0" valign="top"> This project provides the hierarchical storages for the component registry. </td> </tr> </table>

Back to top

The Nested Table

A nested table consists of at least two tables, an exterior, bordered table, and an interior table with invisible borders; this is where the content is. The basic colors and styles of the nested table are like the simple, un-nested table. The advantage of nesting tables lies, then, in that you can create a bordered table with cell demarcators that differ from the exteriors. This can be quite useful.

Table Formatting, Exterior, General

• Width: 100%
• Height: Leave blank; in pixels
• Cell pad: 0
• Cell space: 0
• Align: Default

Note: The border for the above table is not set; you can, for your particular table, however, set it to "1" and make the exterior color light blue: "#99CCFF.

Table Formatting, Exterior, Particulars

This external table includes a row for the header.

• Header text: White (#ffffff), bold, no formatting. Size: you can alter this by shrinking it to -1; that call is up to you.
• Heading background: Dark blue (#00315A)
  

Back to top

Table Formatting: Interior Table

The interior table is a regular table with the border set to 0 or left blank. This way, you can organize information in a tabular fashion without having the borders of the cells interrupt your aesthetic. The rule is:

1. Make your table, setting border = 0 or leave it blank. (There is a difference in the settings. Play around a little; I prefer to set the border to blank.)
2. Position the interior table within the exterior table and set the width = 100%; leave the height blank, in pixels. The interior table should map perfectly to the limits of the exterior table.
3. You can also do other things to accomplish the same effect, such as coloring the cells, etc. Experiment; it's a pleasant way to use up time
   
   

Interior Table Particulars

The interior table above has the following characteristics:

• Border = 0
• Cell Pad = 2 (you can raise it; lowering it is not recommended)
• Cell Space = 0 or leave blank
• Content background: Pale blue (#fofofo) (as will all tables)
• Content text: Black, default font, no formatting. Size: you can shrink the size to -1; that call is up to you.

Back to top

Here is what this table looks like in HTML

<table width="100%" bordercolor="#99ccff" bgcolor="#ffffff" cellpadding="0" cellspacing="0"> <tr> <td height="18" bordercolor="#99ccff" bgcolor="#00315A"><font size="-1" color="#ffffff"><b>Truly useful news</b></font></td> </tr> <tr> <td> <table width="100%" border="0" cellpadding="2" height="100%"> <tr> <td height="8" width="82%"><font size="-1"> <a href="/about_us/surveyreport.pdf">Community Survey Report (472KB pdf)</a></font></td> <td height="8" align="right" width="18%"><font size="-1">3 August</font></td> </tr> <tr> <td height="8" width="82%"><font size="-1"><a href="http://www.openoffice.org/white_papers/index.html">Roadmap: the guide to OpenOffice.org</a></font></td> <td height="8" align="right" width="18%"><font size="-1">9 July</font></td> </tr> <tr> <td height="8" width="82%"><font size="-1"><a href="http://www.openoffice.org/dev_docs/source/download.html">Build 633</a></font></td> <td height="8" align="right" width="18%"><font size="-1">18 June</font></td> </tr> <tr> <td height="12" width="82%"><font size="-1"><a href="http://whiteboard.openoffice.org/screenshots/index.html">Screenshots</a></font></td> <td height="12" align="right" width="18%"><font size="-1">9 July</font></td> </tr> <tr bordercolor="#99ccff"> <td width="74%" height="14"><font size="-1"><a href="http://www.openoffice.org/trulyusefulnews.html">Truly useful archives (two weeks plus)</a></font></td> <td width="18%" height="14" align="right" bgcolor="#ffffff"><font size="-1">Always</font></td> </tr> </table> </td> </tr> </table>

Back to top

Sample Nested Table

Here is a sample nested table. It may be easier to add content to the interior table first, then cut and paste the completed interior table into the exterior table shell. So, I've split them up.

Back to top

Conclusion

Another style guide

Todd Fahner has created a brief but beautifully clear style guide that also explains how to use style sheets. It is still a work in progress, so be sure to check back on it periodically, but I heartily recommend it.

And, if you have any questions, or wish to add (reasonable) material, please let me know: louis@collab.net.