Topics

• Features
• Contacts
• Inserting Complete Versions
• Comments on Browsers
• Other Notes Systems

Introduction

The Beams Division has had a variety of notes systems which document various aspects of the complex and its operations. These systems have evolved in various ways since their introduction in the era when all documents were circulated as paper copies. In the fall of 2002, it was recognized that the work of the Main Injector Group was being impeded by the fact that their web system for documents was difficult to maintain and available new documents had not been added for a couple of years. A document database system which had evolved by use in several experimental groups was implemented to replace the MI-Notes web page system. This system was then made available to various groups and now is open for use across the Beams Division. This note will provide my personal view concerning current use of this system.

Additional Information on the Document Database

A paper on this document system, A Web Based Document Database, was presented at CHEP03. It provides a different sort of overview of this system. The 'get instructions' menu item within the database and references therein provide detailed information on the system and its use. Reference to a more technical description of the system is provided there: BTeV Document Database Design and Interface. If you find this note useful, it is linked as the 'Useful notes' menu item within the database.

DocDB Features

Please access the Beams Division Document Database. The system is implemented using a relational database, some perl code and a web interface.

Some Features to Notice

• Public access is provided for many documents. More restrictive group access is defined for limiting document viewing. Using the public access, selection on the initial menu provides you with a form for accessing documents in various ways. A full-featured search option is supplemented by displays of documents by author, by topic or by revision date.
• User groups control document insertions and updates via username/password combinations on the web server. Any of these passwords provide access to the general interface of the system.
• In spring 2003 it was determined that a division-wide group with associated username/password would suffice for general use in the Beams Division. Additional administrative groups could be implemented for special uses.
• A 'review' group with read-only access is available to share documents with outside reviewers.
• Access via the general link (Beams DocDB at the top or bottom or Beams Document Database on the left) provides a full-featured menu in addition to that of the public interface. This menu adds a "Create or change" feature on the left and a variety of useful options to explore on the right.
• Online help will tell you almost anything you need to know. The "Get Instructions" link on the right side of the main menu page is supplemented by specific help links for the labels on most forms (title, authors, keywords...).
• The "Create or change" link accesses a form for inserting or modifying documents on a standard or a customized form. Additionally, a user can add an author or conference.
• Creating a new document demands a title, of course, but also requires an entry in the abstract field. If no formal abstract is available, please consider adding a line or two to describe the contents succinctly. For consistency, when adding existing formal documents with no abstract, I fill that space with "N.A."
• Each document must be identified with at least one topic (organized in a Topic/Subtopic hierarchy) but one can and often should indicate more than one topic/subtopic to aid in searching.
• To provide additional search capability, keywords can and should be attached to a document. Since multiple keywords are input to the search mechanism as a space delimited list, we will suggest joining multiple words into a `keyword' using an underscore. At present, keyword searches are case insensitive. Our lists are all lower case except for acronyms. To help avoid searching frustration, consistent keyword use is helpful. A list of ``approved'' keywords is available in two (identical) lists: a simple list and a detailed list with definitions. A keywords link on the right side of the main menu accesses both of these while a link on the keyword help will pop up a new window for you with the simple keyword list. The detailed list also provides a search on that keyword. The main search system searches on substrings so using a portion of a keyword is sufficient for those searches.
• Documents will usually be placed into the document system by their authors. The web interface provided is very flexible and adequate and online help is available. Please do place documents into the system in the most widely accessible formats such as .ps or .pdf, however, source versions in MSWord, PowerPoint or LaTeX can be added in the system with figures in source format as suitable. Please consider adding complete document sources whenever possible.
• Users reading your document will appreciate use of the standard file extensions to identify the files you insert. The browser uses that as a hint (sometimes supplemented by information internal to the file) to choose how it will display the contents. This is familiar for many of us from setting our browsers for reading .ps and .pdf files. While most document producing programs will supply this by default, please be careful since some programs do not. The 'browse' button option for selecting a file will deposit something into the form and you can, at that point, check that the file extension is what you expect (.ps or .pdf or .tar or .zip ).
• Web documents (.html) are great and, like any other format, they can be inserted into DocDB. I note that using PowerPoint or Word or Excel to create an html output is likely to produce a very unwieldy document. For example a 20 page PowerPoint presentation may turn into 160 files to be inserted. This works fine for viewing but printing may be of `variable' quality.
• Only a few "gotcha's" have been noticed in several months of use. An important one is a strange interaction with file names which use blanks being manipulated on Windows, then inserted into the database. Just avoid file names with blanks and you won't need to know more. The bad experience involved converting a PowerPoint file by using PowerPoint to output html. Microsoft inserted the HTTP standard symbol (%20) in place of a blank and the DocDB then in use was baffled.
• To permit references to documents in preparation, one can reserve document numbers. Please exercise appropriate restraint.
• There is a flexible e-mail notification system to inform you about new documents which might interest you.

You will find most everything is obvious from the web interface.

DocDB Contacts

The following staff are contacts at present:

• Bruce C. Brown for Main Injector Group
• Ronald Moore for Tevatron Group
• Harry W. K. Cheung for Tevatron Group and Instrumentation Group
• Elliott McCrory for the Proton Source Group
• Tom Meyer for the Instrumentation Group
• Bob Scala for the RF Group
• Michael Syphers for the Beam Physics Group.

Inserting Complete Versions

Users of the document database are likely to lack one or more of the tools which a given author has to create documents. In particular, many Unix users cannot access MS Word or PowerPoint presentations (although there are programs available to access these file types on Unix). Similarly, some Windows users have not installed a Postscript viewer. We therefore recommend that the author seek to provide the document in formats which are widely readable such as POSTSCRIPT (.ps) or Portable Document Format (.pdf). If you have output in .ps, many Unix installations have a utility called ps2pdf to do the file conversion to .pdf. Windows users can 'print' to an Acrobat Distiller from Word or PowerPoint. Find a friend with Adobe Acrobat installed.

It is also true that many times a user would find it convenient to use something from your document in a new document so access to the source: figures, equations, or even templates or style files might be useful. The Document Database system encourages submission of a complete document -- all files for a given document. The source files for MSWord (.doc) or PowerPoint (.ppt) can be stored as well as postscript or .pdf versions. Perhaps you would like to include the Excel file which provides some calculation or data which you used and would like to share. The database can also accept data in any file format. For LaTeX documents, the supporting sources are likely to be in several files. For Web Documents (.html), the primary document may include files, such as included images, in separate files of various formats. We will describe how they can be conveniently brought along.

Some care should be exercised with regard to drawings. Procurement of fabricated items is often based on drawings with formal drawing numbers. Therefore formal drawing numbers are controlled. If you place a revisable version of a drawing into the database, consider making suitable notation changes so that the casual user will not produce and distribute a copy which can be mistaken for a formal release. I recommend the alternative of placing in the database only non-revisable versions (such as .ps or .pdf) of formal drawings.

When a document is selected from the database, the form displays the available files in lists: "Files in Document", "Other Files" (when applicable), and "Retrieve archive of files as" which provides a zip or tar archive file. When creating or adding files to a document, one selects 'main' (default) to have them displayed in the first list. The file classification can be modified using the "Update DB Info" option under "Create or Change".

Hints on Inserting Complete Versions

If you are storing a web page in DocDB, the most convenient way to assemble the needed files is to use the save feature of a browser. In Mozilla 1.2.1 one selects save as type `web page complete'. This results in an html file in the selected directory plus a subdirectory with the required files (and pointers suitably modified in the html file). There is a `all files' option in Netscape 4.7x and Internet Explorer 5 has the save `web page complete' but I have not confirmed that it provides the same capability. If one uses an otherwise unoccupied directory, the file specification for tar or zip is particularly simple. Note that while this brings along embedded images or other 'related' files, if your 'document' consists of several .html files, the browser cannot know to follow just some links (and cannot follow all links) so you need to exercise care to bring all of 'yours' along. This means putting them in the same directory or a subdirectory and correctly specifying the appropriate links. In placing a version of this document into the database I discovered that the appropriate 'relative' links had been replaced with 'complete' links -- but to the directory from which I was extracting the file. You can see this if you look at the 'Topics' menu in V2 of this document.

To assemble sources for LaTeX documents, one can simply copy them into an empty directory. It is useful to provide the TeX or LaTeX source (.tex), any graphic files which were used, and any special style files which may not be widely or conveniently available. I have also included the intermediate device independent .dvi file in case it might be useful.

The form which allows you to upload a complete document in an archive (tar or zip) format will also ask you to describe the file in that archive to be included as the 'main' file. Be prepared to provide that file name exactly.

Assembling tar Archive on Unix (Sun - Solaris)

    tar cf ../MI-0004.tar  . 

Assembling a zip archive on Windows

My Windows 2000 machine has WinZip loaded. I have used it to create a zip archive for uploading to DocDB. Here is what worked (described from the WinZip 'Classic' (not 'Wizard') interface).

1. Invoke WinZip.
2. Select New and give a file name.
3. It will then present a window for creating the archive. On the lower right corner devoted to Folders
   1. Select Recurse Folders
   2. Unselect Save Extra Folder Info (otherwise the subdirectory labeling will include a full or nearly full tree... ugh).
4. Then add the files using the 'Add with Wild Cards' option.

Comments on Browsers

Resizing Problems with Netscape 4.7

Since some of us remain using Netscape 4.7x for browsing (and e-mail), we are more sensitive to some features which others of you can ignore. A particularly aggravating feature is the poor handling of resizing by that Netscape version. If one is filling in a DocDB form and decide that a larger (or smaller) screen would make the job easier, you will have to realize that the form will be repainted and any data entered will be lost.

Selecting Multiple Items in a Menu List

Note also that the key combinations which permit one to select more than one item in a menu list (author, topic...) will be different with different browsers. Simple clicks, clicks with control key and perhaps shift-click will provide the selection of an additional (rather than all between or replacement) for a given browser.

• Using Netscape 4.75 on Sun-Solaris one uses a left-click with the mouse to select an item (first or multiple), the click again to unselect -- its a simple toggle.
• Using Netscape 4.79 or Mozilla 1.2.1 (also called Mozilla/5.0) or Internet Explorer 5 on a Windows 2000 platform, a left-click selects the first item in a menu list. Shift-left-click selects (perhaps many) additional ones from previously selected one through the new selected one. Control-left-click selects a new additional item. To delete any selected item use control-left-click on a highlighted item.
• I find that Netscape 7.0 on Windows98 supports the same operations as the Windows 2000 browsers just described.

More modern browsers better support the DocDB functionality.

Other Notes Systems

In its early days, Fermilab maintained two sets of formal note systems: TM (Technical Memos) and FN (Physics Notes). The Beams Division (then the Accelerator Division) had an Exp (Accelerator Experiment) notes system. The AntiProton Source project created PBar Notes as a separate system and the model was followed for Main Injector Notes and MTF Notes (Magnet Test Facility). In early 2003, a new page SEARCH for Fermilab Preprints has been provided by the Library group which makes easy access to many of these note systems (but not all). I note that there are PBar Notes available on the web are better accessed at this time via links on the Documents page of the Antiproton Source page reached via the Beams Division web site.

The Main Injector Group has maintained a formal note system since 1989. In the summer of 1998 and again one summer since then, summer help has scanned old documents and converted them to a machine readable form. The access to them has been provided via a web page (MI Notes). The system has not been successfully maintained for documents created since 1999. We have reserved Beams-doc numbers for available MI Notes. We indicate the MI-Note number in the "Publication Information" field. Efforts to move quality copies of these documents to DocDB is underway.MI-Notes are available from a paper file. Contact the Main Injector secretary for copies. A menu to access these from the document database web site is available and will be fully implemented when the insertion of MI-Notes is complete.

The EXP notes are available from Beams Division secretaries. A subtopic for them has been reserved under Beam Physics. I suggest that for transferring these and other notes systems, the option of using the "Publication Information" field to identify them can be quite satisfactory. Since it is a free-form data entry field, some care will be required to guarantee accuracy, but corrections of database information is not a problem.