SLAC 16 May 1997
SLAC has collected most of its production WWW files into a single
/afs/slac.stanford.edu/www/, and uses this
document as a guide in naming files and their related URLs in that
space. This document assumes a basic knowledge of the UNIX operating
system and the AFS file
management system at SLAC.
Goals for the SLAC naming scheme are to:
www.slac.stanford.edu,and its production areas, there are a few specialized SLAC Web servers with their own production file spaces. Their owners, too, may find this document useful in regularizing their naming structures.
Production pages should reside in production file space. For the main
SLAC server, this means that production pages reside somewhere in the
/afs/slac.stanford.edu/www/ subdirectory tree. This
single location provides for easier maintenance of the rules file,
space, performance, and the information architecture itself.
Note that in this document, the word "page" may also be understood to mean "a page and its related files (such as image and PostScript )."
For more detailed descriptions, see SLAC Web Definitions.
which can be abbreviated at SLAC:
URLs have the prefix:
For example, the filename for the SLAC Experiment E144 Home Page would be:
and the fully qualified URL would be:
Here the name of the home page follows a common convention in which the name of the home page repeats the directory name with
.htmlon the end.
~USERNAME/public_html/). Non-production space is for testing and sharing informally.
While their use is generally discouraged, using symbolic links can help smooth the active migration of files from one place in the production Web file space to another, allowing users seamless access during the transition period.
Caution must be exercised when using symbolic links pointing from globally visible Web space to space that is normally seen only by those logged in to a SLAC host because such symbolic links may lead to unpleasant visibility surprises.
/comp/platform.htmland the subdirectories
/librarytreat subjects of interest to overlapping sets of SLAC and external users. Organizational files, such as those in the
/grp/irm/telecomsubdirectories describe some part of the SLAC organizational structure. There is overlap between the two categories.
The functional/organizational distinction appears at the top of the SLAC WWW file space and is continued lower down in the hierarchy. See "Appendix A: Naming Examples", below. Documents published for one or more major audiences outside the generating working group often belong in a functional subdirectory tree. These pages are usually relatively formal and generally have a broader audience than organizational pages. Revisions to these pages tend to be technical or procedural.
Documents targeted for an audience within a given group often belong in organizational space along with that group or department's home page. Pages of this kind are often more casual. Revisions to organizational pages (like other organizational elements of an institution) are likely to happen more frequently and have more impact on the existing information structure than are the revisions to the functional pages. Note that while there is an effort to group pages into these two separate categories, pages in organizational space often do include functional pages -- functional pages that are directed toward those inside the working group. The SCS group page is a good example of this.
/grp/CODE/filename, where CODE is usually the two or three character
BINLISTcode. There are more than sixty of these in use. See "Appendix B: Group Codes" for a list.
These codes such as
cd, pur, and
often already recognized by SLAC people. The
codes frequently focus on operational components of the SLAC
organizational structure that seem to be less likely to change than
the hierarchical levels above them. In any case, keeping the hierarchy
flatter means there are fewer components subject to change than if the
names reflected all levels of the current organization chart.
There are a few exceptions to using CODE. For example, the
BINLIST code for the SLAC Library is
for TechPubs is
pub, but these have other contexts in
UNIX (such as,
/usr/local/pub). Also, a group, such as the Library, may
be particularly identified with its name more than its code.
slac.stanford.edudomain (with a SLAC IP number -- 134.79...) when the fully qualified URL includes the word slaconly, such as
/pubs/slaconly/tip. Therefore, if you need to restrict access to SLAC users only, put slaconly (use only lowercase) somewhere in the fully qualified URL. Naming a file in this way will make it inaccessible on the Web to SLAC collaborators working remotely and should therefore be used with caution in the distributed collaborator environment.
Note that users with appropriate AFS privileges (including those
elsewhere in the HEP community with a current AFS token at SLAC) may
read any file in
/afs/slac/www space including those with
slaconly in their names by maneuvering through the file system.
Name-length limitations in AFS volume names are particularly important in re-establishing the file system after certain crashes, and thus short subdirectory names or clear abbreviations of those names are important. Short names are also faster to type and consistent with the UNIX style of labeling things. Very long names in URLs have caused some browser displays to break. It may be useful to remember that fully qualified pathnames are not true English, they are English-like names.
In addition to trying to keep directory names within the 3-8 character range, the following recommendations for naming subdirectories and files should help to promote a coherent and usable name space:
Consistent names help people recognize directories and files when they encounter them or even unearth them via a
where the top file (
ad.html) repeats the name of the subdirectory (
/ad) that contains it.
This option creates a clear association with the directory in which it resides and does not interfere with the automatic listing of the entire subdirectory that is specified by a trailing / on the URL.
This option allows for a shorter URL (as
the default filename and may be omitted), and suppresses the automatic
file listing of the subdirectory described above. If
index.html exists, non-SLAC people are not able to browse
the contents of the subdirectory through the web (SLAC people can
still access the subdirectory if they are logged on to a connected
UNIX file space). It can also make it a more complex task to extract
usage statistics on a file, and in some cases, can prevent the SLAC
search engine from indexing pages in the directory. If you do use this
convention, make sure that the directory will be indexed by ensuring
that at least one of the pages in production space points explicitly
to the top page, using
directoryname/)in the link.
This is a common WWW naming convention for top files, though it seems
to be becoming less frequently used. It is perhaps most appropriate
/grp pages, such as actual departmental home
pages. It does not interfere with the automatic listing of the files
in the directory.
.gif, otherwise avoid them. These endings are reserved for designated MIME types and other file formats. Naming your file with such an extension may result in your filename meaning something that you never intended it to mean. For example, if you were to name all of your PhotoShopTM files as something
.ps, many programs would assume that the files were PostScript files when they weren't and would therefore be unable to read them.
http://www.slac.stanford.edu/slac/www/tool/summary.html. Maintaining distinct page and script names will help users recognize the nature of the file.
/afs/slac/www/icon), unless a name is the name of something well-known in the plural, like
/stats. Fostering a consistent use of the singular will narrow the range of possibilities that searchers and maintainers are required to remember. Again, pathnames are not natural language; they merely borrow from the structures of natural language.
/slac/www/www-tech; but use
/emp/empopp. As long as it's clear, typing fewer characters rather than more is faster. Establishing compound words rather than hyphenated words as the standard will make it easier to remember or guess what would be the likely name for a given subdirectory (as well as allowing a broader range of subdirectories to be displayed in a subdirectory listing).
public_htmlis an unfortunate exception that was brought to SLAC as the default of the CERN server.
For new pages concerning an area of information that requires the creation of a new subdirectory, a one-working-day turnaround is the goal to set up the AFS groups and to request the AFS volume from the Server Support group. That group aims to have the AFS space set up within two working days. This three-day time frame assumes that the area fits into the existing information architecture and that the requestor has provided all the information described in "How to Install Pages in the Production SLAC Web," such as AFS-privileged user names and space estimates.
Finding an appropriate subdirectory name for a new kind of
information area, particularly at the highest subdirectory level in
AFS WWW space, may take quite a bit longer;
example. The time is needed to think through how the creation of a new
subdirectory may affect other aspects of file and page linking
design. This is particularly true in the cases of those subdirectories
that could easily fit in more than one directory.
Finding a good place for pages to reside at the outset can help minimize the URL changes which complicate page maintenance for everyone.
/afs/slac/www/. This Registrar will work to keep the high-level taxonomy sensible and consistent in light of specific user needs and system requirements. In the short run, Joan Winters has agreed to serve as the registrar with Ilse Vinson as backup registrar and Pat Kreitz as the "higher authority." Individual groups may find designating their own group registrars useful.
It is also recommended that SLAC develop or acquire tools to ease migration of pages through the system, including providing for file/URL renaming over the years. Cleaning out the obsolete files (and, where appropriate, putting them into /archive/YYYY, where YYYY is the year of last update) will keep the WWW information space easier to use.
/the SLAC Welcome Page (the default SLAC server page)
/slac/highlighted.html (the Highlighted SLAC Home Page)
/slac/detailed.html (the Detailed SLAC Home Page)
/slac/disclaimer.html (the SLAC Disclaimers, Copyright, and Other Fine Print)
/archive (important files that no longer have a current use)
/bis (business information systems)
/discourse (old mailing list items)
/edu (proposed for pages supporting SLAC's educational mission; some currently in
/eprise (pages relating to enterprise databases)
/esh (environment, safety, and health)
/exp (experiment, often multi-institutional)
/icon (SLAC-supported icons such as the SLAC seal)
/pubs (SLAC periodicals, etc.)
/slac (fairly formal pages of broad interest to the SLAC working community)
/visitor (proposed polished pages dealing with specialized information that is directed at visitors to the SLAC site)
/spires (pages relating to SPIRES applications)
/welcome (polished, introductory information about SLAC)
/xorg (proposed multi-institutional groups that include SLAC, such as task forces and committees)
/grp (group- or department-oriented information)
/bis/pers (proposed for personnel systems)
/edu/ssi (proposed replacement for
/edu/ssp (proposed )
/emp/emp-opp (employment opportunities)
/icon/usr (user-contributed icons of wide interest to the SLAC community)
/grp/pep (possible for SLAC members of the PEP-II group)
/grp/xorg (proposed for cross-SLAC groups, such as task forces and committees)
AAO Affirmative Action Office
ACC Accounting Office
AD Accelerator Department
ARA Accelerator Research Department-A
ARB Accelerator Research Department-B
ARD Accelerator Research Department
BAS Business Applications Support Group
BSD Business Services Division
BU Budget Office
CB Crystal Ball Project
CD Controls Department
CG Computation Research Group
CYO Cryogenics Operations
DO Director's Office
DOE US Department of Energy
EA Experimental Group A
EB Experimental Group B
EC Experimental Group C
EE Experimental Group E
EFD Experimental Facilities Department
EG Experimental Group G
EI Experimental Group I
EK Experimental Group K
EPR Environmental Protection and Restoration
ESA End Station A Users
ESH Environment, Safety, and Health Division
FAC Facilities Office
FD Palo Alto Fire Department, Station 7 (ESH)
IRM Information Resource Management and Technology Transfer
IS Information Services
KLY Klystron and Microwave
MD Mechanical Design
ME Mechanical Engineering
MED Medical Department (ESH)
MFD Mechanical Fabrications Department
NPS Nuclear Physics at SLAC
OHP Operational Health Physics (ESH)
PAO Public Affairs Office
PCD Power Conversion Department
PE Plant Engineering
PEL Physical Electronics
PEP Positron Electron Project
PER Personnel Department
PPO Planning and Assessment Department (ESH)
PRC Property Control
RD Research Division
RPG Radiation Physics (ESH)
SCS SLAC Computing Services
SHA Safety, Health, and Assurance Department (ESH)
SLD SLAC Large Detector
SSR Stanford Synchrotron Radiation Lab
TD Technical Division
THP Theoretical Physics
TSP Accelerator Theory and Special Projects
VAC Vacuum Group
WM Waste Management (ESH)
Joan Winters with Jennifer Masek