[NeXus-tech] NeXus documentation [SEC=UNCLASSIFIED]

[Pete Jemian]

I agree with P^2, go ahead with changes.
As we discovered recently, we can always back out changes (or parts) 
after review.

The part on "NeXus Design" is a high-level overview on how things work 
and is useful for the learner whereas Chapter 7 (NeXus classes) is the 
full specification but does not contain the overview at this time.  
Perhaps the high-level overview can be moved to the start of Chapter 7?  
Might make it easier to identify the parts of the overview that need 
updating with the NXDL rules.

The sections in the ClassDefinitions.xml chapter are automatically 
created from the nxdl.xml files (NXDL for now) using xslt.  This 
"documentation" xslt is different than the xslt that is used to 
transform NXDL into the XML Schema files (.xsd).  These transformations 
are handled by Makefile rules.

Thus, your first item "create the BaseClassSections.xml from the current 
nxdl.xml files" is the current practice.  Same for 
ApplicationClassSections.xml and would be the same for 
ContributedClassSections.xml if we had any contributed_definitions NXDL 
files.

Second (add nxdl.xsd) and third items (simple yet complete image of 
NeXus hierarchy) are good suggestions and can/will be built in.

Description of units in the manual is a topic that can probably progress 
now since the portrayal seems to be settled in NXDL.
Description of type may have to follow since there is still a bit of 
re-arranging necessary in the various .xsd files that support both NXDL 
and data file validation.

Sounds to me as if we have a TRAC ticket to create.

Pete




HAUSER, Nick wrote:
> Gentlemen,
>
> Let me know if it's OK to do what I've proposed below in the
> documentation:
>
> Chapter 1 MediaWikiManual.xml
> * rename MediaWiki Manual to Introduction
> * delete NeXus Design - now appears in Chapter 7. NeXus classes
>
>
> Chapter 7 ClassDefinitions.xml
> You've got references to
>
>     <xi:include href="BaseClassSections.xml"/>
>     <xi:include href="ApplicationClassSections.xml"/>
>     <xi:include href="ContributedClassSections.xml"/>
>
> I imagine that you intended to reference the xsl transformed nxdl.xml
> files in BaseClassSections.xml
> * transform the nxdl.xml files and create the BaseClassSections.xml from
> the current nxdl.xml files, or is it too early?
> * Add an image of nxdl.xsd next to the tabular example 
> * Once the NeXus.xsd is complete, is there a way we can represent the
> entire NeXus tree in a hierarchical way in an image, that isn't as
> verbose as the normal xsd images?
>
> * Has there been any more thought put into what goes into the
> ClassDefinitions.xml, especially the description of type and units?
>
> Cheers.  
>
> Nick.
>
> Nick Hauser
> Bragg Institute, Building 82
> Australian Nuclear Science and Technology Organisation PMB 1, Menai NSW
> 2234 AUSTRALIA
>
> T +61 2 9717 9474
> F +61 2 9717 9799
> M 0417 418 542
> E nick.hauser at ansto.gov.au    
> www.ansto.gov.au/research/bragg_institute
>
> Important: This transmission is intended only for the use of the
> addressee. It is confidential and may contain privileged information or
> copyright material. If you are not the intended recipient, any use or
> further disclosure of this communication is strictly forbidden. If you
> have received this transmission in error, please notify me immediately
> by telephone and delete all copies of this transmission as well as any
> attachments.
>  
>
> _______________________________________________
> NeXus-tech mailing list
> NeXus-tech at nexusformat.org
> http://lists.nexusformat.org/mailman/listinfo/nexus-tech
>   

-- 
----------------------------------------------------------
  Pete R. Jemian, Ph.D.                <jemian at anl.gov>
  Beam line Controls and Data Acquisition, Group Leader
  Advanced Photon Source,   Argonne National Laboratory
  Argonne, IL  60439                   630 - 252 - 3189
-----------------------------------------------------------
     Education is the one thing for which people
        are willing to pay yet not receive.
-----------------------------------------------------------