THDL Toolbox > Developers' Zone > Web Development > File Naming and Storage Conventions For THDL
File Naming and Storage Conventions For THDL
Conventions for THDL Directories and Files
This document covers conventions for naming and storage of assets for the Tibetan and Himalayan Digital Library, www.thdl.org.
Naming Conventions
Always use all lower case. There is no reason to use Upper Case or CamelCase, or, ALLCAPS. When all files and directories are always lower case, there is never any doubt as to whether something was uppercased or not. Plus it saves on hitting the shift key and prevents errors when entering URLs for links, etc. It is easier on the eyes as well.
Never use spaces in directory or file names. The THDL is run off of a Unix server, and Unix forbids spaces in names.
For multiple term entities in a file/dir name, use hyphens between the words. Do not use dots . except for file extension. Do not use underscores; they are problematic in that they are sometimes mistaken for spaces when the name is underlined, which can happen if it’s linked for instance. So, for example, gompa-on-fire.html, but not gompa.on.fire.html or gompa_on_fire.html or gompa on fire.html.
Finally, keep names short, while not shortening them so much that they are inexplicable.
XML Essays
The file name should be author's last name plus an abbreviated description of the content (as short as possible while still indicating the basic content of the essay and being unique). Example: dreyfus-monastic-instruction.xml. If the essay has more than one author, use the same convention but add -etal after the author's name. Example: dreyfus-etal-monastic-instruction.xml.
File Names for PDFs of Texts
For PDF files of journal articles, books, etc., the filename format is author's last name plus an abbreviated description of the content (as short as possible while still indicating the basic content of the essay and being unique). Example: hopkins-maps-of-profound.pdf.
Storage of Assets
First, the general rule of thumb: An asset should be placed only as high on the directory tree as necessary. That is, if you have an image that is used across the whole site, like the THDL logo, it qualifies for the top level /images directory; you wouldn’t want it hiding down somewhere like collections/images or whatever. Conversely, if you have an image that is used only in cultgeo, it has no business cluttering up the top level images directory, it should live in /collections/cultgeo/images/.
This goes for html/xml files as well as images and other kinds of assets. Just as it would be senseless to have html files for the Medicine collection living up at the top level directory, the images that are used only in /collections/medicine/ shouldn’t be up there either. This standard keeps the upper levels of the site free from clutter and interference – and not just from THDL fulltimers. As we have more and more people working on sub-sections of the site, we don't need want them mucking around in the upper levels of the directory tree, possibly damaging/destroying important things.
A final guideline is to make sure you don’t overdo the sub-sub-subdirectorization of the content. Typically content will dictate when you need a new subdirectory, but if any given project spawns more than three levels, you might want to think twice about it.
XML Essays
All essay xml files go in 
http://texts.thdl.org/essays/, and then in the subdirectory that corresponds to the first letter of the author's last name. So an essay by Dan Martin would go in http://texts.thdl.org/essays/m. If the essay has multiple authors, put it in the directory corresponding to the first letter of the author's last name.
PDFs
Journal Articles
PDfs of journal articles reside in the /collections/reprints/ directory. Within that, there is a subdirectory for each journal (often the initials of the journal name or another abbreviation), a subdirectory for each volume, and a subdirectory for each issue. Example: an article from the Journal of Tibetan Studies, volume 15, issue 3, would go in this directory: http://www.thdl.org/collections/reprints/jts/15/3/
Books
PDfs of single-author books reside in the /collections/reprints/books/ directory, and then in the subdirectory that corresponds to the first letter of the author's last name. Example: a book by Dan Martin would go in /collections/reprints/books/m. If the book is not a collection of articles or chapters by different authors but has more than one author, put it in the directory corresponding to the first letter of the author's last name.