All files (HTML, CSS, images) included in EnHacklopedia are licensed under the Creative Commons Attribution-ShareAlike 3.0 License. All authors contributing to EnHacklopedia should be made aware of the license before contributing. If the author does not agree to the licensing, his or her contributions will not be accepted into the project.
Editor settings described in this section should be used to help with WYSIWYG editing for all contributors. Many text editors available are configurable enough to allow changing these settings as required, and some even default to our preferred settings. We recommend using editors with syntax highlighting to help easily catch certain mistakes during the writing process. Some editors to consider are TextPad on Windows and Smultron on Mac OS X.
Tab stops should be equivalent to 4-character columns. For example:
<div class="section"> [tab]<h1>Hello World</h1> </div>This text should appear in your editor as:
<div class="section"> <h1>Hello World</h1> </div>
Your editor should allow saving text documents with UNIX line endings (LF). We don't want any of those Windows "Dark Side" line endings (CRLF) or Mac OS Classic line endings (CR). All text editors on UNIX-like operating systems (including Mac OS X) will save files with UNIX line endings by default. On Windows, the aforementioned TextPad text editor has an option to convert files to UNIX line endings.
Each section is to have its own file, preferrably named with no more than three words, seprated by underscores. All XHTML files must use the extension .html and CSS files to use the extention .css. The main start page will be named index.html. All file names must contain only lower case letters, numbers, and underscores. Periods are only allowed for the file extension.
Path names to all linked files must use relative addressing; do not prefix paths with a slash (no absolute addressing). Any offsite files must be prefixed with "http://", but keep offsite links to an absolute minimum. It is suggested that the only offsite file links be permanent files. This includes standards/licensing references and standards/licensing icons. Use the "../" relative notation when you need to link to a file that is up one directory. Never use the "./" current-directory notation.
Images also follow the path and naming conventions above. They reside in images/page_filename/. Any images used must be public domain or your own creation (screenshots, etc). Don't go stealing them from random sites like some of us used to. All images should be in PNG format, if at all possible. The exception would be public domain images that were originally JPG/GIF. Do not convert from any lossy format (JPG especially) to PNG. Note that images are currently block level and centered by default in the latest CSS. To put it simply, they break the lines; no <br /> required before or after unless making additional space. Using class="inline" should allow images to sit side by side if desired.
Class names and IDs follow the file naming conventions although they might need more than three words to describe; they must contain only lower case letters, numbers, and underscores. IDs should be prefixed with a word common to its parent section and subsections, if any. For example, this document contains a section CSS inside this hierachy of sections: Formatting » XHTML 1.1 and CSS 2.0 Compliance » CSS. The ID linking to the CSS subsection is therefore "formatting_xhtml_css"; one word per section and subsection.
Section and subsection names should be descriptive, but concise. Redundancy should be avoided as much as possible. For example, try to avoid phrases like "how to" in your section descriptions.
You should start each major word with a capital letter in your section names. Some words that are NOT considered major are and, or, not, the, with, by, to, as, is, and any abbriviation. However, abbreviations should be used with caution. Some abbreviation such as etc. are acceptable in most cases. (See also: Spelling.) Avoid using punctuation in section names; no full stop (ending period), use and instead of an ampersand (&), follow the Punctuation guidelines.
We will be creating all of our pages with XHTML 1.1 and CSS 2.0 compliance. The only CSS allowed in the XHTML document is through the use of classes (no "style" attributes on any XHTML element). The reason for this is separation of content and style; XHTML creates the content; CSS creates the style, look, and feel. Some "presentational" elements will be allowed in the XHTML for classic (non-CSS) browsers. These elements are <h1> - <h6>, <strong>, <em>, and <table>. We consider tables to be presentational in nature, due to their objective of arranging contents in a specific manner.
This is the XHTML header template that should be used on all pages.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>EnHacklopedia » Page Title</title> <link rel="stylesheet" type="text/css" href="main.css" /> </head> <body> <div class="header"> <a href="index.html">EnHacklopedia</a> » <a href="root.html">Document Root (If Any)</a> » Document Name </div> <div class="header_space"> </div>
This is the XHTML footer template that should be used on all pages.
<div class="footer"> <a href="http://www.getfirefox.com"> <img src="images/standards/get_firefox.png" alt="Get Firefox" width="88" height="31" /> </a> <a href="http://validator.w3.org/check?uri=referer"> <img src="images/standards/valid_xhtml11.png" alt="Valid XHTML 1.1" width="88" height="31" /> </a> <a href="http://jigsaw.w3.org/css-validator/"> <img src="images/standards/valid_css.png" alt="Valid CSS!" width="88" height="31" /> </a> <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/"> <img src="images/standards/creative_commons.png" alt="Creative Commons License" width="88" height="31" /> </a> </div> <div class="floating_footer"> <a href="index.html">EnHacklopedia</a> » <a href="root.html">Document Root (If Any)</a> » Document Name </div> <div class="footer_space"> </div> </body> </html>
Just as with all XHTML 1.1 documents, all tags must be lower case, all empty elements must be self-closed (<br />; notice the space preceding the forward slash), and all uses of the ampersand character (&) must be written as & (including within links and URLs).
Every "container" element should have its contents indented with a single tab (no spaces), with a few exceptions. Container elements written entirely on one line (<p> tags especially) obviously do not need any indentation, and <pre> elements must NOT be indented at all. All of these multi-line elements must have the open and closing tags on their own lines, with its contents indented inbetween.
Attribute values should be surrounded by double quotes only. The values themselves should be lower case wherever possible, especially when using the id and class attributes (class="section").
When using <br /> elements, place one on each line that it is supposed to break. This means one <br /> element is allowed at the end of a text line or following an inline element, along with one for each following empty line as required. Do not stack your <br /> elements on a single line; a physical line break (plus proper indentation) is required after every <br /> element.
In cases where a line break is supposed to follow a block-level element like <div> or <fieldset>, by sure to place the <br /> element on the following empty line; block-level elements have their own line breaks, and we wish to reflect this fact within our XHTML.
Emtpy lines should contain no white space (spaces or tab stops), and no lines should end with any white space. Modern text editors have options to remove trailing white space from each line in a document; use them! Some editors (TextPad, for example) will automatically strip trailing white space from XHTML and CSS documents when they are saved. All files must contain one empty line at the end of the document.
See Sections and Subsections for a list of additional sections required on each document.
All CSS should be available in a single CSS file (no <style> tags). In some cases it may be necessary to include additional CSS classes that are only useful on one or two pages. For these cases, a new CSS file should be created with the exact page name (except the extension) of the page that uses it. Such cases should be kept to an absolute minimum. The more CSS files, the more difficult it will be to modify document styling in the later stages.
Your CSS should be written with the opening bracket directly following the class or element name (selector), followed by the semi-colon separated declarations. Every declaration must then me indented, one declaration per line, with the final declaration also having its own ending semi-colon.
Try to avoid using keywords like red or black. Use HTML hex color values instead; #FF0000 and #000000. These are much more versatile and customizable than the keywords, even if they are a little bit harder to remember. Just keep in mind that the format is #RRGGBB for Red-Green-Blue, and the higher the value, the brighter the color.
There are several sections that every document is required to have. It is up to the authors to keep these sections maintained as needed. These required sections are an addendum to the XHTML header. (See XHTML.) These sections are required to show at the top of the page in the following order.
The first requirement is the Table of Contents menu. See Menus for more information.
The Legal section appears directly following the Table of Contents. This ensures the license is near the top of the page, making it easily accessible to readers.
<div class="section"> <h2 id="legal">Legal</h2> <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/"> <img alt="Creative Commons License" src="images/standards/creative_commons.png" width="88" height="31" class="float_left" /> </a> <p>All files (HTML, CSS, images) included in EnHacklopedia are licensed under the <a href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution-ShareAlike 3.0 License</a>. All authors contributing to EnHacklopedia should be made aware of the license before contributing. If the author does not agree to the licensing, his or her contributions will not be accepted into the project.</p> </div>
Finally, the History section lists all page version dates in descending order followed by an unordered list of changes made since the last version, and the author's name in parentheses at the end to attribute each change.
<div class="section"> <h2 id="history">History</h2> <ul> <li> 03-12-2007 <ul> <li>Added <em>XHTML 1.1 and CSS 2.0 Compliance</em> section. (Parasyte)</li> <li>Additional CSS styling. (Parasyte)</li> <li>Grammatical and spelling corrections. (Parasyte)</li> </ul> </li> <li> 03-11-2007 <ul> <li>Initial release. (Parasyte)</li> </ul> </li> </ul> </div>