Dealing with files

Before we can start marking up a document there are a few mechanics to take care of. If your document is fairly small and you expect to be able to contain it completely within a single file (e.g. a resumé, a short article, etc), then you simply need to arrive at a reasonable filename, which must end in

    .html


If your document (work) is more complex and will involve more than one file, it is almost always wise to create a directory (folder) for all of its component files. You may also, if it makes sense, create subdirectories of that directory (folders within folders) to hold groups of like files. For example, if you are creating a document to hold your latest book Cataloging Standards for the Twenty First Century, you might create a directory called catstand, and then within that directory create subdirectories like this

    catstand
figures
chapter1
(14 inspired sections on the use of subfields go here)
chapter2
...
afterwrd


By doing this, you make it possible to move your entire work, as a single piece, to a new location and, in general, make it easier to maintain the work. It also allows you to re-use filenames (imagine not being able to use the name "Chapter 1" again).

Notes for DOS, Windows, Macintosh, and Unix users

DOS/Windows and Macs have different sets of restrictions on what you can name a file.

DOS & Windows
DOS filenames can be up to 8 characters long and have a 3 character extention, and contain a fairly restricted set of characters. Filenames are not case-sensitive and directory structure is indicated with backslashes thus: c:\foo\bar\bas
Macintosh
Macs, on the other hand, allow long file names, and permit the use of exotic characters including spaces and nonprinting characters. Filenames are case-sensitive and directory (folder) structure is designated with colons thus: disk:foo:bar:bas
Unix
Like the Mac, Unix has permissive bent, but has a different set of permitted characters and requires special handling for filenames with spaces and other oddball characters. Filenames are case-sensitive and directory structure is indicated with forward slashes thus: /foo/bar/bas

Guideline and conventions

All of this leads to headaches when documents are moved from one environment to another. Fortunately most servers and clients are pretty smart about this problem, so we can stick to a few guidelines to make life a little simpler. If you can manage it reasonably, try to name your documents according to these rules of thumb.

• Use lower case names
• Keep the name down to 8 characters or less, using only "a-z", "0-9", and "_" (underscore). If you must use a longer name, keep a record of the long name make sure that the first 8 characters are unique (i.e. don't name a series factsheet1.html, factsheet2.html, factsheet3.html, etc., since if they ever find their way to a DOS machine (and in a mixed computing environment like Stanford this is highly probable), they will all look like "factshee.htm" and DOS will be very, very unpleasant.
• Note that the extention ".html" is a bit magical in that it signals to the server that this is an HTML file and the server treats it specially. When a DOS foo.htm file is mounted on a Unix or Mac server, the server administrator will rename it foo.html. As a result, any reference within your document to foo.htm will point a nonexistent file! Therefore all references (URLS) within your document should refer to the longer .html form of the name, even if you are on a DOS system. (Fortunately, DOS is a bit flexible about this and if your browser tries to open a file on your machine named foo.html, foo.htm will be opened instead.).
• All paths (directory structures), should be indicated with forward slashes, not backslashes, even if you are on a DOS system. As above, your browser will treat a forward slash as a backslash on DOS systems, so you'll still be able to view your documents locally.

Walter Henry
Stanford University Libraries and Academic Information Resources