Multics
04 Nov 2008

Web Site Design

 

Home | Changes | Multicians | General | History | Features | Bibliography | Sites | Chronology
Stories | Glossary | Papers | Humor | Documents | Source | Links | Site Map | About

Tom Van Vleck

Here is a guide for maintainers of the Multicians web pages.

• Tone
  • This site is about content. The goal is to present the story of Multics for people interested in the system's history, especially Multicians. Humor is OK but excess is not.
  • Aim for an informal, yet accurate tone.
  • Clearly mark individual opinion and distinguish from verified fact. Prefer first-hand accounts of individual experience.
  • Present consistent look and feel.
  • Appearance should be polished but not glitzy.
    • No gratuitous animation, sound, background, etc.
• Audience
  • Multicians
  • Students of operating systems
  • Historians
  • General public
• Content
  • Keep high standards: correct spelling, reformat, fix up GIFs.
  • Credit every source.
  • Ensure that intra-site navigation works and is consistent.
  • Ask permission before publishing others' writings.
  • Inform foreign page owners if linking to them. Check occasionally for dead links.
  • Ask permission before adding a person's mail address to multicians.html.
  • Try to avoid judging the value of others' contributions.
    • If they say they're a Multician, and made some contribution, list them.
  • Pictures
    • Pictures interest people. Use plenty.
    • Small as possible. Put bigger version "behind" for more detail.
    • GIFs or JPGs. Some browsers cannot handle PNG or SVG.
    • High contrast and brightness (pictures get darker on web, PC gamma differs from Mac).
    • Remember that not all systems have same DPI or #colors.
    • Use JPGs for photos. Don't worry about palette conflicts.
    • See my  article on how to use Photoshop.
  • Original documents. This site is a repository for documents not available elsewhere.
    • Scan and convert these to HTML so they are fully searchable. (Image-only PDFs are a bad idea.)
    • Do not attempt to preserve visual fidelity with originals, e.g. two column layout. Concentrate on readability and availability for other use.
    • Redraw figures if necessary.
    • Attempt to secure copyright clearance and permission of author.
  • Ensure that dates are included in many items, so that the reader understands when each part of the story happened.
• Implementation
  • Generate HTML files statically offline.
    • More efficient on server.
    • Stratus mirror site is FTP only.
    • Factor common elements into include files for maintenance ease and consistency.
    • Generate pages from database if this simplifies processing.
  • Write legal standard HTML that works OK in popular browsers.
    • Only one H1 per document.
    • Use Hx controls to represent outline structure, not for text format.
    • Run  W3 Validator on every file we control; should validate as "4.01 Transitional". Fix all reported problems.
    • Use macro tools to generate as much HTML as possible, in order to avoid errors.
    • Use "almost pure CSS menus" for drop down menus. Thanks to  Jason Koivisto
    • Automatically generate a "plain" Lynx-friendly head page with menus at the bottom (to overcome MSIE problems).
    • Plan for the introduction of MSIE 7 in 2006.
      • Convert all pages to run in standard mode with loose DTD, ie add URL to the DOCTYPE.
      • Put a comment above the DOCTYPE so MSIE 6 still runs in quirks mode.
      • Use !important to fix MSIE 5/6 quirks.
    • Do not use HTML produced by MSWord "Save as HTML." It's full of constructs that only work right on MSIE.
  • Be usable by text-only browsers and non-image-loaders.
    • Graphic images should have ALT=
    • Use tables for tabular data, not for presentation.
    • Put formatting and layout in CSS.
    • Do accessibility checks and try to deal with issues raised.
  • Avoid proprietary formats.
    • Convert Word, etc to HTML.
    • Convert PowerPoint, etc to PDF.
    • (Exception: binary tools for reading Multics tapes.)
  • Look good in most browsers.
    • Don't use features that make the page unintelligible in many browsers, e.g. ActiveX.
  • Look as good as possible in Netscape/Mozilla and IE.
    • On average, 45% of hits are from Netscape/Mozilla, 44% from MSIE, 2% Safari.
  • Display as fast as possible.
    • Every IMG should have HEIGHT and WIDTH.
    • Small graphic images.
    • No backgrounds.
    • GIFs larger than icon size should be interlaced.
    • Break files >50K into smaller ones, if this can be done without inconvenience to the reader. (Multicians list, bibliography, source index are all kept integral because having things in one place is more useful than having a file that loads quickly. The glossary, on the other hand, is broken into a file per letter.).
  • Don't require plugins or client side execution.
    • No shockwave, PNG, SVG, etc (requires plugin on most browsers).
    • No ActiveX (won't work with non-Microsoft browsers).
    • No Java (user may disable, Microsoft version may work differently from standard. Reconsider if a really good use is proposed).
    • JavaScript is allowed if the page is still usable when it is turned off (user may disable). Use caution since different browsers implement differently. (Exceptions: main menu dropdowns for MSIE, validation of mail form submission (uses noscript), AJAX in mail form and signup form.)
    • No rollovers (JavaScript, bandwidth, gratuitous). Use of hover (menus, links) is OK.
  • Stratus mirror is FTP only.
    • Can't use server imagemaps, servlets, or PHP.
    • Can point to CGI scripts on servers that do support it; for example, main page's search function points to a CGI at www.multicians.org. This CGI has code to point the user back to the referring site so searches don't "hijack" the user from the site he was searching. Similarly, the mail sending facility points to CGIs at www.multicians.org.
  • Links should not be surprising.
    • Use descriptive link text.
    • Links offsite should be preceded by the globe icon. (Use macros.)
    • Links to website files should be marked with date modified, size, # pictures.
    • Links to website files should have TITLE attribute generated by expander, that provide a tooltip identifying the target.
    • Exceptions to above: links to multicians.html or glossary entries (what about a tiny icon for these?); links from navigation menus.
  • Help user find what's new or interesting.
    • Date modified in heading at the top of every page.
    • Flag new items with new flag, updated ones with updated. (Done with styled text to save an image load.)
    • Put date modified after local links so user can find the new stuff.
    • Maintain the change log and RSS feed describing content changes.
  • Cross-link pages.
    • Links should add to the reading and understanding experience.
    • In general, don't link to the same target more than once from the same area on a page. For instance, the Changes page links to each modified page once, not once for each change. But the Changes page also has a standard navigation panel that links to all pages.
    • Link terms to the Glossary.
    • Link names to the Multicians list.
    • Link to other pages as possible.
  • Many pages will be found by search engines.
    • Make sure every page is self-explanatory, so a user knows what it is part of and what it's about. Users will enter the site at many places besides the front page, and need context.
    • Include a META KEYWORDS and META DESCRIPTION on every page, to ensure that the search engines point to the pages they should and give the user an idea of what is on the page.
    • Ensure that navigation is rich: from every page, one should be able to find the pages a reader might want to go to next, especially the main page.
  • Cascading Style Sheets (CSS)
    • Use HTML for structure, style sheet for layout. For example, don't use extra P or BR tags for layout, place the item in a container with a CLASS attribute and control the class's layout. (This page is an example. The spacing after top-level LI tags is done via a CLASS attribute and a CSS definition.)
    • Tag items with semantic attributes, e.g. pathname, webpage, toplevel, rather than presentation attributes like bold or tiny.
    • All pages should use the standard mxstyle.css. Styles that pertain to a single page can be in a STYLE block on the page.
    • Vast majority of the hits on the site are from CSS capable browsers. Make sure every page is intelligible with and without CSS.
    • Don't use FONT FACE attribute (deprecated), rather STYLE section and SPAN attribute.
    • Many CSS features don't work in all browsers. Stick to those that work in both Netscape/Mozilla and Microsoft.
    • CSS hacks may be needed to enable good presentation. Restrict these, keep then in a few include files only, check them when new browsers are released.
      • Currently the site uses the !IMPORTANT attribute, ignored by MSIE, to mark values for Firefox and Opera, followed by the MSIE value. This construction works for MSIE 5-7 in Quirks mode.
      • The major problem with MSIE layout is its incorrect calculation of box width and height; MSIE includes the border and padding of items in the value, so the MSIE size should be bigger for padded items.
      • MSIE also does not support MAX-WIDTH, used to control page width.
    • Check printing a CSS page as well as displaying it. Some browsers display OK but mess up on printing. A PRINT style is set in the CSS that suppresses the printing of navigation elements.
  • No Frames.
    • Frames are nonstandard.
    • Navigation on frames pages is confusing or buggy in some browsers.
    • Framed pages need extra care to make sure there's no route that shows them unframed.
  • No animation (exception for interesting technical use).
  • No blinking text.
  • Classes of pages:
    • Class 1: head page. Black box at top with logo, drop down menu nav just below. The head page serves as the site map and main index to pages. Since many users never scroll down, the drop down menus make most content accessible without scrolling, in order to draw users deeper into the site. (This seems to work based on navigation patterns in the log.)
    • Class 2: black box at top with logo, navigation links to head page and all tier 2 pages just below. (Text links for navigation are used throughout the rest of the site to speed download time.) For pages with a list of things, put total count in col 3 of the standard header, below the date. These pages are formatted via the wrapper macros described below.
    • Class 3: paper, story, etc, formatted by editor. Simple H1, navigation links to head page and all tier 2 pages at bottom.
    • Class 4: formatting supplied by some other author. Add navigation links to head page and all tier 2 pages at bottom, optional mxstyle.css
  • Spelling and orthography decisions:
    • Unix, not UNIX (except in direct quotes and titles of books, etc). Source: Dennis Ritchie.
    • Database vs data base: both occur, should decide.
    • Timesharing vs time-sharing: both occur, should decide.
    • Online vs on-line: both occur, should decide.
    • Mail vs e-mail vs email: all occur, should decide.
• Each page's organization
  • Each page has a TITLE and H1 (generated by macros).
  • Each page has ADDRESS containing a link to editor (generated by macros).
  • Record content changes in loadc.sql with date (generated from loadc.sql).
  • Title of page and H1 should be self explanatory.
  • All pages have white background, black text from style sheet.
  • Almost all pages have all content inside a DIV with MAX-WIDTH set by an include file, to maintain readability on wide monitors. The content is also centered on the screen. A CSS hack ensures that a fixed width is provided for MSIE, which does not recognize MAX-WIDTH. Since tables are not used for width control, the pages print correctly and display OK in small windows. (Check that this still works as new browsers are announced.)
    • Exception: very long and wide pages, such as the Multicians list.
  • Navigation
    • Link to head page and all tier 2 pages always provided.
    • glossary: alphabetical index, list of topics, forward link.
  • Pages with a single author list it at top.
  • Date modified at bottom for story pages.
• Where stuff goes
  • Sites (sites.html) (tier 2 page, generated from loadsites.sql)
    • link to glossary if any info, link to site bio if exists.
    • site biographies: long stories, link to external site.
    • glossary: link to external site, link to site bio if exists.
    • site-timeline.html: generated by perl program from site-timeline.txt.
  • Chronology (chrono.html) (tier 2 page)
    • every date known. Non-Multics events in italics.
    • site biographies: every date for this site.
    • site-timeline.html: every date for every site, plus a few major events.
  • Multicians (multicians.html) (tier 2 page, generated from loadm.sql)
    • don't xref terms to glossary, makes it too big.
    • don't xref sites, makes it too big.
  • Glossary (tier 2 page, generated from g1.sql)
    • xref people to multicians.html.
    • xref terms to glossary.
    • xref sites to glossary.
    • terms not beginning with a letter go in mga.html.
    • long articles go elsewhere, link to them from glossary, e.g. descriptions of features go in features.html, glossary should have short summary and a link.
  • General (general.html) (tier 2 page)
    • xref people to multicians.html.
    • xref terms to glossary.
    • xref sites to glossary.
  • Features (features.html) (tier 2 page)
    • xref people to multicians.html.
    • xref terms to glossary.
    • xref sites to glossary.
  • History (history.html) (tier 2 page)
    • xref people to multicians.html.
    • xref terms to glossary.
    • xref sites to glossary.
  • Bibliography (biblio.html) (tier 2 page, generated from loadbib.sql)
    • don't xref people, terms, sites (too big).
    • If a referenced paper is online, link to it (globe for external links).
  • Changes (changes.html) (tier 2 page, generated from loadc.sql)
    • Link to file that changed generated by template.
    • List counts for multicians, bibliography, glossary, sites.
    • Current year only; prior years go into changes-old.html
  • Stories (multics-stories.html) (tier 2 page, generated from multics-stories.htmy)
    • Three macros: stories-contrib.htmi, stories-story.htmi, stories-endcontrib.htmi. These generate a section for each author, with a DL having entries that link to and describe each story. TOC for the stories is automatically generated, and count of stories, etc in main page is also maintained automatically. Also generates drop down menus for the main page.
    • Links to each story give size, date, #pictures.
    • Individual stories each get a class 2, 3 or 4 file. Classes 2 and 3 xref people, terms, sites.
  • Development documents (devdoc.html) (tier 2 page)
    • Section for each document type, with DL linking to and describing docs.
    • links to each doc give size, date, #pictures.
    • individual docs xref people, terms, sites.
  • Papers (papers.html) (tier 2 page)
    • Chronological order, with DL linking to and describing paper.
    • links to each paper give size, date, #pictures.
    • individual papers xref people, terms, sites.
    • If a referenced paper is online, link to it (globe for external links).
  • Humor (multics-humor.html) (tier 2 page)
    • Section for each joke.
    • individual jokes xref people, terms, sites.
    • long jokes or anecdotes get their own story file.
  • Links (mult-links.html) (tier 2 page)
    • Sections for different classes of offsite links.
    • Use loadext.sql to create external links.
    • Offsite links may also be placed in other documents; use judgment whether to duplicate on the links page.
    • Do not duplicate homepage links for Multicians on the links page.
  • Site Map (sitemap.html) (tier 3 page, generated from loadpages.sql)
    • One entry for each page on the site.
• Site Maintenance
  • When an image is added to any page, remember to add it to mulctl.txt and generate a thumbnail for it in thumbnails dir using hthumb or vthumb. The imgtag macro generates references to images.
  • Generate external links using {!tag text!} which looks in external links table and inserts globe icon.
  • Generate multicians links using {[tag text]} which looks in multicians table and inserts TITLE tag.
  • Generate glossary links using {{tag text}} which looks in glossary table and inserts TITLE tag.
  • Generate internal links using {@tag text@} which looks in pages table and inserts TITLE tag.
  • Use {:text:} for "cmd", {=text=} for "pathname", {+text+} for "code", {*text*} for "source file".
  • To update main page:
    • Edit multicians.htmy in the source directory.
    • make install
    • For cases when you don't need to re-index the site and want a quick install (e.g. you are connected on dialup) do make q instead.
    Main page is automatically updated if many other pages change. See Makefile.
  • To add or update a Multician:
    • CGI form submission sends mail with database input.
    • User may also send a manual mail message.
    • Verify info and add or update row in loadm.sql in the source directory.
    • make install
  • To add or update an offsite link:
    • Links go in loadext.sql, loadbib.sql, or loadm.sql.
    • Edit loadext.sql to add or modify a row in the external links table and reload it.
    • Add a reference to the place where the link goes. Globe icon, etc will be generated by expandfile.
    • make install
    • Check every few months for dead links using checkext.
  • To add or update site information:
    • Verify info and add row or update in loadsites.sql in the source directory.
    • If new dates are added, fix site timeline datafile site-timeline.txt by hand.
    • make install
  • To add or update bibliography:
    • Verify info and add or update row in table "biblio" loadbib.sql in the source directory.
    • Verify info and add or update rows in "authors" and "aka" tables.
    • make install
  • To add or update glossary entries:
    • Edit or add paragraphs to g1.sql in the source directory. Use special tags to generate links to glossary entries and Multicians list entries, and to mark commands, pathnames, and code. One oddity: to insert a backslash in the output, you have to put EIGHT backslashes in the database file, cause it gets expanded three times.
    • make install
  • To add a new story:
    • Add the HTML body to a new file storyname.htmx in the source directory. Use the wrapper macros.
    • Edit multics-stories.htmy in the source directory. Add a new stories-story macro for each story, and a stories-contrib / stories-endcontrib pair for each new contributor. Newer files go near the top.
    • Do the other "new page" operations below.
    • make and then use W3 validator to check the new file.
    • make install
  • To add or update other class 2 and class 3 pages:
    • Edit or add filename.htmx in the source directory. Don't edit the HTML files directly.
    • Use wrapper macros: set title, description, keywords, and headingdate, then define a block called body (and optional blocks extrastyle and extratail), and then include pagewrapper.htmi. This will take care of all standard heading and tail matter.
    • Use the imgtag macro for references to images. Update mulctl.txt and make thumbnail for new images.
    • When a new page is added,
      • touch the .html page in the object directory to cause make to start creating it.
      • touch makemxtarextrafiles.
      • add a row to loadpages.sql to put it into the site map.
    • Decide if the page should be listed on the home page, or in the menus, and update if so.
    • make and then use W3 validator to check the new file.
    • make install
  • To add or update class 4 pages (formatted by others): either convert the file to a class 3 page, or
    • Place the file directly in the object directory. Edit it to insert naviagtion to the rest of the site at the bottom.
    • Add its name to loadpages.sql and makemxtarextrafiles in the source directory. Optionally add mxstyle.css for uniform heading sytles if this doesn't mess it up.
    • Change mail addresses to links to the Multicians page.
    • make install
  • Run W3 Validator on each new class 1-3 file.
  • Run htmlchek or weblint after any significant changes.
  • Update loadc.sql and make install to describe what's new.
  • On hosting site, tar up using make_mx_tar and send to Stratus mirror using shell script tarsend every month or so.
  • Yearly maintenance:
    • Before the first change to the site in a new year, add a new section for the previous year to changes-old.htmx containing the DT and DD bodies from generated file changes.html.
    • Update the navigation table at the top of changes-old.htmx with counts of changes by year. You can get this by select cyear,count(cyear) from changes where cf='Y' group by cyear;.
    • Check and update title and navigation links if necessary.
    • First change in the new year will cause changes.html to list only that year's changes.
• alt.os.multics FAQ Maintenance
  • Post the FAQ to alt.os.multics on (or after) the first of each month.
    • Short FAQ 8 times a year, one file.
    • Long FAQ quarterly, posts 9 files.
  • To post the long FAQ, run make auto1, which runs Perl programs to generate the FAQ files from the HTML files.
    • Generates 3 multicians FAQ files from multicians.html
    • General
    • Features
    • History
    • Bibliography
    • Sites
    • Chronology
    • Posts to alt.os.multics using perl program post.pl.
  • To post the short FAQ, run make auto2
• multicians.org mail reflector maintenance
  • A procmail script in home directory of the account hosting multicians.org redirects selected mail messages.
  • The redirector script is automatically generated by expandfile with procmail.tpt from the multicians table by the Makefile when loadm.sql is updated.
  • If a new multicians.org address is added, add it to the list of valid entries in the ISP's mail recipe control panel.
  • See multicians-org.html for details.
• multicians.org
  • This site is provided by the editor, who pays the domain registration fees and web hosting fees as a contribution to the online community.
  • We are limited in both storage space and bandwidth as a result. The editor will take whatever steps are necessary to avoid exceeding the (fairly high) limits imposed by the ISP, since this could cost the editor a lot more money than he can spare.
  • The ISP (Pair networks) has a fairly reasonable policy on "slashdotting" but more than one in a month could be a problem.
  • We are also bound by the AUP of the ISP. So far this has not been a problem.
  • The advantages of hosting at the current ISP are very high bandwidth and redundant connectivity, very good server response and uptime, reasonable prices, outstanding policies and facilities, and 24 hour technical support. The ISP has been in business since 1996 and says it does not plan to change management, merge, or be sold.
  • The ISP supports virtual domain hosting, CGI and CGIWRAP usage, custom mail forwarding with procmail, server log extracts, SQL database access, cron, SSH and SCP for updating, shadowed backup, FTP, and other features that not all ISPs provide.
• Wish list, future tasks
  • Redo head page search function to use Swish so that PDFs can be indexed.
  • Pages to write
    • hardware page
    • architecture page
    • B2
    • Comparison between Multics and Unix
    • Security stories
  • Create images table with ownership etc, generate mulctl.txt.
  • Generate site timeline from sites table.
  • Generate multics-stories.htmy from pages table.
  • Write a management form page, backed with CGI, to do maintenance tasks:
    • Add/update user in m (checking mail addr and url)
    • Add document to biblio, linking authors to m via aka (operate on db table and then dump it to ASCII with mysqldump)
    • Add new page, updating pages (run HTML tidy, then transform to create .htmx source using page wrapper)
    • Add new story, updating multics-stories.htmy and pages
    • Add new glossary entry (scan the entry for possible crosslinks)
    • Add/update offsite link (checking that it's there)
    • Add image (add to mulctl.txt and make thumbnail)
    • Check external URLs and mail addresses for validity.
    • Check for extra and missing files.
    • Run W3 validator on all HTML.
    (This begins to look complicated, reinventing content management.)
  • Put source of the website under subversion
• Tools needed to maintain Multics site provided by others:
  • Perl
  • Remote copy command rsync
  • Remote access commands ssh or PuTTY
  • Unix commands make, touch, chmod, diff, cp, cat, ls, echo, mv, sh, grep, sed
  • SQL (MySQL), including command line interface and Perl DBI (currently no version 4 features are used)
  • HTML-aware text editor, such as emacs or TextWrangler
  • Photoshop or Gimp
  • Optional: ImageMagick tool convert
  • Optional: HTML Tidy, Firefox Web Developer plugin
• Tools needed to maintain Multics site provided by editor:
  • Site macros and templates
  • SQL schemas
  • Configuration file config.txt
  • expandfile, thvve.pm, thvvutil.pm
  • printgloss3.pl, printsites2.pl, gen_site_timeline.pl, gallery4.pl, printmulticians2.pl, countauth.pl
  • filemodshort, dbcounts, filesizek, nargs, filedaysold, filedmodiso, checknonempty
  • html2faq, genmultfaq, auto1, auto2, auto1a.sh, post.pl
  • search-index.pl generates index, stopwords.txt
• Programs and data files in cgi-bin directory provided by editor:
  • Configuration file mxconfig.txt
  • mxmail.cgi, mxmailform.cgi, ckem.cgi
  • mxregister.cgi, mxregister4.cgi
  • template files for mxmail and mxregister
  • special.pmrc for spam checking
  • GeoIPCountryWhois.csv for error messages
  • helpsearch2.cgi searches index, searchtpt2.htmt