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

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

make sure the canonical "cansas1d/1.0" is all lowercase in the documentation, refs #19

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