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

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

more documentation; refs #19

  • Property svn:keywords set to Date Revision Author HeadURL Id
File size: 36.3 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">http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xml</link>
67                for an example XML file. Examples, Case Studies, and other background
68                information are below. More discussion can be found on the
69                [[1D_Data_Formats_Working_Group|canSAS 1D Data Formats Working Group]] page and its
70                [[Talk:1D_Data_Formats_Working_Group|discussion]] page. Details about each specific
71                field (XPath string, XML elements and attributes) are described on the
72                [[cansas1d_definition_of_terms]] page. </para>
73            <figure>
74                <title>block diagram of minimum elements required for cansas1d/1.0 standard</title>
75                <mediaobject>
76                    <imageobject>
77                        <imagedata fileref="../graphics/10-minimum.png" scalefit="1" width="200px"/>
78                    </imageobject>
79                </mediaobject>
80            </figure>
81            <itemizedlist>
82                <listitem>
83                    <para> SASroot: the root element of the file (after the XML header) </para>
84                </listitem>
85                <listitem>
86                    <para> SASentry: describes a single experiment (data set, time-slice, step in a
87                        series, new sample, etc.) </para>
88                </listitem>
89                <listitem>
90                    <para> block diagrams </para>
91                </listitem>
92                <listitem>
93                    <para> cansas1d.xml example XML file </para>
94                </listitem>
95                <listitem>
96                    <para> discussion of this format: basic more </para>
97                </listitem>
98                <listitem>
99                    <para> Seek outside help for XML </para>
100                </listitem>
101                <listitem>
102                    <para> Definition of terms: Details about each specific field (XPath string, XML
103                        elements and attributes) </para>
104                </listitem>
105            </itemizedlist>
106            <section xml:id="cansas1d_documentation-Basic_elements">
107                <title>Basic elements of the cansas1d/1.0 standard</title>
108                <para>
109                    <table frame="all">
110                        <title>Basic elements of the CanSAS 1-D standard</title>
111                        <tgroup cols="2">
112                            <colspec colname="c1" colnum="1"/>
113                            <colspec colname="c2" colnum="2"/>
114                            <thead>
115                                <row>
116                                    <entry>Element</entry>
117                                    <entry>Description</entry>
118                                </row>
119                            </thead>
120                            <tbody>
121                                <row>
122                                    <entry>XML Header</entry>
123                                    <entry>descriptive info required at the start of every XML
124                                        file</entry>
125                                </row>
126                                <row>
127                                    <entry>SASroot</entry>
128                                    <entry>root element of XML file</entry>
129                                </row>
130                                <row>
131                                    <entry>SASentry</entry>
132                                    <entry>data set, time-slice, step in a series, new sample,
133                                        etc.</entry>
134                                </row>
135                                <row>
136                                    <entry>:::Title</entry>
137                                    <entry>for this particular SASentry</entry>
138                                </row>
139                                <row>
140                                    <entry>:::Run</entry>
141                                    <entry>run number or ID number of experiment</entry>
142                                </row>
143                                <row>
144                                    <entry>:::[[cansas1d_any | {any}]]</entry>
145                                    <entry>any non-cansas1d/1.0 element can be used at this
146                                        point</entry>
147                                </row>
148                                <row>
149                                    <entry>:::[[cansas1d_SASdata | SASdata]]</entry>
150                                    <entry>this is where the reduced 1-D SAS data is stored</entry>
151                                </row>
152                                <row>
153                                    <entry>::::[[cansas1d_SASdata | Idata]]</entry>
154                                    <entry>a single data point in the dataset</entry>
155                                </row>
156                                <row>
157                                    <entry>:::[[cansas1d_any | {any}]]</entry>
158                                    <entry>any non-cansas1d/1.0 element can be used at this
159                                        point</entry>
160                                </row>
161                                <row>
162                                    <entry>:::[[cansas1d_SASsample | SASsample]]</entry>
163                                    <entry>description of the sample</entry>
164                                </row>
165                                <row>
166                                    <entry>:::[[cansas1d_SASinstrument | SASinstrument]]</entry>
167                                    <entry>description of the instrument</entry>
168                                </row>
169                                <row>
170                                    <entry>::::[[cansas1d_SASsource | SASsource]]</entry>
171                                    <entry>description of the source</entry>
172                                </row>
173                                <row>
174                                    <entry>::::[[cansas1d_SAScollimation | SAScollimation]]</entry>
175                                    <entry>description of the collimation</entry>
176                                </row>
177                                <row>
178                                    <entry>::::[[cansas1d_SASdetector | SASdetector]]</entry>
179                                    <entry>description of the detector</entry>
180                                </row>
181                                <row>
182                                    <entry>:::[[cansas1d_SASprocess | SASprocess]]</entry>
183                                    <entry>for each processing or analysis step</entry>
184                                </row>
185                                <row>
186                                    <entry>:::[[cansas1d_SASnote | SASnote]]</entry>
187                                    <entry>anything at all</entry>
188                                </row>
189                            </tbody>
190                        </tgroup>
191                    </table>
192                </para>
193            </section>
194            <section xml:id="cansas1d_documentation-required_header">
195                <title>Required XML file header</title>
196                <programlisting>
197&lt;?xml version="1.0"?>
198&lt;?xml-stylesheet type="text/xsl" href="cansasxml-html.xsl" ?>
199&lt;SASroot version="1.0"
200    xmlns="cansas1d/1.0"
201    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
202    xsi:schemaLocation="cansas1d/1.0
203        http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd"
204    >
205                </programlisting>
206            </section>
207        </section>
208        <section xml:id="cansas1d_documentation-rules">
209            <title>Rules</title>
210            <orderedlist>
211                <listitem>
212                    <para> canSAS1d/1.0 XML data files will adhere to the standard if they can
213                        successfully [[cansas1d_documentation#Validation_of_XML_against_the_Schema |
214                        validate]] against the established XML Schema
215                        ([http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd
216                        cansas1d.xsd])</para>
217                </listitem>
218                <listitem>
219                    <equation><mathphrase>Q=(4 pi / lambda) sin(theta)</mathphrase></equation>
220                    <para>where lambda is the wavelength of the radiation</para>
221                    <para>and 2theta is the angle through which the detected radiation has been
222                        scattered.</para>
223                    <figure>
224                        <title>definition of Q geometry for small-angle scattering</title>
225                        <mediaobject>
226                            <imageobject>
227                                <imagedata fileref="../graphics/Q-geometry.jpg" 
228                                    scalefit="1" width="200px"
229                                /></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                                <mediaobject>
289                                    <imageobject>
290                                        <imagedata
291                                            fileref="../graphics/translation-orientation-geometry.jpg"
292                                            scalefit="1" width="200px"/></imageobject>
293                                </mediaobject>
294                            </figure>
295                            <figure>
296                                <title>definition of translation and orientation geometry as viewed
297                                    from the source towards the detector</title>
298                                <mediaobject>
299                                    <imageobject>
300                                        <imagedata
301                                            fileref="../graphics/translation-orientation-geometry-2.jpg"
302                                            scalefit="1" width="200px"/></imageobject>
303                                </mediaobject>
304                            </figure>
305                        </listitem>
306                    </orderedlist>
307                </listitem>
308                <listitem>
309                    <para>orientation (angles) describes one-axis rotations (rotations about
310                        multiple axes require more information): </para>
311                    <orderedlist numeration="loweralpha">
312                        <listitem>
313                            <para>roll is about z</para>
314                        </listitem>
315                        <listitem>
316                            <para>pitch is about x</para>
317                        </listitem>
318                        <listitem>
319                            <para>yaw is about y</para>
320                        </listitem>
321                    </orderedlist>
322                </listitem>
323                <listitem>
324                    <para> Unicode characters MUST NOT be used</para>
325                </listitem>
326                <listitem>
327                    <para> Binary data is not supported</para>
328                </listitem>
329            </orderedlist>
330            <para>
331            </para>
332        </section>
333        <section xml:id="cansas1d_documentation-geometry_compatibility">
334            <title>Compatibility of Geometry Definitions</title>
335            <para> Note: translation and orientation geometry used by canSAS are consistent with: </para>
336            <itemizedlist>
337                <listitem>
338                    <para>http://en.wikipedia.org/wiki/Cartesian_coordinate_system</para>
339                </listitem>
340                <listitem>
341                    <para>http://en.wikipedia.org/wiki/Right-hand_rule</para>
342                </listitem>
343                <listitem>
344                    <para>http://www.nexusformat.org/Coordinate_Systems</para>
345                </listitem>
346                <listitem>
347                    <para>http://mcstas.risoe.dk/documentation/tutorial/node6.html</para>
348                </listitem>
349                <listitem>
350                    <para>http://webhost5.nts.jhu.edu/reza/book/kinematics/kinematics.htm</para>
351                </listitem>
352            </itemizedlist>
353            <para>The translation and orientation geometry definitions used here are different than
354                those used by '''SHADOW''' (http://www.nanotech.wisc.edu/shadow) where the ''y'' and
355                ''z'' axes are swapped and the direction of ''x'' is changed.</para>
356        </section>
357        <section xml:id="cansas1d_documentation-converting_into_XML">
358            <title>Converting data into the XML format</title>
359            <para>A WWW form ([http://www.smallangles.net/canSAS/xmlWriter/ canSAS/xmlWriter]) is
360                available to translate three-column ASCII text data into the canSAS1d/1.0 XML
361                format. This form will help you in creating an XML file with all the required
362                elements in the correct places. The form requests the SAS data of Q, I, and Idev
363                (defined elsewhere on this page) and some basic metadata (title, run, sample info,
364                ...). Press the &lt;nowiki>Submit&lt;/nowiki> button and you will receive a nicely
365                formatted WWW page with the SAS data. If you then choose "View page source" (from
366                one of your browser menus), you will see the raw XML of the canSAS1d/1.0 XML format
367                and you can copy/paste this into an XML file. </para>
368            <para>The SAS data that you paste into the form box is likely to be copied directly from
369                a 3-column ASCII file from a text editor. Line breaks are OK, they will be treated
370                as white-space as will tabs and commas. Do not be concerned that the data looks
371                awful in the form entry box, just check the result to see that it comes out
372                OK.</para>
373        </section>
374    </section>
375    <section xml:id="cansas1d_documentation-Documentation-Definitions">
376        <title>Documentation and Definitions</title>
377        <itemizedlist>
378            <listitem>
379                <para><emphasis role="bold">Documentation</emphasis>: [[cansas1d_documentation]]
380                    (this page)</para>
381            </listitem>
382            <listitem>
383                <para><emphasis role="bold">Definitions</emphasis>:
384                    [[cansas1d_definition_of_terms]]</para>
385            </listitem>
386            <listitem>
387                <para><emphasis role="bold">Block diagrams</emphasis>:
388                    [[cansas1d_block_diagrams]]</para>
389            </listitem>
390        </itemizedlist>
391        <section xml:id="cansas1d_documentation-XML_Schema">
392            <title>XML Schema</title>
393            <para> The [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd
394                cansas1d.xsd] [http://www.w3schools.com/xsd XML Schema] defines the rules for the
395                XML file format
396                ([http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd TRAC],
397                [http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd SVN]) and is used to
398                validate any XML file for adherence to the format. </para>
399        </section>
400        <section xml:id="cansas1d_documentation-XML_Stylesheets">
401            <title>XML Stylesheets</title>
402            <itemizedlist>
403                <listitem>
404                    <para>'''cansasxml-html.xsl''': [http://www.w3schools.com/xsl/ XSLT stylesheets]
405                        can be used to extract metadata or to convert into another file format. The
406                        default canSAS stylesheet
407                        [[http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansasxml-html.xsl
408                        cansasxml-html.xsl]] should be copied into each folder with canSAS XML data
409                        file(s). It can be used to display the data in a supporting WWW browser
410                        (such as Firefox or Internet Explorer) or to import into Microsoft Excel
411                        (with the added XML support in Excel). (See the excellent write-up by Steve
412                        King, ISIS, at
413                        http://www.isis.rl.ac.uk/archive/LargeScale/LOQ/xml/cansas_xml_format.pdf
414                        for an example.) By default, MS Windows binds '''*.xml''' files to start
415                        Internet Explorer. Double-clicking on a canSAS XML data file with the
416                        [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansasxml-html.xsl
417                        '''cansasxml-html.xsl'''] stylesheet in the same directory will produce a
418                        WWW page with the SAS data and selected metadata.</para>
419                </listitem>
420                <listitem>
421                    <para>Suggestions for support software that writes canSAS1d/1.0 XML data
422                        files:</para>
423                    <itemizedlist>
424                        <listitem>
425                            <para>be sure to update to the latest SVN repository revision (command:
426                                    <code>svn update</code>) </para>
427                        </listitem>
428                        <listitem>
429                            <para>check the output directory to see if it contains the default XSLT
430                                file.</para>
431                        </listitem>
432                        <listitem>
433                            <para>copy the latest XSLT file to the output directory if
434                                either:</para>
435                            <itemizedlist>
436                                <listitem>
437                                    <para>the output directory contains an older revision</para>
438                                </listitem>
439                                <listitem>
440                                    <para>the output directory does not have the default XSLT
441                                        file</para>
442                                </listitem>
443                            </itemizedlist>
444                        </listitem>
445                        <listitem>
446                            <para>The most recent XSLT file can be identified by examining the file
447                                for the '''$ Revision: ''' string. For example:
448                                <programlisting># \$Revision$</programlisting> is version 66
449                                (updated 2009-01-12). </para>
450                        </listitem>
451                    </itemizedlist>
452                </listitem>
453            </itemizedlist>
454        </section>
455        <section xml:id="cansas1d_documentation-examples">
456            <title>Examples and Case Studies</title>
457            <itemizedlist>
458                <listitem>
459                    <para>[http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xml
460                        cansas1d.xml] basic example: Note that, for clarity, only one row of data is
461                        shown. This is probably a very good example to use as a starting point for
462                        creating XML files with a text editor.</para>
463                </listitem>
464                <listitem>
465                    <para>[http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/bimodal-test1.xml
466                        bimodal-test1.xml]: Simulated SAS data to test size distribution calculation
467                        routines.</para>
468                </listitem>
469                <listitem>
470                    <para>[[Glassy_Carbon_Round_Robin | Glassy Carbon Round Robin]]: Glassy carbon
471                        samples measured at several facilities worldwide.</para>
472                </listitem>
473                <listitem>
474                    <para>[[cansas1d_casestudy_collagen | dry chick collagen]]: illustrates the
475                        minimum information necessary to meet the requirements of the standard
476                        format</para>
477                </listitem>
478                <listitem>
479                    <para>[[cansas1d_casestudy_af1410 | AF1410 steel]]: SANS study using magnetic
480                        contrast variation (with multiple samples and multiple data sets for each
481                        sample), the files can be viewed from TRAC (no description yet):
482                        [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/examples/af1410/
483                        http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/examples/af1410/]</para>
484                </listitem>
485                <listitem>
486                    <para>[http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d-template.xml
487                        cansas1d-template.xml]: This is used to test all the rules in the XML
488                        Schema. This is probably not a very good example to use as a starting point
489                        for creating XML files with a text editor since it tests many of the
490                        special-case rules.</para>
491                </listitem>
492            </itemizedlist>
493            <section xml:id="cansas1d_documentation-examples-multiple_experiments">
494                <title>XML layout for multiple experiments</title>
495                <para>Each experiment is described with a single '''SASentry''' element. The
496                    fragment below shows how multiple experiments can be included in a single XML
497                    file. Full examples of canSAS XML files with multiple experiments
498                    include:</para>
499                <itemizedlist>
500                    <listitem>
501                        <para>[http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/W1W2.XML
502                            ISIS LOQ SANS instrument]</para>
503                    </listitem>
504                    <listitem>
505                        <para>[http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cs_af1410.xml
506                            NIST SANS data]</para>
507                    </listitem>
508                </itemizedlist>
509                <para>Here is a brief sketch of how a file would be arranged with multiple SASentry
510                    elements and multiple SASdata elements.
511                    <programlisting>
512&lt;?xml version="1.0"?>
513&lt;?xml-stylesheet type="text/xsl" href="cansasxml-html.xsl" ?>
514&lt;SASroot version="1.0"
515   xmlns="cansas1d/1.0"
516   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
517   xsi:schemaLocation="cansas1d/1.0 http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd"
518   >
519   &lt;SASentry name="071121.dat#S22">
520     &lt;!-\- contents of the first experiment in the file go here -\->
521   &lt;/SASentry>
522   &lt;SASentry name="example temperature series">
523     &lt;!-\- example with two SAS data sets related to the same sample -\->
524     &lt;Title>title of this series&lt;/Title>
525     &lt;Run name="run1">42-001&lt;/Run>
526     &lt;Run name="run2">42-002&lt;/Run>
527     &lt;SASdata name="run1">
528       &lt;!-\- data from 42-001 run comes here -\->
529     &lt;/SASdata>
530     &lt;SASdata name="run2">
531       &lt;!-\- data from 42-002 run comes here -\->
532     &lt;/SASdata>
533     &lt;!-\- other elements come here for this entry -\->
534   &lt;/SASentry>
535   &lt;SASentry name="other sample">
536     &lt;!-\- any number of additional experiments can be included, as desired -\->
537     &lt;!-\- SASentry elements in the same XML file do not have to be related -\->
538   &lt;/SASentry>
539&lt;/SASroot>
540                    </programlisting></para>
541            </section>
542        </section>
543        <section xml:id="cansas1d_documentation-Foreign_Elements">
544            <title>Foreign Elements</title>
545            <para> To allow for inclusion of elements that are not defined by the cansas1d.xsd XML
546                Schema, XML ''foreign elements'' are permitted at select locations in the
547                cansas1d/1.0 format. Please refer to the references (and others) [[#Help_for_XML |
548                below]] for deeper discussions on foreign elements. </para>
549            <para> No examples exist. <note>
550                    <para> 2009-09, PRJ: Actually, the ISIS glassy carbon data is now an example
551                    </para>
552                </note> At present, all examples of canSAS xml files using foreign namespaces have
553                been converted to bring that data into either the '''SASprocessnote''' or
554                '''SASnote''' elements. Refer to the
555                [http://svn.smallangles.net/trac/canSAS/changeset/47 TRAC changes] for an example of
556                arranging the content in '''SASprocessnote''' to avoid the use of foreign namespace
557                elements. </para>
558        </section>
559        <section xml:id="cansas1d_documentation-Support_Tools">
560            <title>Support tools for Visualization &amp; Analysis software</title>
561            <para> Support for importing canSAS1d/1.0 files exists for these languages: <note>
562                    <para>Refactor the wiki pages here and link as appropriate.</para>
563                </note></para>
564            <itemizedlist>
565                <listitem>
566                    <para><emphasis role="bold">FORTRAN</emphasis></para>
567                </listitem>
568                <listitem>
569                    <para><emphasis role="bold">IgorPro</emphasis></para>
570                </listitem>
571                <listitem>
572                    <para><emphasis role="bold">Java</emphasis></para>
573                </listitem>
574                <listitem>
575                    <para>
576                        <emphasis role="bold">Microsoft Excel</emphasis>
577                        Support for Microsoft Excel is provided through the default
578                        canSAS stylesheet
579                        <link 
580                            xlink:href="http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansasxml-html.xsl">cansasxml-html.xsl</link>.
581                        An
582                        <link 
583                            xlink:href="http://www.isis.rl.ac.uk/archive/LargeScale/LOQ/xml/cansas_xml_format.pdf">excellent description</link>
584                        of how to import data from the cansas1d/1.0 format into Excel is available
585                        from the
586                        <link xlink:href="http://www.isis.stfc.ac.uk/instruments/loq/loq2470.html">ISIS LOQ instrument</link>
587                        (http://www.isis.stfc.ac.uk/instruments/loq/loq2470.html).
588                        Also note the
589                        <link 
590                            xlink:href="http://www.isis.rl.ac.uk/atchive/LargeScale/LOQ/loq.htm">old WWW site</link>.
591                        (http://www.isis.rl.ac.uk/LargeScale/LOQ/loq.htm) may still be available.
592                    </para>
593                </listitem>
594                <listitem>
595                    <para><emphasis role="bold">PHP</emphasis></para>
596                </listitem>
597                <listitem>
598                    <para><emphasis role="bold">Python</emphasis></para>
599                </listitem>
600                <listitem>
601                    <para><emphasis role="bold">XSLT</emphasis> (useful in a web browser)</para>
602                </listitem>
603            </itemizedlist>
604        </section>
605        <section xml:id="cansas1d_documentation-repositories">
606            <title>Software repositories (for canSAS1d/1.0 standard)</title>
607            <itemizedlist>
608                <listitem>
609                    <para><emphasis role="bold">TRAC</emphasis>:
610                        <link xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/tags/v1.0">http://svn.smallangles.net/trac/canSAS/browser/1dwg/tags/v1.0</link></para>
611                </listitem>
612                <listitem>
613                    <para><emphasis role="bold">Subversion</emphasis>:
614                        <link xlink:href="http://svn.smallangles.net/svn/canSAS/1dwg/tags/v1.0">http://svn.smallangles.net/svn/canSAS/1dwg/tags/v1.0</link></para>
615                </listitem>
616            </itemizedlist>
617        </section>
618    </section>
619    <section xml:id="cansas1d_documentation-schema_validation">
620        <title>Validation of XML against the Schema</title>
621        <orderedlist>
622            <listitem><para>open browser to:   http://www.xmlvalidation.com/</para></listitem>
623            <listitem><para>paste content of candidate XML file (with reference in the header to the XML Schema as shown above) into the form</para></listitem>
624            <listitem><para>press &lt;validate></para></listitem>
625            <listitem><para>paste content of [http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd cansas1d.xsd] XSD file into form and press &lt;continue validation></para></listitem>
626            <listitem><para>check the results</para></listitem>
627        </orderedlist>
628    </section>
629    <section xml:id="cansas1d_documentation-XML_Help">
630        <title>Help for XML</title>
631        <para>The various references for help on XML have been moved to their own wiki page:
632            [[XmlHelp]] </para>
633        <note><para>chapter="Other" section="XML Help" xml:id="wiki-XML_Help"</para></note>
634    </section>
635</chapter>
Note: See TracBrowser for help on using the repository browser.