more documentation work

configure.ac

@@ -104,7 +104,6 @@ AC_ARG_ENABLE([docs],
                               [enable building of documentation with doxygen.])])
 test "x$enable_docs" = xyes || enable_docs=no
 AC_MSG_RESULT([$enable_docs])
-AM_CONDITIONAL(BUILD_DOCS, [test "x$enable_docs" = xyes])
 
 # Does the user want to developer documentation?
 AC_MSG_CHECKING([whether PIO developer documentation should be build (only for PIO developers)])
@@ -118,6 +117,7 @@ AC_MSG_RESULT([$enable_developer_docs])
 if test "x$enable_developer_docs" = xyes; then
    enable_docs=yes
 fi
+AM_CONDITIONAL(BUILD_DOCS, [test "x$enable_docs" = xyes])
 
 # Is doxygen installed?
 AC_CHECK_PROGS([DOXYGEN], [doxygen])

doc/source/GettingStarted.txt → doc/source/Introduction.txt

@@ -1,6 +1,6 @@
 @tableofcontents
 
-/*! @page intro Introduction 
+/** @page intro Introduction 
 
 PIO is a software interface layer designed to encapsolate the
 complexities of parallel IO and make it easier to replace the lower

doc/source/Makefile.am

@@ -4,5 +4,5 @@
 
 EXTRA_DIST = api.txt CAMexample.txt Decomp.txt faq.txt Installing.txt	\
 Testing.txt base.txt c_api.txt contributing_code.txt Error.txt		\
-Examples.txt GettingStarted.txt mach_walkthrough.txt			\
+Examples.txt Introduction.txt mach_walkthrough.txt			\
 testpio_example.txt

doc/source/contributing_code.txt

@@ -133,103 +133,5 @@ hours). Any test failures and the merge to master may be rolled back.
 
 </ul>
 
-## Formatting Example ##
-
-<pre>
-/** 
- * \@ingroup PIOc_inq_attname
- * The PIO-C interface for the NetCDF function nc_inq_attname.
- *
- * This routine is called collectively by all tasks in the communicator 
- * ios.union_comm. For more information on the underlying NetCDF commmand
- * please read about this function in the NetCDF documentation at: 
- * http://www.unidata.ucar.edu/software/netcdf/docs/group__attributes.html
- *
- * \@param ncid the ncid of the open file, obtained from
- * PIOc_openfile() or PIOc_createfile().
- * \@param varid the variable ID.
- * \@param attnum the attribute ID.
- * \@return PIO_NOERR for success, error code otherwise.  See PIOc_Set_File_Error_Handling
- */
-int PIOc_inq_attname(int ncid, int varid, int attnum, char *name) 
-{
-    iosystem_desc_t *ios;  /* Pointer to io system information. */
-    file_desc_t *file;     /* Pointer to file information. */
-    int ierr = PIO_NOERR;  /* Return code from function calls. */
-    int mpierr = MPI_SUCCESS, mpierr2;  /* Return code from MPI function codes. */
-
-    LOG((1, "PIOc_inq_attname ncid = %d varid = %d attnum = %d", ncid, varid,
-         attnum));
-
-    /* Find the info about this file. */
-    if (!(file = pio_get_file_from_id(ncid)))
-        return PIO_EBADID;
-    ios = file->iosystem;
-
-    /* If async is in use, and this is not an IO task, bcast the parameters. */
-    if (ios->async_interface)
-    {
-        if (!ios->ioproc)
-        {
-            int msg = PIO_MSG_INQ_ATTNAME;
-            char name_present = name ? true : false;
-
-            if(ios->compmaster) 
-                mpierr = MPI_Send(&msg, 1,MPI_INT, ios->ioroot, 1, ios->union_comm);
-
-            if (!mpierr)
-                mpierr = MPI_Bcast(&ncid, 1, MPI_INT, ios->compmaster, ios->intercomm);
-            if (!mpierr)
-                mpierr = MPI_Bcast(&varid, 1, MPI_INT, ios->compmaster, ios->intercomm);
-            if (!mpierr)
-                mpierr = MPI_Bcast(&attnum, 1, MPI_INT, ios->compmaster, ios->intercomm);
-            if (!mpierr)
-                mpierr = MPI_Bcast(&name_present, 1, MPI_CHAR, ios->compmaster, ios->intercomm);
-        }
-
-        /* Handle MPI errors. */
-        if ((mpierr2 = MPI_Bcast(&mpierr, 1, MPI_INT, ios->comproot, ios->my_comm)))
-            check_mpi(file, mpierr2, __FILE__, __LINE__);
-        if (mpierr)
-            return check_mpi(file, mpierr, __FILE__, __LINE__);
-    }
-
-    /* If this is an IO task, then call the netCDF function. */
-    if (ios->ioproc)
-    {
-\#ifdef _PNETCDF
-        if (file->iotype == PIO_IOTYPE_PNETCDF)
-            ierr = ncmpi_inq_attname(file->fh, varid, attnum, name);
-\#endif /* _PNETCDF */
-\#ifdef _NETCDF
-        if (file->iotype != PIO_IOTYPE_PNETCDF && file->do_io)
-            ierr = nc_inq_attname(file->fh, varid, attnum, name);
-\#endif /* _NETCDF */
-        LOG((2, "PIOc_inq_attname netcdf call returned %d", ierr));
-    }
-
-    /* Broadcast and check the return code. */
-    if ((mpierr = MPI_Bcast(&ierr, 1, MPI_INT, ios->ioroot, ios->my_comm)))
-    {
-        check_mpi(file, mpierr, __FILE__, __LINE__);            
-        return PIO_EIO;
-    }
-    check_netcdf(file, ierr, __FILE__, __LINE__);
-
-    /* Broadcast results to all tasks. Ignore NULL parameters. */
-    if (!ierr)
-        if (name)
-        {
-            int namelen = strlen(name);
-            if ((mpierr = MPI_Bcast(&namelen, 1, MPI_INT, ios->ioroot, ios->my_comm)))
-                check_mpi(file, mpierr, __FILE__, __LINE__);
-            if ((mpierr = MPI_Bcast((void *)name, namelen + 1, MPI_CHAR, ios->ioroot,
-                                    ios->my_comm)))
-                check_mpi(file, mpierr, __FILE__, __LINE__);
-        }
-
-    return ierr;
-}
-</pre>
 
 */