source: 1dwg/trunk/doc/wiki.xml @ 118

Last change on this file since 118 was 118, checked in by prjemian, 12 years ago

current PDF of manual, refs #19

  • Property svn:keywords set to Date Revision Author HeadURL Id
File size: 42.2 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<?oxygen RNGSchema="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" type="xml"?>
3<!--
4    ########### SVN repository information ###################
5    # $Date$
6    # $Author$
7    # $Revision$
8    # $HeadURL$
9    # $Id$
10    ########### SVN repository information ###################
11-->
12<chapter xml:id="wiki-chapter" xmlns="http://docbook.org/ns/docbook" version="5.0"
13    xmlns:xlink="http://www.w3.org/1999/xlink">
14    <title>Wiki Manual</title>
15    <!-- from: http://www.smallangles.net/wgwiki/index.php/cansas1d_documentation -->
16    <section xml:id="cansas1d_documentation-Disclaimer">
17        <title>Disclaimer</title>
18        <para>This description is meant to inform the community how to layout the information within
19            the XML files. However, should the information in this document and the <link
20                xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd"
21                >cansas1d/1.0 SAS XML Schema</link>
22            (http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd) differ, the XML
23            Schema will be deemed to have the most correct description of the standard.</para>
24    </section>
25    <section xml:id="cansas1d_documentation-Objective">
26        <title>Objective</title>
27        <para>One of the first aims of the canSAS (Collective Action for Nomadic Small-Angle
28            Scatterers) forum of users, software developers, and facility staff was to discuss
29            better sharing of SAS data analysis software. <link
30                xlink:href="http://www.smallangles.net/canSAS">CanSAS</link>
31            (http://www.smallangles.net/canSAS) identified that a significant need within the SAS
32            community can be satisfied by a robust, self-describing, text-based, standard format to
33            communicate reduced one-dimensional small-angle scattering data, ''I(Q)'', between users
34            of our facilities. Our goal has been to define such a format that leaves the data file
35            instantly human-readable, editable in the simplest of editors, and importable by simple
36            text import filters in programs that need not recognise advanced structure in the file
37            nor require advanced programming interfaces. The file should contain both the primary
38            data of ''I(Q)'' and also any other descriptive information (metadata) about the sample,
39            measurement, instrument, processing, or analysis steps. </para>
40        <para>The cansas1d/1.0 standard meets the objectives for a 1D standard, incorporating
41            metadata about the measurement, parameters and results of processing or analysis steps.
42            Even multiple measurements (related or unrelated) may be included within a single XML
43            file. </para>
44        <section xml:id="cansas1d_documentation_Objective-Status">
45            <title>Status</title>
46            <para>Version 1.0 was tagged from the subversion repository on 2009-05-12 as no changes
47                were committed since January 2009. Use this command to checkout the tagged release.
48                <programlisting>svn checkout http://svn.smallangles.net/svn/canSAS/1dwg/tags/v1.0 cansas1dwg-1.0</programlisting></para>
49        </section>
50    </section>
51    <section xml:id="cansas1d_documentation-XMLLayout">
52        <title>General Layout of the XML Data</title>
53        <para>The canSAS 1-D standard for reduced 1-D SAS data is implemented using XML files. A
54            single file can contain SAS data from a single experiment or multiple experiments. All
55            types of relevant data (''I(Q)'', metadata) are described for each experiment. More
56            details are provided below.</para>
57        <section xml:id="cansas1d_documentation-XMLLayout-Overview">
58            <title>Overview</title>
59            <para>The basic elements of the cansas1d/1.0 standard are shown in the following table.
60                After an XML header, the root element of the file is [[cansas1d_SASroot | SASroot]]
61                which contains one or more [[cansas1d_SASentry | SASentry]] elements, each of which
62                describes a single experiment (data set, time-slice, step in a series, new sample,
63                etc.). Details of the [[cansas1d_SASentry | SASentry]] element are also shown in the
64                next figure. Refer to the [[cansas1d_block_diagrams | block diagrams]] for
65                alternative depictions. See <link
66                    xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xml"
67                    >http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xml</link>
68                for an example XML file. Examples, Case Studies, and other background information
69                are below. More discussion can be found on the
70                [[1D_Data_Formats_Working_Group|canSAS 1D Data Formats Working Group]] page and its
71                [[Talk:1D_Data_Formats_Working_Group|discussion]] page. Details about each specific
72                field (XPath string, XML elements and attributes) are described on the
73                [[cansas1d_definition_of_terms]] page. </para>
74            <figure>
75                <title>block diagram of minimum elements required for cansas1d/1.0 standard</title>
76                <mediaobject>
77                    <imageobject>
78                        <imagedata fileref="../graphics/10-minimum.png" scalefit="1" width="200pt"/>
79                    </imageobject>
80                </mediaobject>
81            </figure>
82            <itemizedlist>
83                <listitem>
84                    <para> SASroot: the root element of the file (after the XML header) </para>
85                </listitem>
86                <listitem>
87                    <para> SASentry: describes a single experiment (data set, time-slice, step in a
88                        series, new sample, etc.) </para>
89                </listitem>
90                <listitem>
91                    <para> block diagrams </para>
92                </listitem>
93                <listitem>
94                    <para> cansas1d.xml example XML file </para>
95                </listitem>
96                <listitem>
97                    <para> discussion of this format: basic more </para>
98                </listitem>
99                <listitem>
100                    <para> Seek outside help for XML </para>
101                </listitem>
102                <listitem>
103                    <para> Definition of terms: Details about each specific field (XPath string, XML
104                        elements and attributes) </para>
105                </listitem>
106            </itemizedlist>
107            <section xml:id="cansas1d_documentation-Basic_elements">
108                <title>Basic elements of the cansas1d/1.0 standard</title>
109                <para>
110                    <table frame="all">
111                        <title>Basic elements of the CanSAS 1-D standard</title>
112                        <tgroup cols="2">
113                            <colspec colname="c1" colnum="1" colwidth="2*"/>
114                            <colspec colname="c2" colnum="2" colwidth="6*"/>
115                            <thead>
116                                <row>
117                                    <entry>Element</entry>
118                                    <entry>Description</entry>
119                                </row>
120                            </thead>
121                            <tbody>
122                                <row>
123                                    <entry>XML Header</entry>
124                                    <entry>descriptive info required at the start of every XML
125                                        file</entry>
126                                </row>
127                                <row>
128                                    <entry>
129                                        <emphasis role="bold">
130                                            <code>SASroot</code>
131                                        </emphasis>
132                                    </entry>
133                                    <entry>root element of XML file</entry>
134                                </row>
135                                <row>
136                                    <entry>
137                                        <emphasis role="bold">
138                                            <code>&#160;SASentry</code>
139                                        </emphasis>
140                                    </entry>
141                                    <entry>data set, time-slice, step in a series, new sample,
142                                        etc.</entry>
143                                </row>
144                                <row>
145                                    <entry>
146                                        <emphasis role="bold">
147                                            <code>&#160;&#160;Title</code>
148                                        </emphasis>
149                                    </entry>
150                                    <entry>for this particular SASentry</entry>
151                                </row>
152                                <row>
153                                    <entry>
154                                        <emphasis role="bold">
155                                            <code>&#160;&#160;Run</code>
156                                        </emphasis>
157                                    </entry>
158                                    <entry>run number or ID number of experiment</entry>
159                                </row>
160                                <row>
161                                    <entry>
162                                        <emphasis role="bold">
163                                            <code>&#160;&#160;{any}</code>
164                                        </emphasis>
165                                    </entry>
166                                    <entry>any non-cansas1d/1.0 element can be used at this
167                                        point</entry>
168                                </row>
169                                <row>
170                                    <entry>
171                                        <emphasis role="bold">
172                                            <code>&#160;&#160;SASdata</code>
173                                        </emphasis>
174                                    </entry>
175                                    <entry>this is where the reduced 1-D SAS data is stored</entry>
176                                </row>
177                                <row>
178                                    <entry>
179                                        <emphasis role="bold">
180                                            <code>&#160;&#160;&#160;Idata</code>
181                                        </emphasis>
182                                    </entry>
183                                    <entry>a single data point in the dataset</entry>
184                                </row>
185                                <row>
186                                    <entry>
187                                        <emphasis role="bold">
188                                            <code>&#160;&#160;{any}</code>
189                                        </emphasis>
190                                    </entry>
191                                    <entry>any non-cansas1d/1.0 element can be used at this
192                                        point</entry>
193                                </row>
194                                <row>
195                                    <entry>
196                                        <emphasis role="bold">
197                                            <code>&#160;&#160;SASsample</code>
198                                        </emphasis>
199                                    </entry>
200                                    <entry>description of the sample</entry>
201                                </row>
202                                <row>
203                                    <entry>
204                                        <emphasis role="bold">
205                                            <code>&#160;&#160;SASinstrument</code>
206                                        </emphasis>
207                                    </entry>
208                                    <entry>description of the instrument</entry>
209                                </row>
210                                <row>
211                                    <entry>
212                                        <emphasis role="bold">
213                                            <code>&#160;&#160;&#160;SASsource</code>
214                                        </emphasis>
215                                    </entry>
216                                    <entry>description of the source</entry>
217                                </row>
218                                <row>
219                                    <entry>
220                                        <emphasis role="bold">
221                                            <code>&#160;&#160;&#160;SAScollimation</code>
222                                        </emphasis>
223                                    </entry>
224                                    <entry>description of the collimation</entry>
225                                </row>
226                                <row>
227                                    <entry>
228                                        <emphasis role="bold">
229                                            <code>&#160;&#160;&#160;SASdetector</code>
230                                        </emphasis>
231                                    </entry>
232                                    <entry>description of the detector</entry>
233                                </row>
234                                <row>
235                                    <entry>
236                                        <emphasis role="bold">
237                                            <code>&#160;&#160;SASprocess</code>
238                                        </emphasis>
239                                    </entry>
240                                    <entry>for each processing or analysis step</entry>
241                                </row>
242                                <row>
243                                    <entry>
244                                        <emphasis role="bold">
245                                            <code>&#160;&#160;SASnote</code>
246                                        </emphasis>
247                                    </entry>
248                                    <entry>anything at all</entry>
249                                </row>
250                            </tbody>
251                        </tgroup>
252                    </table>
253                </para>
254            </section>
255            <section xml:id="cansas1d_documentation-required_header">
256                <title>Required XML file header</title>
257                <programlisting>
258&lt;?xml version="1.0"?>
259&lt;?xml-stylesheet type="text/xsl" href="cansasxml-html.xsl" ?>
260&lt;SASroot version="1.0"
261    xmlns="cansas1d/1.0"
262    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
263    xsi:schemaLocation="cansas1d/1.0
264    http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd"></programlisting>
265            </section>
266        </section>
267        <section xml:id="cansas1d_documentation-rules">
268            <title>Rules</title>
269            <orderedlist>
270                <listitem>
271                    <para> canSAS1d/1.0 XML data files will adhere to the standard if they can
272                        successfully [[cansas1d_documentation#Validation_of_XML_against_the_Schema |
273                        validate]] against the established XML Schema
274                        <link xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd"
275                            >cansas1d.xsd</link></para>
276                </listitem>
277                <listitem>
278                    <equation><mathphrase>Q=(4 pi / lambda) sin(theta)</mathphrase></equation>
279                    <para>where lambda is the wavelength of the radiation</para>
280                    <para>and 2theta is the angle through which the detected radiation has been
281                        scattered.</para>
282                    <figure>
283                        <title>definition of Q geometry for small-angle scattering</title>
284                        <mediaobject>
285                            <imageobject>
286                                <imagedata fileref="../graphics/Q-geometry.jpg" scalefit="1"
287                                    width="200pt"/></imageobject>
288                        </mediaobject>
289                    </figure>
290                </listitem>
291                <listitem>
292                    <para> units to be given in standard SI abbreviations (eg, m, cm, mm, nm, K)
293                        with the following exceptions: </para>
294                    <orderedlist numeration="loweralpha">
295                        <listitem>
296                            <para>um=micrometres</para>
297                        </listitem>
298                        <listitem>
299                            <para>C=celsius</para>
300                        </listitem>
301                        <listitem>
302                            <para>A=Angstroms</para>
303                        </listitem>
304                        <listitem>
305                            <para>percent=%.</para>
306                        </listitem>
307                        <listitem>
308                            <para>fraction</para>
309                        </listitem>
310                        <listitem>
311                            <para>a.u.=arbitrary units</para>
312                        </listitem>
313                        <listitem>
314                            <para>none=no units are relevant (such as dimensionless)</para>
315                        </listitem>
316                    </orderedlist>
317                </listitem>
318                <listitem>
319                    <para> where reciprocal units need to be quoted the format shall be
320                        "1/abbreviation"</para>
321                </listitem>
322                <listitem>
323                    <para> when raised to a power, use similar to "A^3" or "1/m^4" (and not "A3" or
324                        "m-4")</para>
325                </listitem>
326                <listitem>
327                    <para> axes: </para>
328                    <orderedlist numeration="loweralpha">
329                        <listitem>
330                            <para>z is along the flight path (positive value in the direction of the
331                                detector)</para>
332                        </listitem>
333                        <listitem>
334                            <para>x is orthogonal to z in the horizontal plane (positive values
335                                increase to the right when viewed towards the incoming
336                                radiation)</para>
337                        </listitem>
338                        <listitem>
339                            <para>y is orthogonal to z and x in the vertical plane (positive values
340                                increase upwards)</para>
341                        </listitem>
342                        <listitem>
343                            <figure>
344                                <title>definition of translation and orientation geometry as viewed
345                                    from the detector towards the source</title>
346                                <para>
347                                    <table>
348                                        <title/>
349                                        <tgroup cols="2">
350                                            <tbody>
351                                                <row>
352                                                  <entry>
353                                                  <mediaobject>
354                                                  <imageobject>
355                                                  <imagedata
356                                                  fileref="../graphics/translation-orientation-geometry.jpg"
357                                                  width="200pt" scalefit="1"/>
358                                                  </imageobject>
359                                                  <caption>
360                                                  <para>as viewed from source</para>
361                                                  </caption>
362                                                  </mediaobject>
363                                                  </entry>
364                                                  <entry>
365                                                  <mediaobject>
366                                                  <imageobject>
367                                                  <imagedata
368                                                  fileref="../graphics/translation-orientation-geometry-2.jpg"
369                                                  width="200pt" scalefit="1"/>
370                                                  </imageobject>
371                                                  <caption>
372                                                  <para>as viewed from detector</para>
373                                                  </caption>
374                                                  </mediaobject>
375                                                  </entry>
376                                                </row>
377                                            </tbody>
378                                        </tgroup>
379                                    </table>
380                                </para>
381                            </figure>
382                        </listitem>
383                    </orderedlist>
384                </listitem>
385                <listitem>
386                    <para>orientation (angles) describes one-axis rotations (rotations about
387                        multiple axes require more information): </para>
388                    <orderedlist numeration="loweralpha">
389                        <listitem>
390                            <para>roll is about z</para>
391                        </listitem>
392                        <listitem>
393                            <para>pitch is about x</para>
394                        </listitem>
395                        <listitem>
396                            <para>yaw is about y</para>
397                        </listitem>
398                    </orderedlist>
399                </listitem>
400                <listitem>
401                    <para> Unicode characters MUST NOT be used</para>
402                </listitem>
403                <listitem>
404                    <para> Binary data is not supported</para>
405                </listitem>
406            </orderedlist>
407            <para>
408            </para>
409        </section>
410        <section xml:id="cansas1d_documentation-geometry_compatibility">
411            <title>Compatibility of Geometry Definitions</title>
412            <para> Note: translation and orientation geometry used by canSAS are consistent with: </para>
413            <itemizedlist>
414                <listitem>
415                    <para>http://en.wikipedia.org/wiki/Cartesian_coordinate_system</para>
416                </listitem>
417                <listitem>
418                    <para>http://en.wikipedia.org/wiki/Right-hand_rule</para>
419                </listitem>
420                <listitem>
421                    <para>http://www.nexusformat.org/Coordinate_Systems</para>
422                </listitem>
423                <listitem>
424                    <para>http://mcstas.risoe.dk/documentation/tutorial/node6.html</para>
425                </listitem>
426                <listitem>
427                    <para>http://webhost5.nts.jhu.edu/reza/book/kinematics/kinematics.htm</para>
428                </listitem>
429            </itemizedlist>
430            <para>The translation and orientation geometry definitions used here are different than
431                those used by <link xlink:href="http://www.nanotech.wisc.edu/shadow"><emphasis
432                        role="bold">SHADOW</emphasis></link> (http://www.nanotech.wisc.edu/shadow)
433                where the <emphasis role="italic">y</emphasis> and <emphasis role="italic"
434                    >z</emphasis> axes are swapped and the direction of <emphasis role="italic"
435                    >x</emphasis> is changed.</para>
436            <note>
437                <para>How does this relate to <emphasis>McStas</emphasis> conventions?</para>
438            </note>
439        </section>
440        <section xml:id="cansas1d_documentation-converting_into_XML">
441            <title>Converting data into the XML format</title>
442            <para>A WWW form ([http://www.smallangles.net/canSAS/xmlWriter/ canSAS/xmlWriter]) is
443                available to translate three-column ASCII text data into the canSAS1d/1.0 XML
444                format. This form will help you in creating an XML file with all the required
445                elements in the correct places. The form requests the SAS data of Q, I, and Idev
446                (defined elsewhere on this page) and some basic metadata (title, run, sample info,
447                ...). Press the &lt;nowiki>Submit&lt;/nowiki> button and you will receive a nicely
448                formatted WWW page with the SAS data. If you then choose "View page source" (from
449                one of your browser menus), you will see the raw XML of the canSAS1d/1.0 XML format
450                and you can copy/paste this into an XML file. </para>
451            <para>The SAS data that you paste into the form box is likely to be copied directly from
452                a 3-column ASCII file from a text editor. Line breaks are OK, they will be treated
453                as white-space as will tabs and commas. Do not be concerned that the data looks
454                awful in the form entry box, just check the result to see that it comes out
455                OK.</para>
456        </section>
457    </section>
458    <section xml:id="cansas1d_documentation-Documentation-Definitions">
459        <title>Documentation and Definitions</title>
460        <itemizedlist>
461            <listitem>
462                <para><emphasis role="bold">Documentation</emphasis>: [[cansas1d_documentation]]
463                    (this page)</para>
464            </listitem>
465            <listitem>
466                <para><emphasis role="bold">Definitions</emphasis>:
467                    [[cansas1d_definition_of_terms]]</para>
468            </listitem>
469            <listitem>
470                <para><emphasis role="bold">Block diagrams</emphasis>:
471                    [[cansas1d_block_diagrams]]</para>
472            </listitem>
473        </itemizedlist>
474        <section xml:id="cansas1d_documentation-XML_Schema">
475            <title>XML Schema</title>
476            <para> The [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd
477                cansas1d.xsd] [http://www.w3schools.com/xsd XML Schema] defines the rules for the
478                XML file format
479                ([http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd TRAC],
480                [http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd SVN]) and is used to
481                validate any XML file for adherence to the format. </para>
482        </section>
483        <section xml:id="cansas1d_documentation-XML_Stylesheets">
484            <title>XML Stylesheets</title>
485            <itemizedlist>
486                <listitem>
487                    <para>'''cansasxml-html.xsl''': [http://www.w3schools.com/xsl/ XSLT stylesheets]
488                        can be used to extract metadata or to convert into another file format. The
489                        default canSAS stylesheet
490                        [[http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansasxml-html.xsl
491                        cansasxml-html.xsl]] should be copied into each folder with canSAS XML data
492                        file(s). It can be used to display the data in a supporting WWW browser
493                        (such as Firefox or Internet Explorer) or to import into Microsoft Excel
494                        (with the added XML support in Excel). (See the excellent write-up by Steve
495                        King, ISIS, at
496                        http://www.isis.rl.ac.uk/archive/LargeScale/LOQ/xml/cansas_xml_format.pdf
497                        for an example.) By default, MS Windows binds '''*.xml''' files to start
498                        Internet Explorer. Double-clicking on a canSAS XML data file with the
499                        [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansasxml-html.xsl
500                        '''cansasxml-html.xsl'''] stylesheet in the same directory will produce a
501                        WWW page with the SAS data and selected metadata.</para>
502                </listitem>
503                <listitem>
504                    <para>Suggestions for support software that writes canSAS1d/1.0 XML data
505                        files:</para>
506                    <itemizedlist>
507                        <listitem>
508                            <para>be sure to update to the latest SVN repository revision (command:
509                                    <code>svn update</code>) </para>
510                        </listitem>
511                        <listitem>
512                            <para>check the output directory to see if it contains the default XSLT
513                                file.</para>
514                        </listitem>
515                        <listitem>
516                            <para>copy the latest XSLT file to the output directory if
517                                either:</para>
518                            <itemizedlist>
519                                <listitem>
520                                    <para>the output directory contains an older revision</para>
521                                </listitem>
522                                <listitem>
523                                    <para>the output directory does not have the default XSLT
524                                        file</para>
525                                </listitem>
526                            </itemizedlist>
527                        </listitem>
528                        <listitem>
529                            <para>The most recent XSLT file can be identified by examining the file
530                                for the '''$ Revision: ''' string. For example: <code>#
531                                    &#36;Revision: 111 $</code> is version 111. </para>
532                        </listitem>
533                    </itemizedlist>
534                </listitem>
535            </itemizedlist>
536        </section>
537        <section xml:id="cansas1d_documentation-examples">
538            <title>Examples and Case Studies</title>
539            <itemizedlist>
540                <listitem>
541                    <para>[http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xml
542                        cansas1d.xml] basic example: Note that, for clarity, only one row of data is
543                        shown. This is probably a very good example to use as a starting point for
544                        creating XML files with a text editor.</para>
545                </listitem>
546                <listitem>
547                    <para>[http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/bimodal-test1.xml
548                        bimodal-test1.xml]: Simulated SAS data to test size distribution calculation
549                        routines.</para>
550                </listitem>
551                <listitem>
552                    <para>[[Glassy_Carbon_Round_Robin | Glassy Carbon Round Robin]]: Glassy carbon
553                        samples measured at several facilities worldwide.</para>
554                </listitem>
555                <listitem>
556                    <para>[[cansas1d_casestudy_collagen | dry chick collagen]]: illustrates the
557                        minimum information necessary to meet the requirements of the standard
558                        format</para>
559                </listitem>
560                <listitem>
561                    <para>[[cansas1d_casestudy_af1410 | AF1410 steel]]: SANS study using magnetic
562                        contrast variation (with multiple samples and multiple data sets for each
563                        sample), the files can be viewed from TRAC (no description yet):
564                        [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/examples/af1410/
565                        http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/examples/af1410/]</para>
566                </listitem>
567                <listitem>
568                    <para>[http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d-template.xml
569                        cansas1d-template.xml]: This is used to test all the rules in the XML
570                        Schema. This is probably not a very good example to use as a starting point
571                        for creating XML files with a text editor since it tests many of the
572                        special-case rules.</para>
573                </listitem>
574            </itemizedlist>
575            <section xml:id="cansas1d_documentation-examples-multiple_experiments">
576                <title>XML layout for multiple experiments</title>
577                <para>Each experiment is described with a single '''SASentry''' element. The
578                    fragment below shows how multiple experiments can be included in a single XML
579                    file. Full examples of canSAS XML files with multiple experiments
580                    include:</para>
581                <itemizedlist>
582                    <listitem>
583                        <para> ISIS LOQ SANS instrument: <link
584                                xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/W1W2.XML"
585                                >http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/W1W2.XML</link>
586                        </para>
587                    </listitem>
588                    <listitem>
589                        <para> AF1410 steel SANS contrast variation study from NIST: <link
590                                xlink:href="http://svn.smallangles.net/svn/canSAS/1dwg/trunk/examples/af1410/cs_af1410.xml"
591                                >
592                                http://svn.smallangles.net/svn/canSAS/1dwg/trunk/examples/af1410/cs_af1410.xml
593                            </link>
594                        </para>
595                    </listitem>
596                </itemizedlist>
597                <para>Here is a brief sketch of how a file would be arranged with multiple SASentry
598                    elements and multiple SASdata elements.
599                    <programlisting>
600&lt;?xml version="1.0"?>
601&lt;?xml-stylesheet type="text/xsl" href="cansasxml-html.xsl" ?>
602&lt;SASroot version="1.0"
603      xmlns="cansas1d/1.0"
604      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
605      xsi:schemaLocation="cansas1d/1.0 http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd"
606      >
607      &lt;SASentry name="071121.dat#S22">
608            &lt;!-\- contents of the first experiment in the file go here -\->
609      &lt;/SASentry>
610      &lt;SASentry name="example temperature series">
611           &lt;!-\- example with two SAS data sets related to the same sample -\->
612           &lt;Title>title of this series&lt;/Title>
613           &lt;Run name="run1">42-001&lt;/Run>
614           &lt;Run name="run2">42-002&lt;/Run>
615           &lt;SASdata name="run1">
616                &lt;!-\- data from 42-001 run comes here -\->
617           &lt;/SASdata>
618           &lt;SASdata name="run2">
619                &lt;!-\- data from 42-002 run comes here -\->
620           &lt;/SASdata>
621           &lt;!-\- other elements come here for this entry -\->
622      &lt;/SASentry>
623      &lt;SASentry name="other sample">
624           &lt;!-\- any number of additional experiments can be included, as desired -\->
625           &lt;!-\- SASentry elements in the same XML file do not have to be related -\->
626      &lt;/SASentry>
627&lt;/SASroot>
628                    </programlisting></para>
629            </section>
630        </section>
631        <section xml:id="cansas1d_documentation-Foreign_Elements">
632            <title>Foreign Elements</title>
633            <para> To allow for inclusion of elements that are not defined by the cansas1d.xsd XML
634                Schema, XML ''foreign elements'' are permitted at select locations in the
635                cansas1d/1.0 format. Please refer to the references (and others) [[#Help_for_XML |
636                below]] for deeper discussions on foreign elements. </para>
637            <para> These is one example that demonstrates the use of a foreign namespace: <link
638                    xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/data/Glassy%20Carbon/ISIS/GLASSYC_C4G8G9_withTL.xml"
639                    >http://svn.smallangles.net/trac/canSAS/browser/1dwg/data/Glassy%20Carbon/ISIS/GLASSYC_C4G8G9_withTL.xml</link>
640                This example uses a foreign namespace to record the transmission spectra related to
641                the acquisition of the SANS data at a time-of-flight facility. Look for the
642                    <code>&lt;transmission_spectrum xmlns="urn:transmission:spectrum"></code>
643                element at line 153. The foreign namespace given
644                    (<literal>urn:transmission:spectrum</literal>) becomes the default for just the
645                    <literal>transmission_spectrum</literal> element. </para>
646            <para> Also refer to <link
647                    xlink:href="http://svn.smallangles.net/trac/canSAS/changeset/47">canSAS TRAC
648                    ticket #47</link> for an example of arranging the content in <emphasis
649                    role="bold">SASprocessnote</emphasis> to avoid the use of foreign namespace
650                elements. </para>
651        </section>
652        <section xml:id="cansas1d_documentation-Support_Tools">
653            <title>Support tools for Visualization &amp; Analysis software</title>
654            <para> Support for importing canSAS1d/1.0 files exists for these languages: <note>
655                    <para>Refactor the wiki pages here and link as appropriate.</para>
656                </note></para>
657            <itemizedlist>
658                <listitem>
659                    <para><emphasis role="bold">FORTRAN</emphasis></para>
660                </listitem>
661                <listitem>
662                    <para><emphasis role="bold">IgorPro</emphasis></para>
663                </listitem>
664                <listitem>
665                    <para><emphasis role="bold">Java</emphasis></para>
666                </listitem>
667                <listitem>
668                    <para>
669                        <emphasis role="bold">Microsoft Excel</emphasis> Support for Microsoft Excel
670                        is provided through the default canSAS stylesheet <link
671                            xlink:href="http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansasxml-html.xsl"
672                            >cansasxml-html.xsl</link>. An <link
673                            xlink:href="http://www.isis.rl.ac.uk/archive/LargeScale/LOQ/xml/cansas_xml_format.pdf"
674                            >excellent description</link> of how to import data from the
675                        cansas1d/1.0 format into Excel is available from the <link
676                            xlink:href="http://www.isis.stfc.ac.uk/instruments/loq/loq2470.html"
677                            >ISIS LOQ instrument</link>
678                        (http://www.isis.stfc.ac.uk/instruments/loq/loq2470.html). Also note the
679                            <link
680                            xlink:href="http://www.isis.rl.ac.uk/atchive/LargeScale/LOQ/loq.htm">old
681                            WWW site</link>. (http://www.isis.rl.ac.uk/LargeScale/LOQ/loq.htm) may
682                        still be available. </para>
683                </listitem>
684                <listitem>
685                    <para><emphasis role="bold">PHP</emphasis></para>
686                </listitem>
687                <listitem>
688                    <para><emphasis role="bold">Python</emphasis></para>
689                </listitem>
690                <listitem>
691                    <para><emphasis role="bold">XSLT</emphasis> (useful in a web browser)</para>
692                </listitem>
693            </itemizedlist>
694        </section>
695        <section xml:id="cansas1d_documentation-repositories">
696            <title>Software repositories (for canSAS1d/1.0 standard)</title>
697            <itemizedlist>
698                <listitem>
699                    <para><emphasis role="bold">TRAC</emphasis>: <link
700                            xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/tags/v1.0"
701                            >http://svn.smallangles.net/trac/canSAS/browser/1dwg/tags/v1.0</link></para>
702                </listitem>
703                <listitem>
704                    <para><emphasis role="bold">Subversion</emphasis>: <link
705                            xlink:href="http://svn.smallangles.net/svn/canSAS/1dwg/tags/v1.0"
706                            >http://svn.smallangles.net/svn/canSAS/1dwg/tags/v1.0</link></para>
707                </listitem>
708            </itemizedlist>
709        </section>
710    </section>
711    <section xml:id="cansas1d_documentation-schema_validation">
712        <title>Validation of XML against the Schema</title>
713        <orderedlist>
714            <listitem>
715                <para>open browser to: http://www.xmlvalidation.com/</para>
716            </listitem>
717            <listitem>
718                <para>paste content of candidate XML file (with reference in the header to the XML
719                    Schema as shown above) into the form</para>
720            </listitem>
721            <listitem>
722                <para>press &lt;validate></para>
723            </listitem>
724            <listitem>
725                <para>paste content of
726                    [http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd cansas1d.xsd] XSD
727                    file into form and press &lt;continue validation></para>
728            </listitem>
729            <listitem>
730                <para>check the results</para>
731            </listitem>
732        </orderedlist>
733    </section>
734    <section xml:id="cansas1d_documentation-XML_Help">
735        <title>Help for XML</title>
736        <para>The various references for help on XML have been moved to their own wiki page:
737            [[XmlHelp]] </para>
738        <note>
739            <para>chapter="Other" section="XML Help" xml:id="wiki-XML_Help"</para>
740        </note>
741    </section>
742</chapter>
Note: See TracBrowser for help on using the repository browser.