SLAC ESD Software Engineering Group
Stanford Linear Accelerator Center

Web Support Design

SLAC Detailed
SLAC Computing
Software Home
Software Detailed
Documentation and Web Support Home

This is a design document for ESD Software’s Web documentation.

Contents: IntroductionProblems and Solutions (File Organization, Easy Publication, Network Independence, Other Problems)

    1         Introduction

    Although documentation is a necessary part of development, contributing to our present knowledge base can be a daunting task.  First of all, there is the question of a document’s existence and if so where to find it. Currently, the ESD Software Web pages are not sufficiently organized so that publication and retrieval is well understood.  Second, although most document writers work on Windows-based platforms, the documentation itself is in AFS space.  There is a lack of user-friendly cross-platform publishing tools.

    Another problem with the current location(s) of our documentation is its dependency on AFS and SCS.  In the event of a network disconnect, documentation required to operate the accelerator must be available to Operations.

    2         Problems and Solutions

    The requirements that will solve the problem of publication retrieval, uncomplicated addition to the current knowledge base and network independence are determined. 

    2.1       File Organization

    As projects and operating platforms have multiplied, project owners have developed their own methods of organization.  The number of variables that require consideration further complicates the matter.  Is this a SLAC-only document?  Is this a general document or does it apply to a specific project?

    A general file organization hierarchy and structure must be established.

    Specific Design Problems and Solutions

    1.        Problem:         There is no general scheme for correlating documentation subject to documentation directories.

    Solution:         1. On AFS Web Server, create directories and index pages in these directories for keeping user guides, requirements, and design documents:

    ·         $CD_SOFT/html/ug (

    o        $CD_SOFT/html/ug/slaconly (symlink to slaconly/ug)

    ·         $CD_SOFT/html/pg (

    o        $CD_SOFT/html/pg/slaconly (symlink to slaconly/pg)

    ·         $CD_SOFT/html/req (

    o        $CD_SOFT/html/req/slaconly (symlink to slaconly/req)

    ·         $CD_SOFT/html/design (

    o        $CD_SOFT/html/design/slaconly (symlink to slaconly/design)

    ·         $CD_SOFT/html/slaconly (

    o        $CD_SOFT/html/slaconly/ug

    o        $CD_SOFT/html/slaconly/pg

    o        $CD_SOFT/html/slaconly/req

    o        $CD_SOFT/html/slaconly/design

    These directories will be the default locations of such documents on Unix, if there is no other project subdirectory in which they should be located, or before that project subdirectory exists.

    2. On our local Windows IIS server, WEBMCC, symmetrically create directories and index pages in these directories for keeping user guides, requirements, and design documents.  Because WEBMCC is a SLAC-only server, the slaconly directory is not necessary:

    ·         \\webmcc\wwwroot\grp\ug (

    ·         \\webmcc\wwwroot\grp\pg (

    ·         \\webmcc\wwwroot\grp\req ( /grp/req)

    ·         \\webmcc\wwwroot\grp\design ( /grp/design)


    2.        Problem:         Web page hierarchy does not reflect folder hierarchy.

    Solution:         Create an index.html page in each subdirectory of /afs/slac/g/cd/soft/html, and link that to the home page afs/slac/g/cd/soft/html either directly, or indirectly through intermediate index pages. There doesn't have to be a precise 1:1 correspondence in the directory structure to page hierarchy, but it should be close.

    Organization will be both project and type specific.  When project specific html directories do exist, soft links should be created from these directories to those corresponding subdirectories of each project, so for instance $CD_SOFT/html/req/cmlog is a soft link which points to the directory $CD_SOFT/html/cmlog/req/.

    Unix Web Home: afs/slac/www/grp/cd/soft/





















    similar folders for /req, /design, /slaconly                  similar folder for each project

    3.        Problem:         Web pages are not standardized.

    Solution:         Go though all pages now in the subdirectories of afs/slac/g/cd/soft/html, and add the standard ESD Software Engineering Group Unix web page header on them at a minimum.  If possible, apply the standards listed in the template located at


    4.        Problem:         There appear to be redundant folders.

    Solution:         We have both a CD_SOFT/html/slaconly and a CD_SOFT/html/share/slaconly. Why do we have these two. If there's no good reason, amalgamte them under just CD_SOFT/html/slaconly and fix the links. Note, slaconly in the pathname tells the web server not to let anyone from outside SLAC access the page. Seems like we don't need both slaconlys though. 

    2.2       Easy Publication

    Currently, the easiest way to create a document using Microsoft Word or FrontPage and publish it to AFS is by saving the document to the appropriate AFS folder using the OpenAFS mounted file system.  SCS does not currently support the use of  OpenAFS with the Windows XP Operating System.  Although many individuals have made it work, SCS has warned that this will no longer be possible once Windows XP is at its highest security setting. 

    So what does SCS suggest?  The SCS-supported tool provided for copying files is WinSCP (, a freeware SCP (Secure CoPy) client for Windows which uses SSH (Secure Shell) to safely copy files between a local and a remote computer.  It works much like WS_FTP.  A user must log in, find the destination folder on the remote computer (AFS), then copy it over.  If a user wants to update an existing document, then the file must first be copied to the local computer for editing in Windows-based editor, then copied back to AFS.  The process is confusing and cumbersome. 

    Ideally, a knowledge base contributor should be able to open a document in a browser, make edits and publish quickly without having to memorize the exact location on AFS. 

    Specific Design Problems and Solutions 

    1.        Problem:         Publication location is unclear because there are so many possible publication locations.

    Solution:         Web page locations and their purposes will be organized as follows:



    What goes there




    ·        All Unix project documentation

    ·        Individual Unix account pages (

    ·        Unix

    ·        Not WebDAV-enabled



    ·        Mirror of AFS documentation (read-only)

    ·        Release announcements

    ·        Windows

    ·        SLAC-only


    ·        Individual Windows account pages (

    ·        Windows

    ·        Public


    ·        Index Panel

    ·        NLC Architecture, Networks and Software

    ·        Presentations/documentation that should be visible to the public (ICALEPCS Epics, Fireside Chat)

    ·        Windows

    ·        Public


    Web server

    ·        This Web server will be retired.  Documents will be moved to the appropriate directories (ug, pg, req, design on afs, webmcc, or www-group depending on its visibility and content



    ·        This Web server will be kept unchanged, but new documentation should not be placed here




    2.      Problem:         Authoring privileges are inconsistent.

    Solution:         Give the Software Group write access to the Web pages, so documentation can easily be updated.  Each publishing location should have an identified “Advanced Author” who can set folder permissions.  On AFS, this will depend on the ACL in each directory under afs/slac/g/cd/soft/html/. The ACL is probably the same for each subdirectory of afs/slac/g/cd/soft/html/, but still check which ACLs are there, and whether everyone in the software group is able to write to those directories.  For Windows, verify that the ESD Group has authoring privileges to http://www-group/cdsoft and


    3.      Problem:         A User Guide to help people understand methods and locations for publishing does not exist.

    Solution:         Write a Users' Guide to ESD Software Group Web Site. This should include:

    1.        Help page for web page writing and publishing. This should cover help for each of:

    a.       Publishing to the Unix web space under /afs/slac/g/cd/soft/html from XP. Include explicit instructions for Netscape Composer and Macromedia Contribute.

    b.      Writing and publishing to Windows Web space.

    2.        Guide to the directory scheme in place. That is, list the special purpose directories CD_SOFT/html/ug, CD_SOFT/html/req, CD_SOFT/html/design, and the other important directories we have in place.  A script will be written to create directories and symlinks for new projects.

    2.3       Network Independence

    A compromise of the control system’s security which would require us to disconnect from the SLAC network or AFS incapacity are current examples of conditions under which an operator would not be able to retrieve control system documentation. 

    A Web Server on the control-system side of the firewall is required. 

    Specific Design Considerations 

    1.       Question:     Should the local server be Unix or Windows?

        Discovery:   There are two advantages of a Windows-based Web server over a Unix server.  The first is that SCS has agreed to support it remotely.  The second is that the current configuration for Windows servers that SCS supports allows for publishing via WebDAV (Web-based Distributed Authoring and Versioning,  WebDAV is a set of extensions to the HTTP protocol which allows users to collaboratively edit and manage files on remote web servers.  Clients include Microsoft Word and Microsoft Front Page.  Although a Unix Server would have eliminated cross-platform file copying, SCS will only support AFS, not NFS.  An AFS server would not meet our disconnect requirement, and an NFS server would require resources for maintenance.

        Decision:        We have purchased a Windows server,  It is physically located in our Computer Room. 


    2.      Question:Should documentation be written to AFS, WEBMCC, or both?

    Discovery:   Ideally, document writers would be able to choose their publishing tool and write to either Unix or Windows space.  However, constant mirroring is not possible.  The natural place for documentation to be housed is with the application or project.  As many of our applications are in AFS, it follows that supporting documentation should be kept in AFS.

       Decision:     All documentation will be published to the AFS directory /afs/slac/www/grp/cd/soft.  All AFS documentation in this directory will be mirrored to our new Windows IIS server, which is physically located in our Computer Room. Mirroring will be accomplished using GNU Wget (, a free network utility used to retrieve files using HTTP, HTTPS  and FTP.  Wget will translate absolute URLs to the local web server while it recursively mirrors the directories.  WebDAV publication to AFS is still under investigation, but FTP publishing is currently available with tools such as Netscape Composer and Macromedia Contribute.  

    2.4       Other Problems

    1. Problem:         Nodenames are visible to the public.

      Solution:         Move control-system detailed operational pages to /afs/slac/g/cd/soft/html/slaconly, and fix links.  Pages which should be moved are those that include nodenames, like "opi00gtw00", or "MCC.SLAC.STANFORD.EDU". This may well entail finding all references to those pages and changing the link! 

    ·        Our software releases pages ( and below are such pages that have node names and should be moved to slac-only. This is a cgi system, so moving it may not be trivial).

    Programmers' Guides, Users' Guides, Requirements, Design, Papers, Administration, How-To, Hardware, IOC, Database

    [SLAC ESD Software Engineering Group][ SLAC Home Page]

    Author: G. DeContreras, 14-Apr-2003
    Modified by: