Introduce and use latex_path().

[lyx.git] / src / support / filetools.h

diff --git a/src/support/filetools.h b/src/support/filetools.h
index 1a9e5217b78e3b16fa1a3140291b1c49245394c6..092aa70a45c3586b8ad3570dc4afc27c05377d4e 100644 (file)
--- a/src/support/filetools.h
+++ b/src/support/filetools.h
@@ -19,17 +19,22 @@
 namespace lyx {
 namespace support {
 
-/// remove directory and all contents, returns 0 on success
-int destroyDir(std::string const & tmpdir);
+/// remove directory and all contents, returns true on success
+bool destroyDir(std::string const & tmpdir);
 
-///
-std::string const CreateBufferTmpDir(std::string const & pathfor = std::string());
+/// Creates the per buffer temporary directory
+std::string const createBufferTmpDir();
 
 /// Creates directory. Returns true on success
 bool createDirectory(std::string const & name, int permissions);
 
-///
-std::string const CreateLyXTmpDir(std::string const & deflt);
+/** Creates the global LyX temp dir.
+  \p deflt can be an existing directory name. In this case a new directory
+  inside \p deflt is created. If \p deflt does not exist yet, \p deflt is
+  created and used as the temporary directory.
+  \return the tmp dir name or string() if something went wrong.
+ */
+std::string const createLyXTmpDir(std::string const & deflt);
 
 /** Find file by searching several directories.
   Uses a string of paths separated by ";"s to find a file to open.
@@ -65,14 +70,6 @@ bool IsDirWriteable (std::string const & path);
  */
 bool IsFileReadable (std::string const & path);
 
-/** Is file read only?
-  returns
-    1: read-write
-    0: read_only
-   -1: error (doesn't exist, no access, anything else)
-  */
-int IsFileWriteable (std::string const & path);
-
 ///
 bool IsLyXFilename(std::string const & filename);
 
@@ -99,19 +96,26 @@ std::string const
 i18nLibFileSearch(std::string const & dir, std::string const & name,
                  std::string const & ext = std::string());
 
-/** Takes a command such as "sh $$s/convertDefault.sh file.in file.out"
- *  and replaces "$$s/" with the path to the "most important" of LyX's
- *  script directories containing this script. If the script is not found,
- *  "$$s/" is removed. Executing the command will still fail, but the
- *  error message will make some sort of sense ;-)
+/** Takes a command such as "sh $$s/scripts/convertDefault.sh file.in file.out"
+ *  and replaces "$$s/" with the path to the LyX support directory containing
+ *  this script. If the script is not found, "$$s/" is removed. Executing the
+ *  command will still fail, but the error message will make some sort of
+ *  sense ;-)
  */
 std::string const LibScriptSearch(std::string const & command);
 
-///
-std::string const GetEnv(std::string const & envname);
-
-/// A helper function.
-std::string const GetEnvPath(std::string const & name);
+/** @param path a file path in internal_path format. Ie, directories
+ *  are indicated by '/', not by '\'.
+ *
+ *  Manipulates @c path into a form suitable for inclusion in a LaTeX
+ *  document.  
+ *  If @c path contains LaTeX special characters, these are escaped.
+ *  Eg, '~' -> '\string~'
+ *  If @c path contains spaces, then the returned path is enclosed in
+ *  "-quotes. This last fix will lead to successful compiliation of the
+ *  LaTeX file only if a sufficiently modern LaTeX compiler is used.
+ */
+std::string const latex_path(std::string const & path);
 
 /// Substitutes active latex characters with underscores in filename
 std::string const MakeLatexName(std::string const & file);
@@ -135,17 +139,27 @@ ChangeExtension(std::string const & oldname, std::string const & extension);
 /// Return the extension of the file (not including the .)
 std::string const GetExtension(std::string const & name);
 
-/// Return the type of the file as an extension from contents
-std::string const getExtFromContents(std::string const & name);
+/** Guess the file format name (as in Format::name()) from contents.
+ Normally you don't want to use this directly, but rather
+ Formats::getFormatFromFile().
+ */
+std::string const getFormatFromContents(std::string const & name);
 
 /// check for zipped file
 bool zippedFile(std::string const & name);
 
-/// \return the name that LyX will give to the unzipped file.
+/** \return the name that LyX will give to the unzipped file \p zipped_file
+  if the second argument of unzipFile() is empty.
+ */
 std::string const unzippedFileName(std::string const & zipped_file);
 
-/// unzip a file
-std::string const unzipFile(std::string const & zipped_file);
+/** Unzip \p zipped_file.
+  The unzipped file is named \p unzipped_file if \p unzipped_file is not
+  empty, and unzippedFileName(\p zipped_file) otherwise.
+  Will overwrite an already existing unzipped file without warning.
+ */
+std::string const unzipFile(std::string const & zipped_file,
+                            std::string const & unzipped_file = std::string());
 
 /// Returns true is path is absolute
 bool AbsolutePath(std::string const & path);