[NeXus-definitions-tickets] [NeXusDefinitions] #211: improve NXImpatient

[NeXus Base Classes and Instrument Definitions]

#211: improve NXImpatient
----------------------------+----------------------------
 Reporter:  Tobias Richter  |      Owner:  Tobias Richter
     Type:  enhancement     |     Status:  new
 Priority:  major           |  Milestone:
Component:  general         |   Keywords:
----------------------------+----------------------------
 Pete J and me wrote:

 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.

 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.

 > 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.

-- 
Ticket URL: <http://trac.nexusformat.org/definitions/ticket/211>
NeXus Base Classes and Instrument Definitions <http://www.nexusformat.org/>
NeXus Base Classes and Instrument Definitions