README

   1 Here are some guidelines for updating samba.org:
   2
   3 XHTML
   4
   5 The new design for samba.org uses xhtml 1.0 Transitional.
   6 xhtml is different from html<=4.0 in several ways.  The
   7 difference is minimal in terms of syntax, but major in
   8 terms of its implications on the page.  A rundown of each:
   9
  10 ***Case Sensitive***
  11
  12 xhtml is case sensitive, and all tags are lowercase.
  13 <ul> != <UL>  Therefore, mixing case is bad, too.
  14 You can't do <a HREF="...">.
  15
  16 ***Closed Tags***
  17
  18 xhtml requires all tags be closed.  Most notably, this
  19 affects the former <br>, <hr>, and <img> tags; these should
  20 now be written as <br />, <hr />, and
  21 <img src="..." alt="..." />.  The img tag is the one that
  22 catches people most often, especially in the following syntax:
  23 <a href="..."><img src="..." alt="..." /></a>.  Even though
  24 the anchor tags are closed, the image tag must still be closed.
  25
  26 ***Proper Nesting***
  27
  28 Tags must close in the proper nesting order.  An example:
  29 <tag1><tag2></tag2></tag1>.  This is a simple example, but
  30 in nesting lists it can get confusing.  Also, within forms
  31 using other tags can get sticky.  I'm still learning some
  32 of the nuances of this myself, so be careful with this
  33 one.  Use an online validator to check if you're not sure.
  34
  35 ***Why You Should Care***
  36
  37 html is *very* forgiving.  xhtml is not.  If you miss one of
  38 the above in your web page, there's no telling what it will
  39 look like in different browsers.  In fact, most of the wild
  40 page display problems during the move to the new design were
  41 due to xhtml validation problems.  And there's no telling how
  42 a browser may handle an error.  We still have several html
  43 hold-overs, but none of them are critical, at least in terms of
  44 page display.
  45
  46
  47 ADDING NEW PAGES
  48
  49 If you have to add a completely new page to a directory,
  50 templates have been provided in each directory.  Adding
  51 a page should simply be a matter of opening the template
  52 and adding in the info you want.  Make sure you follow
  53 the xhtml rules above and be sure to add a title between
  54 the title tags.  The two-header system was built to allow
  55 for page specific titles.  This is a help in browser bookmarks
  56 and search engine indexing.
  57
  58
  59 PAGE FORMAT
  60
  61 Page formatting is handled by css.  This is another important
  62 consideration in xhtml sites versus html sites.  This means that
  63 you should not use a bunch of attribute tags to style a page.
  64 For example, <table border="3" width="30" height="100"> is
  65 not used in xhtml/css sites.  The stylesheet rules control
  66 the look of each element.  If you use just normal <h3> tags for
  67 headings and <p> tags for paragraphs, styles are already in place.
  68
  69 Also, see </samba/styles/common.css> for a number of built in
  70 styles.  Simply declare a style as an attribute of a tag to use
  71 a particular style.  So if you want to use the headline style,
  72 write <p class="headline">YOUR_INFO_HERE</p>.  Stylesheets
  73 distinguish classes with a "." and ids with a "#".  Using the logo
  74 style would require <p id="logo">CONTENT_HERE</p>.
  75
  76
  77 ADDING STYLES
  78
  79 If you need styles added or have special formatting requirements,
  80 please email me (deryck[at]samba[dot]org).  Questions and comments
  81 are also welcome.