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

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

more documentation translated, refs #19

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