<!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>
<pre>
$Header: /repository/documentation/docstd.htm,v 1.2 2006/04/29 00:24:44 joerg Exp $
</pre>
<P> remark: see the source of this HTML document and you have an example of the
rules </P>
<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 overhead compared to plain text is
neglectable. </P>
<P> 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>.
<H3> we only use HTLM 2.0 </H3>
<P> 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. </P>
<P> so the first line of every document is </P>
<P><CODE>
<!DOCTYPE html PUBLIC "-//IETF//DTD HTML 2.0//EN">
</CODE></P>
<H3> lower & upper case </H3>
<P> 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. </P>
<P> for example in HTML we use upper case for all tags </P>
<H3> keep it simple </H3>
<P> 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.
<H2> HTML formating </H2>
<H3> the general structure </H3>
<PRE> <CODE><!-- ------------- cut here ------------------------ -->
<!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>
</CODE> </PRE> <!-- ------------ cut here ----------------------- -->
<H3> intendation </H3>
<P> we use intendation of three (3) chars. </P>
<P> there are three styles of indenting: </P>
<H4> start and end in one line </H4>
<P> you can place start and end tag in one line. in this case you
don't need any indentation. like in: </P>
<PRE> <CODE> <H2> general rules </H2> </CODE> </PRE>
<H4> text follows start text, end text in later line </H4>
<P> in this case the end tag is at the end of the last text line. the
second line and any following is intended. </P>
<PRE> <CODE> <!-- -------------- cut here --------------------- -->
<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>
</CODE> </PRE> <!-- ------------ cut here --------------------- -->
<H4> start and end in seperated lines </H4>
<P> the start and end are in two lines in the same colmns. all lines
inbetween are indented. </P>
<PRE> <CODE> <!-- --------------- cut here --------------------- -->
<HEAD>
<TITLE>silicon brains documentation standard</TITLE>
</HEAD>
</CODE> </PRE> <!-- ------------ cut here --------------------- -->
<H2> used tags </H2>
<H3> DOCTYPE </H3>
<P> first tag and line in the document is </P>
<P> <CODE> <!DOCTYPE html PUBLIC "-//IETF//DTD HTML 2.0//EN">
</CODE> </P>
<H3> HTML </H3>
<P> next is the <CODE> <HTML> </CODE> which contains the whole
rest of the document.
<H3> HEAD </H3>
<P> inside the html-tag the first is the <CODE> <HEAD> </CODE>
, which contains only the <TITLE> tag. </P>
<H3> TITLE </H3>
<P> inside the <TITLE> tag the text should not be longer than 64
chars, so that in a lynx someone can see the complete title. <P/>
<H3> BODY </H3>
<P> 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.
<H3> P </H3>
<P> 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.
<H3> BR </H3>
<P> use the <BR> for a fixed new line. </P>
<H3> BLOCKQUOTE </H3>
<P> use the <BLOCKQOUTE> if you quote something from another source. </P>
<H3> HR </H3>
<P> you can use a <HR> (without any attributes), but be aware, that lynx doesn't
display it. so it should no be too importand.
<H3> A </H3>
<P> use the <A HREF="http://..."> text </A> for hyperlinks. </P>
<P> use the <A NAME="name"</A> for anchors. </P>
<H3> UL, OL and LI </H3>
<P> 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.
<H3> DL, DT and DD </H3>
<P> use these for definition lists. allways use the ending tags for <DT> and
<DD> even if they are optional.
<H3> extended chars </H3>
<P> the only extended char allowed are &, > and <. they are written not by
numeric code but by named character code.
<H3> EM, STRONG, ADDRESS, CITE, CODE, KBD, SAMP and VAR </H3>
<P> 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>
<H3> PRE </H3>
<P> use the <PRE> tag e.g. to display a larger pice of program code. </P>
<H2> that's all </H2>
<P> 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. </P>
<H2> page layout </H2>
<P> you can see the page layout on this page. here a short
description:</P>
<UL>
<LI> a title. </LI>
<LI> a header 1 with the same text as in the title. </LI>
<LI> headers 2 and more. </LI>
<LI> text taged like described here. </LI>
<LI> a horzontal line <HR>. </LI>
<LI> a link to the index.htm </LI>
<LI> a link to a mail contact. </LI>
<LI> the address of the originator. </LI>
<LI> copyright notice. the complete documentation is gpl'ed. </LI>
</UL>
<HR>
<P> <A HREF="index.htm">the silicon brain home page</A> </P>
<P> <A HREF="mailto:info@siliconbrain.com">contact
SiliconBrain</A></P>
<ADDRESS>
<A HREF="mailto:info@siliconbrain.com">info@siliconbrain.com</A>
</ADDRESS>
<P> this web page was designed by joerg kunze.</P>
<P> copyright; 1998, 2006 joerg kunze </P>
<P> 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.</P>
<P> this web page is distributed in the hope that it is useful, but
<STRONG>without any warranty</STRONG>; without even the implied warranty of
<STRONG>merchantability</STRONG> or <STRONG>fitness for a particular
purpose</STRONG>. see the GNU General Public License for details.</P>
<P> you should have received a <A HREF="gpl.html">copy of the GNU
General Public License</A>
along with these web page; if not, write to the
<A HREF="http://www.fsf.org/">Free Software Foundation</A>, Inc.,
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.</P>
<hr>
<pre>
$Log: docstd.htm,v $
Revision 1.2 2006/04/29 00:24:44 joerg
add Header and Log cvs keywords
</pre>
</BODY>
</HTML>