$Header: /usr/home/web681a3/repository/documentation/docstd.htm,v 1.2 2006/04/29 00:24:44 joerg Exp $
remark: see the source of this HTML document and you have an example of the rules
HTML is an easy to use formating system, which is able to be read by many programs (browsers), which is very often used in the internet. if you don't use pics its overhead compared to plain text is neglectable.
we use HTML as a logical markup language. so we don't express how a page should look like (herefor we would use tex or the page description language post script). for an example we rather use <EM> and <STRONG> instead of <I> and <B>.
so everyone with a web browser and a connection to the WWW will be able to read this documentation. the results are the same on any browser and it will be readable in lynx.
so the first line of every document is
<!DOCTYPE html PUBLIC "-//IETF//DTD HTML 2.0//EN">
in english language we use only lower case, upper case for acronyms. upper case has no information. in programing languages we use upper case for specific meanings.
for example in HTML we use upper case for all tags
the idea is to have as less formating as possible, so that the reader is not confused by many styles without information. and to have an almost unique lookout of all the documentation pages.
<!DOCTYPE html PUBLIC "-//IETF//DTD HTML 2.0//EN">
<HTML>
<HEAD>
<TITLE>silicon brains documentation standard</TITLE>
</HEAD>
<BODY>
<H1> the silicon brain documentation standard </H1>
<H2> general rules </H2>
<H3> we use english </H3>
<H3> we only use HTML </H3>
<P> HTML is an easy to use formating system, which is able to be
read by
many programs (browsers), which is very often used in the
internet.
if you don't use pics its overhaed compared to plain text is
neglectable. </P>
</BODY>
</HTML>
we use intendation of three (3) chars.
there are three styles of indenting:
you can place start and end tag in one line. in this case you don't need any indentation. like in:
<H2> general rules </H2>
in this case the end tag is at the end of the last text line. the second line and any following is intended.
<P> HTML is an easy to use formating system, which is able
to be read by
many programs (browsers), which is very often used in the
internet. if you don't use pics its overhaed compared to plain text is
neglectable. </P>
the start and end are in two lines in the same colmns. all lines inbetween are indented.
<HEAD>
<TITLE>silicon brains documentation standard</TITLE>
</HEAD>
first tag and line in the document is
<!DOCTYPE html PUBLIC "-//IETF//DTD HTML 2.0//EN">
next is the <HTML> which contains the whole
rest of the document.
inside the html-tag the first is the <HEAD>
, which contains only the <TITLE> tag.
inside the <TITLE> tag the text should not be longer than 64 chars, so that in a lynx someone can see the complete title.
next after the </HEAD> is the <BODY>. this body tag contains no other attributes. this guarantees, that all text and the background apears as choosen by the user. a background pic is not viewable in text based browsers and is bad for people with slow connections to the internet.
each paragraph is started with a <P> and ended with a </P>. the <P> definitly is a container element, even when many browsers don't need it. the <P> has no attributes.
use the <BR> for a fixed new line.
use the <BLOCKQOUTE> if you quote something from another source.
you can use a <HR> (without any attributes), but be aware, that lynx doesn't display it. so it should no be too importand.
use the <A HREF="http://..."> text </A> for hyperlinks.
use the <A NAME="name"</A> for anchors.
use <UL> or <OL> and <LI> for creating lists. do not use the <BR> for that aim. it is allowed to nest the UL's. <UL> has no aCODEributes.
use these for definition lists. allways use the ending tags for <DT> and <DD> even if they are optional.
the only extended char allowed are &, > and <. they are written not by numeric code but by named character code.
these are the HTML 2.0 logical markup tags. all are used as container tags. we don't use the physical tags like <TT>, <I> or <B>
use the <PRE> tag e.g. to display a larger pice of program code.
do not use any tags not described here. the idea is not to confuse the reader with many styles and kinds of formatting. another idea is to keep a homogenous layout thru all the documentation.
you can see the page layout on this page. here a short description:
this web page was designed by joerg kunze.
copyright; 1998, 2006 joerg kunze
this web page is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the license or (at your opinion) any later version.
this web page is distributed in the hope that it is useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. see the GNU General Public License for details.
you should have received a copy of the GNU General Public License along with these web page; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
$Log: docstd.htm,v $
Revision 1.2 2006/04/29 00:24:44 joerg
add Header and Log cvs keywords