add some precision in listfiles documentation page
[scilab.git] / scilab / modules / fileio / help / en_US / listfiles.xml
index 6d12f7d..828603e 100644 (file)
  *
  -->
 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" version="5.0-subset Scilab" xml:lang="en" xml:id="listfiles">
-  <refnamediv>
-    <refname>listfiles</refname>
-    <refpurpose>list of files</refpurpose>
-  </refnamediv>
-  <refsynopsisdiv>
-    <title>Calling Sequence</title>
-    <synopsis>files = listfiles(paths [,flag,flagexpand])</synopsis>
-  </refsynopsisdiv>
-  <refsection>
-    <title>Arguments</title>
-    <variablelist>
-      <varlistentry>
-        <term>paths</term>
-        <listitem>
-          <para>
-            a string matrix giving a set of pathnames (eventually  ended by a pattern built with <literal>*</literal>).
-          </para>
-        </listitem>
-      </varlistentry>
-      <varlistentry>
-        <term>flag, flagexpand</term>
-        <listitem>
-          <para>
-            boolean optional parameters (default value is <constant>%t</constant>).
-          </para>
-        </listitem>
-      </varlistentry>
-      <varlistentry>
-        <term>files</term>
-        <listitem>
-          <para>a string matrix.</para>
-        </listitem>
-      </varlistentry>
-    </variablelist>
-  </refsection>
-  <refsection>
-    <title>Description</title>
-    <para>
-      <function>listfiles</function> can be used to list the files which match
-      the patterns given by one of the paths entries.
-      Patterns are given to the Unix <command>ls</command> or to the Windows
-      <command>dir</command> commands in order to get information about files.
-      Thus in order to write portable Scilab script valid wildcard patterns
-      for both OS are to be given. Note that pathname conversion is
-      performed and for example <literal>SCI/core/macros/*.sci</literal> is a valid
-      pattern for both Unix and Windows.
-    </para>
-    <para>
-      If <varname>flag</varname> is true the pathnames given by
-      <varname>paths</varname> are converted according to the <code>getos() == 'Windows'</code>
-      value (see also <link linkend="pathconvert">pathconvert</link>).
-      Moreover, if <varname>flagexpand</varname> is true leading strings like
-      <varname>SCIHOME</varname>, <varname>SCI</varname> or
-      <literal>~</literal> are expanded using environment variables.
-    </para>
-    <para>
-      If the input path is the name of a directory, the returned 
-      <varname>files</varname> names are the
-      relative to that directory.
-    </para>
-    <para>
-      If the input path contains a pattern (e.g. <literal>"/*"</literal>, <literal>"*.c"</literal>), the returned <varname>files</varname> names
-      are prepended with the input path.
-    </para>
-  </refsection>
-  <refsection>
-    <title>Examples</title>
-    <programlisting role="example">
-      <![CDATA[
+    <refnamediv>
+        <refname>listfiles</refname>
+        <refpurpose>list of files</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>files = listfiles(paths [, flag, flagexpand])</synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Arguments</title>
+        <variablelist>
+            <varlistentry>
+                <term>paths</term>
+                <listitem>
+                    <para>
+                        a string matrix giving a set of pathnames (eventually  ended by a pattern built with <literal>*</literal>).
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>flag, flagexpand</term>
+                <listitem>
+                    <para>
+                        boolean optional parameters (default value is <constant>%t</constant>).
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>files</term>
+                <listitem>
+                    <para>a string matrix.</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            <function>listfiles</function> can be used to list the files which match
+            the patterns given by one of the paths entries.
+            Patterns are given to the Unix <command>ls</command> or to the Windows
+            <command>dir</command> commands in order to get information about files.
+            Thus in order to write portable Scilab script valid wildcard patterns
+            for both OS are to be given. Note that pathname conversion is
+            performed and for example <literal>SCI/core/macros/*.sci</literal> is a valid
+            pattern for both Unix and Windows.
+        </para>
+        <para>
+            If <varname>flag</varname> is true the pathnames given by
+            <varname>paths</varname> are converted according to the <code>getos() == 'Windows'</code>
+            value (see also <link linkend="pathconvert">pathconvert</link>).
+            Moreover, if <varname>flagexpand</varname> is true leading strings like
+            <varname>SCIHOME</varname>, <varname>SCI</varname> or
+            <literal>~</literal> are expanded using environment variables.
+        </para>
+        <para>
+            If the input argument <varname>paths</varname> is the name of a directory, the returned <varname>files</varname>
+            are the names relative to that directory.
+        </para>
+        <para>
+            If the input argument <varname>paths</varname> contains more than one element, or if it contains
+            a pattern (e.g. <literal>"/*"</literal>, <literal>"*.c"</literal>), the returned <varname>files</varname> are the absolute paths (i.e.
+            file name prepended with the name of the directory).
+        </para>
+    </refsection>
+    <refsection>
+        <title>Examples</title>
+        <programlisting role="example">
+            <![CDATA[
 files=listfiles(['SCI/modules/core/macros/*.sci';'SCI/modules/core/macros/*.bin']);
  ]]>
-    </programlisting>
-  </refsection>
-  <refsection>
-    <title>History</title>
-    <revhistory>
-      <revision>
-        <revnumber>5.4.0</revnumber>
-        <revremark>If paths is not a single string, all returned files are homogenized with the absolute path form.</revremark>
-      </revision>
-    </revhistory>
-  </refsection>
-  <refsection role="see also">
-    <title>See Also</title>
-    <simplelist type="inline">
-      <member>
-        <link linkend="findfiles">findfiles</link>
-      </member>
-      <member>
-        <link linkend="basename">basename</link>
-      </member>
-      <member>
-        <link linkend="pathconvert">pathconvert</link>
-      </member>
-    </simplelist>
-  </refsection>
+        </programlisting>
+    </refsection>
+    <refsection>
+        <title>History</title>
+        <revhistory>
+            <revision>
+                <revnumber>5.4.0</revnumber>
+                <revremark>If paths is not a single string, all returned files are homogenized with the absolute path form.</revremark>
+            </revision>
+        </revhistory>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="findfiles">findfiles</link>
+            </member>
+            <member>
+                <link linkend="basename">basename</link>
+            </member>
+            <member>
+                <link linkend="pathconvert">pathconvert</link>
+            </member>
+        </simplelist>
+    </refsection>
 </refentry>