Kitab-i-Aqdas -- parameters

Parameters

for all programmers involved in the construction of

The Kitáb-i-Aqdas Project

This is the first attempt at codifying the HTML/CSS structure of the Kitáb-i-Aqdas Project for others, and putting in writing the basis of some of the design concepts such as proportion and spacing. All of this has, till now, lived only in my heart and my head. Not being used to writing this style of page, it will tend to ramble; future revisions will see improvements and refinement.

It must be stated first that, as the Kitáb-i-Aqdas Project moves into the future, there will be many opportunities to incorporate other types of coding, such as javascript, XML, or other means of delivering information to an end user. This is still an early stage in the evolution of this Project toward its full capacity - it is more important at this time to develop the concept; future programmers will take this concept and remodel it to suit the technology of that time. In this regard, all modification must be examined carefully in the light of the following statement:

Just because it can be done, is not alone sufficient reason for it to be done

All changes, whether to presentation or coding, be it layout, style, navigation or delivery, must be carefully weighed in this light. Changes must always take consideration of the lowest common denominator, and must demonstrate added value – some of the questions that must be asked (and there are still others) must be: does it improve the capacity of the user to navigate the site? does it improve access to the information? does it remain quick to load even when the user has only the slowest available connection (at the time of writing this, generally a 56K modem)? can the lowest levels of hardware and/or software display the change/addition as intended? does it improve the aesthetics/appearance? and so on.

A standard template for new pages will be found at the end of this document, plus templates for the various parts that format the content.

It is expected that every new programmer to this Project will spend some time familiarising themselves with the existing code in the Project, and with the CSS stylesheet used; that they will, before keying even one line of code for the Kitáb-i-Aqdas Project, experiment by creating pages in the style of the Kitáb-i-Aqdas Project, using the stylesheet “my.css”, that they may understand how and why it all fits together.

English usage issues

British English will be used for spelling throughout the Kitáb-i-Aqdas Project. Though the reason for this is, to a small degree arbitary, to a greater degree the reasons are that Shoghi Effendi used British English spelling, and to provide a consistent spelling standard throughout the Project.

Acronyms are totally forbidden, except where the text being copied into the Project already carries an acronym. In this case, faithfulness to the text must take priority; however, a <span title="meaning of acronym">acronym</span> element will be used around it to provide a popup of the meaning of the acronym to the user.

Summary of structure

Layout is defined through the use of standard “containers” and standard “spacers”, as defined in the Cascading Style Sheet (CSS) ‘my.css’. The result of using only these standard elements is a consistency of proportion. Bearing in mind that there are a variety of browsers in use, which as a general rule apply styles inconsistently, and that users can be using a variety of screen resolutions and can set their font sizes to their own taste, the proportions need to be based on common denominators. Thus, all proportions are based on the “em” and on percentages. Layout is managed through the use of standard “containers”, “indents” and “spacers” The use of the HTML element <p> as a paragraph/element divider/spacer is not permitted.

Containers.

There are three “containers” used in this Project. Their purpose is to provide the horizontal spacing for elements (and in the case of a table, some layout functionality). These “containers” are:

• main-container

This is the container within which the next container type, the indents, perform their function. It is set to use 80% of the width of the browser window, and is placed centrally within the window (i.e. leaving a 10% left margin). All the indents used on this page are placed within this "main-container" See the template at the bottom of this page for usage.

• …-…-indent

The naming may at first appear confusing. The use of the term ‘indent’ should, however, be viewed as a convention rather than as a description.

There are five primary indents in use - if more than this are needed, it can be achieved by nesting these indents (for example, by using an indent as a pseudo main-container). These indents will primarily be used within a "main-container", but, where a <table… has been declared should also be used within the <td>…</td> section(s) of that table. All the visual indents on this page have been actioned using these predefined indents within a "main-container". Each indent has a prefix which will be discussed following this list:

…-first-indent – 100% of the width of the containing element, no left margin

…-second-indent – 97% of the width of the containing element, 3% left margin

…-third-indent – 94% of the width of the containing element, 6% left margin

…-fourth-indent – 91% of the width of the containing element, 9% left margin

…-fifth-indent – 88% of the width of the containing element, 12% left margin

Each of the above indents is preceded by a character or set of characters that define specific properties of that indent. These prefixes are:

n – paragraph is displayed as per user/browser defaults, and non-justified

i – paragraph is displayed in italic, otherwise as per user/browser defaults, and non-justified

j – paragraph is displayed justified, otherwise as per user/browser defaults

ji – paragraph is displayed justified, italic, otherwise as per user/browser defaults

Each of these five can be further modified by the addition of the letter ‘t’, to indent the first line of text contained within the indent by 2%, as follows:

jit

Thus, the format of an indent is “style-placement-indent”, as in, for example, "n-second-indent" (normal user/browser defaults, indented by one increment) or “jit-first-indent” (justified/italic/text indent/no paragraph indent) or “j-third-indent” (justified/indented by two increments).

No need has yet been seen to create a similar indent scenario for bold text – where bold text is required, standard HTML is used.

See below for some examples of these indents in action, and have a look at the coding of this page as well.

• <table…

Though allowed, it is anticipated that, as either my own skill in CSS improves or as other more proficient programmers begin work on the Kitáb-i-Aqdas Project, that the use of tables will be eventually eliminated. A table should be viewed as a special form of “main-container”, and will, in their turn, carry the other formatting elements (indents, spacers etc.) within the cells. Where tables are used, it will only be to allow layout of columns, and they will abide by the standard declaration found below with the templates.

Spacers.

Spacers are used to provide the vertical spacing between the containers. There are some predefined spacers for spacing content vertically on a page. These should be sufficient for every purpose. Though the <br /> element can, under certain discretionary circumstances, be used, the use of the HTML element <p> is not permitted under any circumstances - a new paragraph or the placement of a new element is achieved by the use of “indent”s, <table…'s and the following standard spacers between these “indent”s and <table…'s:

quarter-em-spacer

half-em-spacer

threequarter-em-spacer

one-em-spacer

two-em-spacer

three-em-spacer

four-em-spacer

std-paragraph-spacing

set at 25% of the current font size. This will be the most common spacer that is used within the coding to provide a consistent space between each page element.

page-bottom-space

Note: This spacer is the only one that is based upon the pixel, and is set to create a space at the bottom of the page that will allow the bottom-most line of text to appear at the top of the screen when viewed at 1200 * 768 resolution; it does not matter if it is a fraction more than this. For an example of its use, look at the bottom of the A-Z indices.

Templates

Standard document

All documents will conform to this standard template

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

<html>

<head>

</head>

Document content using the classes for headers, indents, tables (if needed), spacers for vertical placement, and so on — everything needed should already be part of standard HTML or be declared as a class within the my.css document

</div>

A small table is inserted here to carry the navigation icons and links that occur at the bottom of very page. Depending on need as to whether there will be three or four columns. Code for these will be added to this guide at a later date.

</body>

</html>

Standard tables

All tables will conform to this standard table declaration, and will be declared outside of a “main-container” except when nested within another table (see discussion below). The only variation allowed is in the …width… and the …align… element, depending on context and need, but the left and right boundaries of a table cannot extend beyond the boundaries defined by the declaration of “main-container”; this will limit tables declared as left or right aligned or as being greater than 80% width to those that are nested within another table.

It must be noted that, as some versions of Konquerer do not apply the <table… element as expected within a <div… statement, nor does it apply the width aspect as expected when used within a class in the <table… declaration, where a <table… is used, the “main-container” must have a closing </div> before the <table… is declared, and the “main-container” must then be re-declared after the closing </table> statement. This is one reasons for allowing the inclusion of the …width… and the …align… elements, but they are also there to allow flexibility when a <table… is nested inside another table without needing to declare separate classes.

A “std-cell” (<td class="std-cell">) has also been defined in my.css, with no padding and no border.

Standard rule

Where a rule is needed (as, for example, those found on this page), they will conform to this standard rule. The spacers either side may be varied at need, but as a general rule where these are used to divide sections of text, the "half-em-spacer" will be utilised.

Examples

Indent examples

Understanding the indents and their application in combination with "main-container", <td>…</td> and spacers is easy. The following examples provide a brief visual example for those who may need them, but the best way to grasp indents as declared in the stylesheet and defined above is to look at them in the style sheet, look at the coding of the Kitáb-i-Aqdas Project and of this page, and to play with them in your own coding. Remember that, under limited discretionary circumstances, an indent can be utilised within a main-container to provide a pseudo main-container (see the ‘Additions to the A-Z indices’ on the “Release notes” page for an example).

This page has been coded as per the “standard document” (above), which sets the left margin at 10% from the left edge of the window (using the “main-container”). This paragraph and the one immdiately above have then been declared as <div class="n-first-indent"> (‘n’ for ‘normal user/browser’) – text is displayed at user and browser defaults, no left indentation from the left margin of the “main-container”, no extra indentation of the first line, no text justification (ragged right).

Paragraph formatted using <div class="jt-second-indent"> – This paragraph has been indented by one indent increment, is justified, and has the first line indented by 2% through the addition of the ‘t’ (justified/text-indent/paragraph indent). Quotes that take their own paragraph are usually indented by the next indent increment from the paragraph that immediately precedes it – examples abound throughout the body of the Kitáb-i-Aqdas Project.

Paragraph formatted using <div class="jit-second-indent"> – This paragraph has been indented by one indent increment, is justified, uses italic text and has the first line indented by 2% through the addition of the ‘t’ (justified/italic/text-indent/paragraph indent).