Wiki Testing/ServerInstallationGuide7

Documenting Your Data

OPeNDAP's version 3.5 server contains provisions for supplying documentation to users about a server, and also about the data that server provides. When a server receives an information request (through the info service that invokes the dap_usage program), it returns to the client an HTML document created from the DAS and DDS of the referenced data. It may also return information about the server, and more detail about the dataset.

Users access this information by appending .info to a DAP URL. For example to get the HTML info page for an netCDF file, you might type something like this:

http://test.opendap.org/opendap/nph-dods/data/nc/fnoc1.nc.info

The Info service will return important information about your dataset even if you do not write custom HTML files for it. If you do write those files they will be concatenated with the default information returned by the usage server.

If you would like to provide more information about a dataset than is contained in the DAS and DDS, simply create an HTML document (without the html and body tags, which are supplied by the info service), and store it in the same directory as the dataset, with a name corresponding to the dataset filename. For example, the dataset fnoc1.nc might be documented with a file called fnoc1.html.

You can also provide documentation for a class of files that may have a common root in their names. For example, a file that would be used for data files called S00443.nc, S00444.nc and S00445.nc could be called S.html (or S00.html in this case). This file should be located in the directory where the data is located.

If you'd like to append information to the info message for all the files on a server, you can write a file called servername .html, where servername is one of nc, ff, hdf, jg, and so on.

You may prefer to override this method of creating documentation and simply provide a single, complete HTML document that contains general information for a dataset. If you call your documentation file fnoc2.ovr, the client will see only the contents of that file, and will not get the text generated by the dataset DAS and DDS, or the servername.html file.

More information about providing user information, including sample HTML files, and a complete description of the search procedure for finding the dataset documentation, may be found in The OPeNDAP Programmer's Guide .

Special Instructions for the OPeNDAP/JGOFS Handler

The JGOFS handler provides usage data in almost the same way as the other servers, but the dap_usage helper program is called usage-jg, and it functions slightly differently. For the general JGOFS handler and for each data object it serves, you can write a HTML document which the usage server will return when requested by users. You can write a HTML document that describes any special features of your particular JGOFS handler and save that document in a file named jg.html in the cgi-bin directory that holds the server programs.

[Tip:]The jg.html file could be used to provide descriptive information, including the names, for all the data objects served at your site.

The only special thing about this file is that you should include only those HTML tags that would fall between the body and body tags. Thus it should not contain the html, head, body or their matching counterparts.

To provide HTML for each JGOFS data object you serve, create a file whose name is based on the names of the data object you want to describe. For example, a file that would be used for all the s87_xbt data object used in the previous section's example would be s87_xbt.html. This file must be located in the directory where the top-level datafile is located, as defined in the data objects dictionary.

Users access this information by appending .info to a DAP URL. For example to get the HTML page for the URL used in the previous section, you'd type:

http://dods.gso.uri.edu/cgi-bin/nph-dods/s87_xbt.info