[NeXus-tech] NXimpatient

[Pete Jemian]

On 12/12/2011 8:23 AM, Tobias.Richter at diamond.ac.uk wrote:
> Hi,
>
> It took some time, but now I've had a closer look at the document.

Thanks!

>
> Of the 23 pages it generates 11 are either empty or contain meta information like title and tables of contents. If we didn't attempt laying it out as a book (which we agree it does not try to be) we'd be near 10 pages and a TOC wouldn't even be required any more.

Can you configure sphinx so that "make latexpdf" does not generate the 
blank pages?  It's probably in the latex source.


>
> Section 5.1 (What goes into a NeXus File) is too late to explain the structure. Reading a file (Chapter 4) cannot be sensibly done before you know what is where (hence I disagree with the statement at the beginning of chapter 5). And chapter 2 already tells half the story anyway. That's where I'd move 5.1 into.

Agreed.  Make the move.
There is also a procedure in the manual's FAQ section that describes how 
to find the plottable data.  That's worthy in the Impatient docs.


>
> Section 5.3 does not work for me. The file system analogy works when introducing hdf5 groups and datasets, but struggles with attributes (although many file systems support them). But presenting this at the very end, after the NeXus classes and structure have been introduced and are now ignored, confuses me.

The file system analogy started with the HDF Group.  The blank spots in 
the table might be the cause of your concern.  What's best for now, 
removing any mention of attributes at this point?  Removing the table?
The table seems useful but perhaps in the wrong place.


>
> One of the main requests from Chris and friends was simple instructions how to write a NeXus file outside the API. What are the elements the API and tools look for. How are they formatted, what NeXus version to I claim, what is the target attribute on links used for?
> As we are only writing using the API and not even generating links we are not really addressing that in this document.

True for Chris's need.  But others coming before Chris, just wanted to 
know how to read a NeXus file.


>
> I believe Pete J has put some h5dumps for example files into the manual. That should be directly linked.

There is an Examples chapter that is now in a stable position.


>
> Freddie already made the point that the C examples are not too helpful for the impatient. On the 12 pages of content we have examples in C/NAPI, C/HDF5, python/NAPI, python/h5py, and MATLAB. I'd limit that to C/NAPI and python h5py and refer to the full manual for others. It is enough to get the idea of both the NAPI and non-NAPI approach while being reasonably concise. If you program C/HDF5 and you are looking at the h5py code you will know where to throw in your variable declarations, a bunch of close calls and a few mallocs for good measure. I intentionally left out the 'free' calls, as our example doesn't have any either.

Agreed


>
> If there is some consensus I'd be happy to make the suggested changes. I'd see how far I get with the open problems.
>
> Regards,
>
> Tobias

You have my vote to do this.


Also, can anyone supply the four missing files noted below?
 > NXfile.h5
 > sn2013287.nxs
 > powder.h5
 > NXfile.nxs

Pete

> ________________________________________
> From: nexus-tech-bounces at nexusformat.org [nexus-tech-bounces at nexusformat.org] on behalf of Pete Jemian [prjemian at gmail.com]
> Sent: 22 November 2011 16:29
> To: nexus-tech at nexusformat.org
> Subject: Re: [NeXus-tech] NXimpatient
>
> On reviewing the NXimpatient.rst document, there are several example
> NeXus data files in the example code.
>
> Can someone supply (email to me, commit to svn, identify a URL, ...)
> copies of these files?  One is already found.
>
> NXfile.h5
>
> sn2013287.nxs
>
> powder.h5
>
> lrcs3701.nxs
>          http://svn.nexusformat.org/definitions/exampledata/IPNS/LRMECS/lrcs3701.nxs
>
> NXfile.nxs
> _______________________________________________
> NeXus-tech mailing list
> NeXus-tech at nexusformat.org
> http://lists.nexusformat.org/mailman/listinfo/nexus-tech
>