diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index fcb2b33680..0f5d3324f3 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -789,6 +789,7 @@ INPUT = \ @abs_top_srcdir@/libsrc4/ncfunc.c \ @abs_top_srcdir@/libsrc4/nc4dim.c \ @abs_top_srcdir@/libsrc4/nc4attr.c \ + @abs_top_srcdir@/libsrc4/nc4cache.c \ @abs_top_srcdir@/libhdf5/nc4info.c \ @abs_top_srcdir@/libsrc4/nc4dispatch.c \ @abs_top_srcdir@/libnczarr/zarr.c \ @@ -2036,7 +2037,7 @@ SKIP_FUNCTION_MACROS = YES # TAGFILES = html/guide.tag=./html_guide "html/tutorial.tag = ./html_tutorial" #TAGFILES = ../../NUG/html/nug.tag=../../../NUG/html -TAGFILES = ../../NUG/html/nug.tag=https://docs.unidata.ucar.edu/nug +#TAGFILES = ../../NUG/html/nug.tag=https://docs.unidata.ucar.edu/nug # When a file name is specified after GENERATE_TAGFILE, doxygen will create a # tag file that is based on the input files it reads. See section "Linking to diff --git a/docs/FAQ.md b/docs/FAQ.md index 380dfda7e0..ba4a99aeef 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -67,7 +67,7 @@ that is part of the netCDF software distribution. It is a command line tool that provides a text representation of a netCDF file's data, just its metadata, or just the data for specified variables, depending on what arguments you use. For more information, -see the \ref ncdump_guide documentation. +see the [ncdump User's Guide](https://docs.unidata.ucar.edu/nug/current/netcdf_utilities_guide.html#ncdump_guide) documentation. Another good tool for conversion of netCDF data to text is the ["ncks" program](http://nco.sourceforge.net/nco.html#ncks-netCDF-Kitchen-Sink) that's one of the utility programs in the [NCO (NetCDF Operators)](software.html#NCO) package. Similar capabilities are available using programs from the [CDO (Climate Data Operators)](software.html#CDO) software, commands from [NCL (NCAR Command Language)](software.html#NCL), or various other packages such as [ANAX](http://science.arm.gov/~cflynn/ARM_Tested_Tools/), cdf2asc, and NOESYS, all "third party" netCDF utilities developed and supported by other organizations. You can find more information about these third-party packages on the [Software for Manipulating or Displaying NetCDF Data](software.html) page. @@ -322,7 +322,7 @@ We test releases on the following operating systems with various compilers: - Solaris - Windows (some versions, see below) -The [NetCDF Installation and Porting Guide](@ref getting_and_building_netcdf) explains how to build netCDF from source on various platforms. Often, it's as easy as running +The [NetCDF Installation and Porting Guide](https://docs.unidata.ucar.edu/nug/current/getting_and_building_netcdf.html) explains how to build netCDF from source on various platforms. Often, it's as easy as running ~~~~ {.boldcode} ./configure @@ -483,7 +483,7 @@ How do I build and install netCDF for a specific development environment? {#How- You have to build and install the netCDF C library first, before you build and install other language libraries that depend on it, such as Fortran, C++, or Python netCDF libraries. The netCDF Java library is mostly independent of the netCDF C library, unless you need to write netCDF-4 files from Java, in which case you will also need an installed netCDF C library. For more details, see -[NetCDF Installation and Porting Guide](@ref getting_and_building_netcdf). +[NetCDF Installation and Porting Guide](https://docs.unidata.ucar.edu/nug/current/getting_and_building_netcdf.html). ---------- diff --git a/docs/nczarr.md b/docs/nczarr.md index af10387c60..19546d55ff 100644 --- a/docs/nczarr.md +++ b/docs/nczarr.md @@ -190,7 +190,7 @@ be a prefix of any other key. There several other concepts of note. 1. __Dataset__ - a dataset is the complete tree contained by the key defining the root of the dataset. -Technically, the root of the tree is the key /.zgroup, where .zgroup can be considered the _superblock_ of the dataset. +Technically, the root of the tree is the key \/.zgroup, where .zgroup can be considered the _superblock_ of the dataset. 2. __Object__ - equivalent of the S3 object; Each object has a unique key and "contains" data in the form of an arbitrary sequence of 8-bit bytes. diff --git a/docs/notes.md b/docs/notes.md index 133670b13b..73ae15703f 100644 --- a/docs/notes.md +++ b/docs/notes.md @@ -107,3 +107,44 @@ that is returned by nc_open() and nc_create().) For netCDF-4/HDF5 files, netCDF IDs can come not just from nc_open() and nc_create(), but also from nc_def_grp(), nc_inq_grps(), nc_inq_ncid(), nc_inq_grp_parent(), and nc_inq_grp_full_ncid(). + +# NetCDF Names {#object_name} + +## Permitted Characters in NetCDF Names + +The names of dimensions, variables and attributes (and, in netCDF-4 +files, groups, user-defined types, compound member names, and +enumeration symbols) consist of arbitrary sequences of alphanumeric +characters, underscore '_', period '.', plus '+', hyphen '-', or at +sign '@', but beginning with an alphanumeric character or +underscore. However names commencing with underscore are reserved for +system use. + +Beginning with versions 3.6.3 and 4.0, names may also include UTF-8 +encoded Unicode characters as well as other special characters, except +for the character '/', which may not appear in a name. + +Names that have trailing space characters are also not permitted. + +Case is significant in netCDF names. + +## Name Length + +A zero-length name is not allowed. + +Names longer than ::NC_MAX_NAME will not be accepted any netCDF define +function. An error of ::NC_EMAXNAME will be returned. + +All netCDF inquiry functions will return names of maximum size +::NC_MAX_NAME for netCDF files. Since this does not include the +terminating NULL, space should be reserved for ::NC_MAX_NAME + 1 +characters. + +## NetCDF Conventions + +Some widely used conventions restrict names to only alphanumeric +characters or underscores. + +Note that, when using the DAP2 protocol to access netCDF data, there +are reserved keywords, the use of which may result in undefined +behavior. See DAP2 Reserved Keywords for more information. diff --git a/docs/tutorial.dox b/docs/tutorial.dox index cc500cc8cc..40369442a4 100644 --- a/docs/tutorial.dox +++ b/docs/tutorial.dox @@ -68,7 +68,7 @@ The utility ncdump can be used to show the contents of netCDF files. By default, ncdump shows the CDL description of the file. This CDL description can be fed into ncgen to create the data file. -See also: \ref ncdump_guide +See also: [The ncdump User's Guide](https://docs.unidata.ucar.edu/nug/current/netcdf_utilities_guide.html#ncdump_guide) \subsection netcdf_utilities_ncgen ncgen @@ -76,15 +76,15 @@ The ncgen utility can take an ASCII input file, in CDL format, and generate a binary netCDF file. It is the opposite of ncdump. See also: -- \ref guide_ncgen -- \ref guide_ncgen3 +- [ncgen](https://docs.unidata.ucar.edu/nug/current/netcdf_utilities_guide.html#guide_ncgen) +- [ncgen3](https://docs.unidata.ucar.edu/nug/current/netcdf_utilities_guide.html#guide_ncgen3) \subsection netcdf_utilities_nccopy nccopy The nccopy utility can copy a netCDF file, changing binary format, chunk sizes, compression, and other storage settings. -See also: \ref guide_nccopy +See also: [nccopy](https://docs.unidata.ucar.edu/nug/current/netcdf_utilities_guide.html#guide_nccopy) \section external_netcdf_tools Tools for Manipulating NetCDF Files @@ -262,8 +262,9 @@ opaque types. These features may only be used when working with a netCDF-4/HDF5 -file. Files created in classic formats cannot support -groups or user-defined types (see \ref netcdf_format). +file. Files created in classic formats cannot support groups or +user-defined types (see [NetCDF File +Formats](https://docs.unidata.ucar.edu/nug/current/netcdf_introduction.html#netcdf_format)).

\image html nc4-model.png @@ -455,7 +456,8 @@ of netCDF-4. - \ref example_simple_xy_nc4 The examples are built and run with the “make check” command. (See -\ref building). +[Building +netCDF-C](https://docs.unidata.ucar.edu/nug/current/getting_and_building_netcdf.html#building)). The corresponding examples in each language create identical netCDF data files. For example, the C program sfc_pres_temp_wr.c produces the @@ -812,11 +814,13 @@ with nc_get_vara()/nc_put_vara(). \page parallel_io Parallel I/O with NetCDF-4 -NetCDF-4 provides parallel file access to both classic and netCDF-4/HDF5 files. -The parallel I/O to netCDF-4 files is achieved through the HDF5 library while -the parallel I/O to classic files is through PnetCDF. A few functions have been -added to the netCDF C API to handle parallel I/O. You must build netCDF-4 -properly to take advantage of parallel features (see \ref build_parallel). +NetCDF-4 provides parallel file access to both classic and +netCDF-4/HDF5 files. The parallel I/O to netCDF-4 files is achieved +through the HDF5 library while the parallel I/O to classic files is +through PnetCDF. A few functions have been added to the netCDF C API +to handle parallel I/O. You must build netCDF-4 properly to take +advantage of parallel features (see [Building with Parallel I/O +Support](https://docs.unidata.ucar.edu/nug/current/getting_and_building_netcdf.html#build_parallel)). The nc_open_par() and nc_create_par() functions are used to create/open a netCDF file with parallel access. diff --git a/include/netcdf.h b/include/netcdf.h index 47e1394d7c..35ef6f8cc2 100644 --- a/include/netcdf.h +++ b/include/netcdf.h @@ -334,21 +334,27 @@ there. */ #define NC_QUANTIZE_GRANULARBR 2 /**< Use Granular BitRound quantization. */ #define NC_QUANTIZE_BITROUND 3 /**< Use BitRound quantization. */ +/**@{*/ /** When quantization is used for a variable, an attribute of the * appropriate name is added. */ #define NC_QUANTIZE_BITGROOM_ATT_NAME "_QuantizeBitGroomNumberOfSignificantDigits" #define NC_QUANTIZE_GRANULARBR_ATT_NAME "_QuantizeGranularBitRoundNumberOfSignificantDigits" #define NC_QUANTIZE_BITROUND_ATT_NAME "_QuantizeBitRoundNumberOfSignificantBits" +/**@}*/ +/**@{*/ /** For quantization, the allowed value of number of significant * decimal and binary digits, respectively, for float. */ #define NC_QUANTIZE_MAX_FLOAT_NSD (7) #define NC_QUANTIZE_MAX_FLOAT_NSB (23) +/**@}*/ +/**@{*/ /** For quantization, the allowed value of number of significant * decimal and binary digits, respectively, for double. */ #define NC_QUANTIZE_MAX_DOUBLE_NSD (15) #define NC_QUANTIZE_MAX_DOUBLE_NSB (52) +/**@}*/ /** The netcdf version 3 functions all return integer error status. * These are the possible values, in addition to certain values from diff --git a/libdispatch/dattinq.c b/libdispatch/dattinq.c index 2d878a5ca3..baba2840bc 100644 --- a/libdispatch/dattinq.c +++ b/libdispatch/dattinq.c @@ -30,8 +30,9 @@ Research/Unidata. See \ref copyright file for more info. */ * @param name Pointer to the location for the returned attribute \ref * object_name. \ref ignored_if_null. * - * @param xtypep Pointer to location for returned attribute \ref - * data_type. \ref ignored_if_null. + * @param xtypep Pointer to location for returned attribute [data + * type](https://docs.unidata.ucar.edu/nug/current/md_types.html#data_type). \ref + * ignored_if_null. * * @param lenp Pointer to location for returned number of values * currently stored in the attribute. For attributes of type @@ -318,8 +319,8 @@ nc_inq_natts(int ncid, int *nattsp) * * @param name Attribute \ref object_name. * - * @param xtypep Pointer to location for returned attribute \ref - * data_type. + * @param xtypep Pointer to location for returned attribute [data + * type](https://docs.unidata.ucar.edu/nug/current/md_types.html#data_type). * * @section nc_inq_atttype_example Example * diff --git a/libdispatch/dvar.c b/libdispatch/dvar.c index 8ed6c46bbf..fe029f44c6 100644 --- a/libdispatch/dvar.c +++ b/libdispatch/dvar.c @@ -148,7 +148,9 @@ nc_create(), nc_def_grp(), or associated inquiry functions such as nc_inq_ncid(). @param name Variable @ref object_name. - @param xtype @ref data_type of the variable. + @param xtype (Data + type)[https://docs.unidata.ucar.edu/nug/current/md_types.html#data_type] + of the variable. @param ndims Number of dimensions for the variable. For example, 2 specifies a matrix, 1 specifies a vector, and 0 means the variable is a scalar with no dimensions. Must not be negative or greater than the @@ -488,7 +490,7 @@ nc_def_var_deflate(int ncid, int varid, int shuffle, int deflate, int deflate_le types return an error (NC_EINVAL). Variables that use quantize will have added an attribute with name - ::NC_QUANTIZE_[ALGORITHM_NAME]_ATT_NAME, which will contain the + NC_QUANTIZE_[ALGORITHM_NAME]_ATT_NAME, which will contain the number of significant digits. Users should not delete or change this attribute. This is the only record that quantize has been applied to the data. @@ -640,7 +642,7 @@ nc_def_var_fletcher32(int ncid, int varid, int fletcher32) @note Scalar variables may have a storage of NC_CONTIGUOUS or NC_COMPACT. Attempts to set chunking on a scalare variable will - cause ::NC_EINVEL to be returned. Only non-scalar variables can + cause ::NC_EINVAL to be returned. Only non-scalar variables can have chunking. @param ncid NetCDF ID, from a previous call to nc_open() or