OpenOffice.org Style Guide

-Louis Suarez-Potts

$Date: 2004/06/29 14:32:29 $

Update

This style guide is fairly obsolete but not entirely.

OpenOffice.org uses CSS extensively. It didn't use to, and this style guide indicates it does not. For the latest style guide, see The New Style Guide.

 

That said, the colors and layout of tables listed below are still relevant; it's just that we want you to use CSS throughout.

 

 

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@openoffice.org.



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:

    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

    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@openoffice.org.

    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:

    Longer explanation. The tendency in OpenOffice.org has been to use absolute links. That is, links of the form, "//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 "//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: //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, "//". 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

    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.

    <!--Start here. Do not add any header HTML-->

    <!--Heading: H2, default font (we use css, which defines color (as #cc6600) and font face; body text: default; subheadings: H4, default font-->

    <!--Language here is supposed to offer a start, not a finish. Feel free to change it as necessary, but try to keep within the bounds described.-->

    <!--Project mailing lists, project news, are all taken care of now by SourceCast's top navbar. You do not need to add a table for them.-->

    <!--You might wish to include a "to-dos" list or something like that.--><h2>[Projectname] Project </h2>

    <p><i>Last modified: [date]</i></p>

    <br>
    <br>

    <h4>Mission Statement</h4>
    <p>A sentence or two explaining the purpose of the project</p>

    <br>
    <h4>Background</h4>
    <p>A short history, if relevant, of the project.</p>
    <br>
    <h4>Project Summary</h4>
    <p>[A short paragraph informing interested people of the project's scope and to-dos. You might wish instead to include a simple table listing to-dos or associated projects, as below:]</p>

    <br>
    <table cellpadding="4" cellspacing="1" bgcolor="#ffffff" width="100%">

    <tbody>
    <tr>
    <td colspan="3" bgcolor="#00315a" align="Center">
    <div align="left"><font color="#ffffff" size="-1"><b> [To-dos]/[associated projects]</b></font></div>

    </td>
    </tr>
    <tr>
    <td bgcolor="#99ccff" align="Center" width="30%">
    <div align="left"><font color="#00315a" size="-1"> <b>[Type]</b></font></div>

    </td>
    <td bgcolor="#99ccff" align="Left"> <font color="#00315a" size="-1"> <b>[Description]</b></font></td>

    </tr>
    <tr>
    <td bgcolor="#f0f0f0" width="30%"> <font size="-1"> <b>[item 1] </b></font></td>

    <td bgcolor="#f0f0f0" align="Left">&nbsp;</td>
    </tr>
    <tr>
    <td bgcolor="#f0f0f0" width="30%"> <font size="-1"> <b>[item 2] </b></font></td>

    <td bgcolor="#f0f0f0" align="Left">&nbsp;</td>
    </tr>
    <tr>
    <td bgcolor="#f0f0f0" width="30%"> <font size="-1"> <b>[item 3] </b></font></td>

    <td bgcolor="#f0f0f0" align="Left">&nbsp;</td>
    </tr>

    </tbody>
    </table>
    <p>
    <!--Simply replace the items with your own, or delte this table. Style: font size, -1; default face. -->

    </p>
    <br>
    <h4>Participation</h4>
    <!--This language can be changed!-->
    <p> Much of our work takes place in our mailing lists page, which can viewed by clicking on the &quot;Mailing Lists&quot; link in the navbar above. From there, you can subscribe to our lists and view archives. Please familiarize yourself with the discussions that have taken place. Once you have done so, don't hesitate to join in! A convention is that new members introduce themselves briefly before they present ideas and opinions to the community.

    <p>&nbsp;


    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

    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.


    Current Mirror Sites
    Type
    URL
    Login
    Password
    Source Binaries Solver
    Maintainer
    FTP
    openoffice
    <none>
    633 (all platforms) 633 (all platforms)   Bartek Maruszewski
    FTP
    <anonymous> <none> 633, 627, 625, 617 633 (Linux, Win32), in 5 MB parts Michael Niblett*
    HTTP
    <n/a> <none> 633, 627, 625, 617 633 (Linux, Win32), in 5 MB parts Michael Niblett*
    HTTP http://sapi.vlsm.org/openoffice/ <anonymous> <none>   633 (ZIP for Win32)   Rahmat M. Samik-Ibrahim
    FTP ftp://sapi.vlsm.org/openoffice/ <anonymous> <none>   633 (ZIP for Win32)   Rahmat M. Samik-Ibrahim
    FTP ftp://sapi.vlsm.org/openoffice/win32split/ <anonymous> <none>   633 (ZIP for Win32) in 1440000 byte parts Rahmat M. Samik-Ibrahim
    HTTP http://sapi.vlsm.org/openoffice/win32split/ <anonymous> <none>   633 (ZIP for Win32) in 1440000 byte parts Rahmat M. Samik-Ibrahim
    HTTP http://office.qkaka.com/ <n/a> <n/a>   localized 627 zip   H.Z.
    FTP ftp://ftp.3way.com.hk <anonymous> <none> All current binaries, solver, and source; files in parts. Nelson Lau

    Particulars

    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

    Here is a nested table, also from the homepage. Note: it is unbordered.

    Truly useful news
    Community Survey Report (472KB pdf) 3 August
    Roadmap: the guide to OpenOffice.org 9 July
    Build 633 18 June
    Screenshots 9 July
    Newsletters Always

    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

    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.

    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:

    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="//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="//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="//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="//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.

    [Your heading here]
     

    [content]
    [content]
    [content]

    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@openoffice.org.