source: 1dwg/trunk/doc/src/wiki.xml @ 129

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

more cross-references, formatting, & indices, refs #19

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