Revision of help pages for pathconvert (en_US, ru_RU).
[scilab.git] / scilab / modules / fileio / help / en_US / path_filename / pathconvert.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2008 - INRIA
5  * ...
6  *
7  * This file must be used under the terms of the CeCILL.
8  * This source file is licensed as described in the file COPYING, which
9  * you should have received as part of this distribution.  The terms
10  * are also available at
11  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
12  *
13  -->
14 <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" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="pathconvert">
15     <refnamediv>
16         <refname>pathconvert</refname>
17         <refpurpose>converts a path to an OS path format.</refpurpose>
18     </refnamediv>
19     <refsynopsisdiv>
20         <title>Calling Sequence</title>
21         <synopsis>paths = pathconvert(paths [,flagtrail [,flagexpand [,type]]])</synopsis>
22     </refsynopsisdiv>
23     <refsection>
24         <title>Arguments</title>
25         <variablelist>
26             <varlistentry>
27                 <term>paths</term>
28                 <listitem>
29                     <para>a string matrix giving a set of file paths</para>
30                 </listitem>
31             </varlistentry>
32             <varlistentry>
33                 <term>flagtrail</term>
34                 <listitem>
35                     <para>
36                         optional boolean, used to add a trailing file separator to the
37                         paths (<literal>\</literal> or <literal>/</literal>,
38                         depending on the target path format). Default value is true
39                         (<constant>%t</constant>).
40                     </para>
41                 </listitem>
42             </varlistentry>
43             <varlistentry>
44                 <term>flagexpand</term>
45                 <listitem>
46                     <para>
47                         optional boolean, used to expand leading variables in paths.
48                         Default value is true (<constant>%t</constant>).
49                     </para>
50                 </listitem>
51             </varlistentry>
52             <varlistentry>
53                 <term>type</term>
54                 <listitem>
55                     <para>
56                         optional string, used to specify the target path format: <literal>'u'</literal> for POSIX path format (GNU/Linux,...), and <literal>'w'</literal> for Windows path format.
57                     </para>
58                 </listitem>
59             </varlistentry>
60         </variablelist>
61     </refsection>
62     <refsection>
63         <title>Description</title>
64         <para>
65             <function>pathconvert</function> is used to convert a set of paths,
66             to be compatible with an OS (Operating System) path format. For example Windows path style uses <literal>/</literal> for file separator, while it is <literal>\</literal> on other OS.
67         </para>
68         <para>
69             By default, the paths are converted to the current OS path format (but another path format can be specified with argument <varname>type</varname>).
70         </para>
71         <para>
72             <note>
73                 Note: Windows paths starting with a drive letter prefix are converted to
74                 the POSIX paths using the cygwin convention (with <literal>/cygdrive</literal>).
75                 For example: <literal>C:\tmp</literal> will be converted to <literal>/cygdrive/C/tmp</literal>.
76             </note>
77         </para>
78         <para>
79             <varname>flagtrail</varname> is used to add or remove a file
80             separator (depending on the target path format) to the end
81             of paths. When the parameter is set to true, a trailing file
82             separator is added if missing. Otherwise, the trailing file
83             separators are removed.
84         </para>
85         <para>
86             <varname>flagexpand</varname> is used to expand the leading
87             Scilab environment variables in paths. The following
88             variables are accepted:
89             <itemizedlist>
90                 <listitem>
91                     <constant>SCI</constant>
92                 </listitem>
93                 <listitem>
94                     <constant>WSCI</constant>
95                 </listitem>
96                 <listitem>
97                     <constant>SCIHOME</constant>
98                 </listitem>
99                 <listitem>
100                     <constant>TMPDIR</constant>
101                 </listitem>
102                 <listitem>
103                     <literal>home</literal> (or <literal>~</literal>)
104                 </listitem>
105             </itemizedlist>
106             <caution>
107                 <constant>WSCI</constant> is unknown on GNU/Linux and
108                 <literal>~</literal> in term "path" is unknown on Windows.
109             </caution>
110         </para>
111     </refsection>
112     <refsection>
113         <title>Examples</title>
114         <programlisting role="example"><![CDATA[
115 pathconvert("SCI/modules/foo", %f, %t, "w")
116 pathconvert("SCI\modules\foo", %f, %t, "u")
117 pathconvert("SCI\modules\foo", %t, %t, "u")
118 pathconvert("SCI/modules/foo", %f, %f, "w")
119 pathconvert("SCI/modules/foo", %t, %f, "w")
120 pathconvert("C:/tmp", %f, %f, "u")
121 pathconvert("/cygdrive/c/tmp", %f, %f, "w")
122  ]]></programlisting>
123     </refsection>
124     <refsection role="see also">
125         <title>See Also</title>
126         <simplelist type="inline">
127             <member>
128                 <link linkend="basename">basename</link>
129             </member>
130             <member>
131                 <link linkend="listfiles">listfiles</link>
132             </member>
133             <member>
134                 <link linkend="dirname">dirname</link>
135             </member>
136         </simplelist>
137     </refsection>
138 </refentry>