* Bug #8649 fixed : Basename help page is not clear on the argument flag and flagexpand. 86/10786/2
Simon Marchetto [Tue, 12 Mar 2013 11:38:45 +0000 (12:38 +0100)]
Fix: rewrite help for flags, flagexpand arguments in basename & dirname macros

+ fix basename & dirname examples

Change-Id: I25c51a895ac1fd9fa38883aeff8ad0f8d6dcf203

scilab/CHANGES_5.4.X
scilab/modules/fileio/help/en_US/path_filename/basename.xml
scilab/modules/fileio/help/en_US/path_filename/dirname.xml

index 6ab9e03..bd571bd 100644 (file)
@@ -191,6 +191,9 @@ Documentation
 
 * Default stacksize is incorrect (See bug #12134).
 
+* Document flag and flagexpand arguments in basename and
+  dirname functions (See bug #8649).
+
 
 Compilation
 ============
index f41c27e..72ded5a 100644 (file)
@@ -3,11 +3,11 @@
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) 2008 - INRIA
  * ...
- * 
+ *
  * This file must be used under the terms of the CeCILL.
  * This source file is licensed as described in the file COPYING, which
  * you should have received as part of this distribution.  The terms
- * are also available at    
+ * are also available at
  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
  *
  -->
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>flag, flagexpand</term>
+                <term>flag</term>
+                <listitem>
+                    <para>optional boolean, used to convert the given path(s) for the current operating system.
+                        Default value is true (<constant>%t</constant>).
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>flagexpand</term>
                 <listitem>
-                    <para>boolean optional parameters. Default value is
-                        <constant>%t</constant>.
+                    <para>optional boolean, used to expand leading variables in paths.
+                        Only used with flag argument. Default value is true (<constant>%t</constant>).
                     </para>
                 </listitem>
             </varlistentry>
     <refsection>
         <title>Description</title>
         <para>
-            <code>basename(files)</code> returns the basename of the file entries
-            given in <varname>files</varname>.
+            <code>basename(files)</code> returns the suffixs of paths, i.e. the last string following the final file separator for each path given in <varname>files</varname>.
+        </para>
+        <para>
+            If <varname>flag</varname> is true the paths are first converted for the current operating system (for example, 'C:/Tmp/folder' will be converted on Windows to 'C:\Tmp\folder').
+        </para>
+        <para>
+            if <varname>flagexpand</varname> is true, leading path variables (HOME, SCI, SCIHOME, ...) are expanded for the current operating system
+            (for example, 'HOME\tmp' will be converted on Linux to 'home/&lt;user&gt;/tmp', where &lt;user&gt; is the current user logged on).
         </para>
         <para>
-            If <varname>flag</varname> is true the files are first converted to
-            the target type given by the <code>getos() == 'Windows'</code> variable. Moreover,
-            if <varname>flagexpand</varname> is true leading strings like
-            <literal>SCIHOME</literal>, <literal>SCI</literal> or <literal>~</literal>
-            are expanded using environment variables.
+            See more details on <varname>flag</varname> and <varname>flagexpand</varname> in <link linkend="pathconvert">pathconvert</link> section.
         </para>
     </refsection>
     <refsection>
         <title>Examples</title>
-        <programlisting role="example"><![CDATA[ 
-files=basename('SCI/modules/fileio/macros/poo.sci')
-files=basename('SCI/modules\fileio/macros/poo.sci')
-files=basename('SCI/modules\fileio/macros/poo.sci.k')
+        <programlisting role="example"><![CDATA[
+files=basename('/tmp/poo')
+files=basename('/tmp/poo.sci')
+files=basename('/tmp/poo.bak.sci')
+files=basename('/tmp/')
+
+files=basename('C:\tmp\poo')
+files=basename('C:\tmp\poo.sci')
+files=basename('C:\tmp\poo.bak.sci')
+
+files=basename('C:\tmp\')
+
+files=basename(['SCI/etc/scilab.start', 'SCI/etc/scilab.quit'])
  ]]></programlisting>
     </refsection>
     <refsection role="see also">
index 5bbb615..1237e9e 100644 (file)
@@ -3,11 +3,11 @@
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) 2008 - INRIA
  * ...
- * 
+ *
  * This file must be used under the terms of the CeCILL.
  * This source file is licensed as described in the file COPYING, which
  * you should have received as part of this distribution.  The terms
- * are also available at    
+ * are also available at
  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
  *
  -->
             <varlistentry>
                 <term>files</term>
                 <listitem>
-                    <para>a string matrix giving a set of file names</para>
+                    <para>a string matrix containing file paths</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>flag</term>
+                <listitem>
+                    <para>optional boolean, used to convert the given path(s) for the current operating system.
+                        Default value is true (<constant>%t</constant>).
+                    </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>flag, flagexpand</term>
+                <term>flagexpand</term>
                 <listitem>
-                    <para>
-                        boolean optional parameters (default value <constant>%t</constant>)
+                    <para>optional boolean, used to expand leading variables in paths.
+                        Only used with flag argument. Default value is true (<constant>%t</constant>).
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>files, dirs</term>
+                <term>dirs</term>
                 <listitem>
                     <para>string matrices</para>
                 </listitem>
     <refsection>
         <title>Description</title>
         <para>
-            <function>dirname</function> returns the directory names of the file entries given in <varname>files</varname>.
+            <function>dirname</function> returns the directory paths of the file entries given in <varname>files</varname>.
+        </para>
+        <para>
+            If <varname>flag</varname> is true the paths are first converted for the current operating system (for example, 'C:/Tmp/folder' will be converted on Windows to 'C:\Tmp\folder').
         </para>
         <para>
-            If <varname>flag</varname> is true the files are first converted to the target 
-            type given by the <code>getos() == 'Windows'</code> variable. 
-            Moreover, if <varname>flagexpand</varname> is true leading strings like
-            <literal>SCIHOME</literal>, <literal>SCI</literal> or <literal>~</literal> are expanded using environment
-            variables.
+            if <varname>flagexpand</varname> is true, leading path variables (HOME, SCI, SCIHOME, ...) are expanded for the current operating system
+            (for example, 'HOME\tmp' will be converted on Linux to 'home/&lt;user&gt;/tmp', where &lt;user&gt; is the current user logged on).
         </para>
         <para>
-            Note that <code>dirname(files,%f)</code> can give erroneous results if 
-            pathnames given in <varname>files</varname> do not follow the convention 
-            given by the <code>getos() == 'Windows'</code> variable.
+            See more details on <varname>flag</varname> and <varname>flagexpand</varname> in <link linkend="pathconvert">pathconvert</link> section.
         </para>
     </refsection>
     <refsection>
         <title>Examples</title>
-        <programlisting role="example"><![CDATA[ 
-dirs=dirname('SCI/modules/fileio/macros/poo.sci')
-dirs=dirname('SCI/modules\fileio/macros/poo.sci')
-dirs=dirname('SCI/modules\fileio/macros/poo.sci.k')
+        <programlisting role="example"><![CDATA[
+dirs=dirname('/tmp/folder/poo')
+dirs=dirname('/tmp/folder/')
+dirs=dirname('/')
+
+dirs=dirname('C:\tmp\folder\poo')
+dirs=dirname('C:\tmp\folder\')
+dirs=dirname('C:\')
+
+dirs=dirname(['SCI/etc/scilab.start', 'SCI/etc/scilab.quit'])
  ]]></programlisting>
     </refsection>
     <refsection role="see also">