Documentation + file removals as sent to list

git-svn-id: svn://svn.lyx.org/lyx/lyx-devel/trunk@4286 a592a061-630c-0410-9148-cb99ea01b6c8

src/support/ChangeLog

@@ -1,3 +1,22 @@
+2002-05-30  John Levon  <moz@compsoc.man.ac.uk>
+ 
+ 	* Makefile.am:
+ 	* date.C:
+ 	* getUserName.C:
+ 	* fileblocks.c:
+ 	* StrPool.h:
+ 	* StrPool.C: remove unused files
+  
+ 	* lyxalgo.h:
+ 	* lyxlib.h:
+ 	* mkdir.C:
+ 	* path.h:
+ 	* path.C:
+ 	* systemcall.C:
+ 	* textutils.h:
+ 	* translator.h:
+ 	* types.h: document and small cleanups
+ 
 2002-05-29  Lars Gullik Bjønnes  <larsbj@birdstep.com>
 
 	* switch from SigC signals to boost::signals.

src/support/Makefile.am

@@ -22,13 +22,10 @@ libsupport_la_SOURCES = \
 	LOstream.h \
 	os.C \
 	os.h \
-	StrPool.C \
-	StrPool.h \
 	abort.C \
 	atoi.C \
 	chdir.C \
 	copy.C \
-	date.C \
 	filetools.C \
 	filetools.h \
 	fmt.C \
@@ -36,7 +33,6 @@ libsupport_la_SOURCES = \
 	forkedcall.h \
 	forkedcontr.C \
 	forkedcontr.h \
-	getUserName.C \
 	getcwd.C \
 	kill.C \
 	limited_stack.h \

src/support/StrPool.C

@@ -1,41 +0,0 @@
-/* This file is part of
- * ======================================================
- *
- *           LyX, The Document Processor
- *
- *	     Copyright 2000-2001 Jean-Marc Lasgouttes
- *
- * ======================================================*/
-
-#ifdef __GNUG__
-#pragma implementation
-#endif
-
-#include <config.h>
-#include "StrPool.h"
-
-
-StrPool::~StrPool()
-{
-	for (Pool::const_iterator cit = pool_.begin();
-	     cit != pool_.end() ; ++cit) {
-		delete[] (*cit);
-	}
-}
-
-/* One interesting thing here would be to store the strings in a map,
-   so that one string is only stored once. This would make things a
-   bit slower, but memory requirements would be lower in the long run.
-   I expect that it would be fast enough anyway. (Lgb)
-*/
-char const * StrPool::add(string const & str)
-{
-	string::size_type s = str.length();
-	char * buf = new char [s + 1];
-	str.copy(buf, s);
-	buf[s] = '\0';
-	pool_.push_back(buf);
-	return buf;
-}
-
-//StrPool strPool;

src/support/StrPool.h

@@ -1,39 +0,0 @@
-// -*- C++ -*-
-/* This file is part of
- * ======================================================
- *
- *           LyX, The Document Processor
- *
- *	     Copyright 2000-2001 Jean-Marc Lasgouttes
- *
- * ======================================================*/
-
-
-#ifndef STRPOOL_H
-#define STRPOOL_H
-
-#ifdef __GNUG__
-#pragma interface
-#endif
-
-#include "LString.h"
-#include <vector>
-
-///
-class StrPool {
-public:
-	/// delete all the strings that have been allocated by add()
-	~StrPool();
-	/// Make a copy of the string, and remember it in the pool
-	char const * add(string const & str);
-
-private:
-	///
-	typedef std::vector<char const *> Pool;
-	///
-	Pool pool_;
-};
-
-//extern StrPool strPool;
-
-#endif

src/support/date.C

@@ -1,14 +0,0 @@
-#include <config.h>
-
-#include <time.h>
-
-#include "support/lyxlib.h"
-
-char * lyx::date()
-{
-	time_t tid;
-	if ((tid = ::time(0)) == static_cast<time_t>(-1))
-		return 0;
-	else
-		return ::ctime(&tid);
-}

src/support/fileblocks.c

@@ -1,70 +0,0 @@
-/* Convert file size to number of blocks on System V-like machines.
-   Copyright (C) 1990 Free Software Foundation, Inc.
-
-   This program is free software; you can redistribute it and/or modify
-   it under the terms of the GNU General Public License as published by
-   the Free Software Foundation; either version 2, or (at your option)
-   any later version.
-
-   This program is distributed in the hope that it will be useful,
-   but WITHOUT ANY WARRANTY; without even the implied warranty of
-   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-   GNU General Public License for more details.
-
-   You should have received a copy of the GNU General Public License
-   along with this program; if not, write to the Free Software Foundation,
-   Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.  */
-
-/* Written by Brian L. Matthews, blm@6sceng.UUCP. */
-
-#ifdef HAVE_CONFIG_H
-# include <config.h>
-#endif
-
-#if !defined (HAVE_ST_BLOCKS) && !defined(_POSIX_VERSION)
-# include <sys/types.h>
-# include <sys/param.h>
-
-# ifndef NINDIR
-/* Some SysV's, like Irix, seem to lack these.  Hope they're correct. */
-/* Size of a indirect block, in bytes. */
-#  ifndef BSIZE
-#   define BSIZE 1024
-#  endif
-
-/* Number of inode pointers per indirect block. */
-#  define NINDIR (BSIZE/sizeof(daddr_t))
-# endif /* !NINDIR */
-
-/* Number of direct block addresses in an inode. */
-# define NDIR	10
-
-/* Return the number of 512-byte blocks in a file of SIZE bytes. */
-
-long
-st_blocks (size)
-     long size;
-{
-  long datablks = (size + 512 - 1) / 512;
-  long indrblks = 0;
-
-  if (datablks > NDIR)
-    {
-      indrblks = (datablks - NDIR - 1) / NINDIR + 1;
-
-      if (datablks > NDIR + NINDIR)
-	{
-	  indrblks += (datablks - NDIR - NINDIR - 1) / (NINDIR * NINDIR) + 1;
-
-	  if (datablks > NDIR + NINDIR + NINDIR * NINDIR)
-	    indrblks++;
-	}
-    }
-
-  return datablks + indrblks;
-}
-#else
-/* This declaration is solely to ensure that after preprocessing
-   this file is never empty.  */
-extern int textutils_fileblocks_unused;
-#endif

src/support/getUserName.C

@@ -1,15 +0,0 @@
-#include <config.h>
-
-#include "support/lyxlib.h"
-#include "support/filetools.h"
-#include "gettext.h"
-
-string const lyx::getUserName()
-{
-	string userName(GetEnv("LOGNAME"));
-	if (userName.empty())
-		userName = GetEnv("USER");
-	if (userName.empty())
-		userName = _("unknown");
-	return userName;
-}

src/support/lyxalgo.h

@@ -1,4 +1,15 @@
 // -*- C++ -*-
+/**
+ * \file lyxalgo.h
+ * Copyright 1995-2002 the LyX Team
+ * Read the file COPYING
+ *
+ * A variety of useful templates.
+ *
+ * \author unknown
+ */
+
+ 
 
 #ifndef LYX_ALGO_H
 #define LYX_ALGO_H
@@ -44,6 +55,10 @@ struct firster {
 };
 
 
+/**
+ * copy elements in the given range to the output iterator 
+ * if the predicate evaluates as true
+ */
 template <class InputIter, class OutputIter, class Func>
 OutputIter copy_if(InputIter first, InputIter last,
 	       OutputIter result, Func func)
@@ -74,4 +89,4 @@ count (Iterator first, Iterator last, T const & value)
 
 } // namespace lyx
 
-#endif
+#endif // LYX_ALGO_H

src/support/lyxlib.h

@@ -1,67 +1,58 @@
 // -*- C++ -*-
-/* This file is part of
+/**
- * ======================================================
+ * \file lyxlib.h
+ * Copyright 1995-2002 the LyX Team
+ * Read the file COPYING
  *
- *           LyX, The Document Processor
+ * A selection of useful system functions made
+ * handy for C++ usage.
  *
- *           Copyright 1995 Matthias Ettrich
+ * \author unknown
- *           Copyright 1995-2001 The LyX Team.
+ */
- *
- * ====================================================== */
 
 #ifndef LYX_LIB_H
 #define LYX_LIB_H
 
 #include "LString.h"
 
-// Where can I put this?  I found the occurence of the same code
-// three/four times. Don't you think it better to use a macro definition
-// (an inlined member of some class)?
-
-// Use a namespace if we can, a struct otherwise
 namespace lyx {
 
-///
+/// get the current working directory
 string const getcwd();
-///
+/// change to a directory, 0 is returned on success.
 int chdir(string const & name);
-/// Returns false if it fails
+/**
+ * rename a file, returns false if it fails. 
+ * It can handle renames across partitions.
+ */
 bool rename(string const & from, string const & to);
-/// Returns false it it fails
+/// copy a file, returns false it it fails
 bool copy(string const & from, string const & to);
-/// generates a checksum
+/// generates a checksum of a file
 unsigned long sum(string const & file);
-/// returns a date string (not used currently)
+/// FIXME: some point to this hmm ?
-char * date();
-/// returns the name of the user (not used currently)
-string const getUserName();
-///
 int kill(int pid, int sig);
-///
+/// FIXME: same here
 void abort();
-///
+/// create the given directory with the given mode
 int mkdir(string const & pathname, unsigned long int mode);
-///
+/// put a C string into the environment
 int putenv(char const * str);
-///
+/// unlink the given file
 int unlink(string const & file);
-///
+/// remove the given directory
 int rmdir(string const & file);
-///
+/// convert the given string to an integer
 int atoi(string const & nstr);
-///
+/// (securely) create a temporary file in the given dir with the given prefix
 string const tempName(string const & dir = string(),
 		      string const & mask = string());
 
 
-/** Returns true if var is approximately equal to number with allowed error
+/**
+ * Returns true if var is approximately equal to number with allowed error
  * of 'error'.
  *
- * Reason: A float can be very close to the number, yet still need not be
- * exactly equal, you can have exp(-10) which is very close to zero but not
- * zero. If you only need an approximate equality (you usually do), use this
- * template.
- *
  * Usage: if (float_equal(var, number, 0.0001)) { }
  *
  * This will check if 'var' is approx. equal to 'number' with error of 1/1000
@@ -72,4 +63,5 @@ inline bool float_equal(float var, float number, float error)
 }
 
 } // namespace lyx
+ 
 #endif /* LYX_LIB_H */

src/support/mkdir.C

@@ -11,5 +11,6 @@
 
 int lyx::mkdir(string const & pathname, unsigned long int mode)
 {
+	// FIXME: why don't we have mode_t in lyx::mkdir prototype ?? 
 	return ::mkdir(pathname.c_str(), mode_t(mode));
 }

src/support/path.C

@@ -1,3 +1,11 @@
+/**
+ * \file path.C
+ * Copyright 1995-2002 the LyX Team
+ * Read the file COPYING
+ *
+ * \author unknown
+ */
+
 #include <config.h>
 
 #ifdef __GNUG__
@@ -11,21 +19,14 @@ int Path::pop()
 	if (popped_) {
 		// should throw an exception
 		// throw logical_error();
-		// The use of WriteFSAlerrt makes this impossible
-		// to inline.
-		//Alert::err_alert(_("Error: Dir already popped: "),
-		//	     pushedDir_);
 		return 0;
 	}
+ 
 	if (lyx::chdir(pushedDir_)) {
 		// should throw an exception
 		// throw DirChangeError();
-		// The use of Alert::err_alert makes this impossible
-		// to inline.
-		//Alert::err_alert(
-		//	_("Error: Could not change to directory: "),
-		//	pushedDir_);
 	}
 	popped_ = true;
+ 
 	return 0;
 }

src/support/path.h

@@ -1,4 +1,12 @@
 // -*- C++ -*-
+/**
+ * \file path.h
+ * Copyright 1995-2002 the LyX Team
+ * Read the file COPYING
+ *
+ * \author unknown
+ */
+
 #ifndef PATH_H
 #define PATH_H
 
@@ -11,39 +19,48 @@
 #pragma interface
 #endif
 
-///
+
+/**
+ * Path - utility closs for stackable working directories
+ *
+ * You can use a local variable of this type to temporarily
+ * change to a directory as the cwd, for example :
+ *
+ * if (blah) {
+ *	Path p("/tmp/blah");
+ * 	...
+ * }
+ *
+ * At the end of p's scope the cwd is reset to its previous value.
+ */
 class Path : boost::noncopyable {
 public:
-	///
+	/// change to the given directory
 	explicit
 	Path(string const & path)
 		: popped_(false)
 	{
 		if (!path.empty()) { 
-			pushedDir_ = lyx::getcwd(); // GetCWD();
+			pushedDir_ = lyx::getcwd();
-			if (pushedDir_.empty() || lyx::chdir(path)) {
+			if (pushedDir_.empty() || lyx::chdir(path))
-				// should throw an exception
+				/* FIXME: throw */;
-				// throw DirChangeError();
-				// The use of Alert::err_alert makes this
-				// impossible to inline.
-				//Alert::err_alert(_("Error: Could not change to directory: "),
-				//	     path);
-			}
 		} else {
 			popped_ = true;
 		}
 	}
-	///
+ 
+	/// set cwd to the previous value if needed
 	~Path()
 	{
 		if (!popped_) pop();
 	}
-	///
+ 
+	/// set cwd to the previous value if needed
 	int pop();
 private:
-	///
+	/// whether we are in the new cwd or not
 	bool popped_;
-	///
+	/// the previous cwd
 	string pushedDir_;
 };
 
@@ -55,4 +72,4 @@ private:
 #define Path(x) unnamed_Path;
 // Tip gotten from Bobby Schmidt's column in C/C++ Users Journal
 
-#endif
+#endif // PATH_H

src/support/systemcall.C

@@ -7,13 +7,6 @@
  *
  * Interface cleaned up by
  * \author Angus Leeming <a.leeming@ic.ac.uk>
- *
- * Class Systemcall uses "system" to launch the child process.
- * The user can choose to wait or not wait for the process to complete, but no
- * callback is invoked upon completion of the child.
- *
- * The child process is not killed when the Systemcall instance goes out of
- * scope.
  */
 
 #include <config.h>
@@ -25,15 +18,7 @@
 #include "systemcall.h"
 #include "os.h"
 
-#include <cstdlib> //for ::system
+#include <cstdlib>
-
-
-#if 0
-Systemcall::Systemcall(Starttype how, string const & what)
-{
-	startscript(how, what);
-}
-#endif
 
 
 // Reuse of instance

src/support/systemcall.h

@@ -8,15 +8,6 @@
  *
  * Interface cleaned up by
  * \author Angus Leeming <a.leeming@ic.ac.uk>
- *
- * An instance of Class Systemcall represents a single child process.
- *
- * Class Systemcall uses system() to launch the child process.
- * The user can choose to wait or not wait for the process to complete, but no
- * callback is invoked upon completion of the child.
- *
- * The child process is not killed when the Systemcall instance goes out of
- * scope.
  */
 
 #ifndef SYSTEMCALL_H
@@ -28,27 +19,24 @@
 #pragma interface
 #endif
 
+/** 
+ * An instance of Class Systemcall represents a single child process.
+ *
+ * Class Systemcall uses system() to launch the child process.
+ * The user can choose to wait or not wait for the process to complete, but no
+ * callback is invoked upon completion of the child.
+ *
+ * The child process is not killed when the Systemcall instance goes out of
+ * scope.
+ */
 class Systemcall {
 public:
-	///
+	/// whether to wait for completion
 	enum Starttype {
-		///
+		Wait, //< wait for completion before returning from startscript()
-		Wait,
+		DontWait //< don't wait for completion
-		///
-		DontWait
 	};
  
-#if 0
-	///
-	Systemcall() {}
-
-	/** Generate instance and start child process.
-	 *  The string "what" contains a commandline with arguments separated
-	 *  by spaces.
-	 */
-	Systemcall(Starttype how, string const & what);
-#endif
-
 	/** Start child process.
 	 *  The string "what" contains a commandline with arguments separated
 	 *  by spaces.

src/support/textutils.h

@@ -1,52 +1,53 @@
 // -*- C++ -*-
-/* This file is part of
+/**
- * ======================================================
+ * \file textutils.h
+ * Copyright 1995-2002 the LyX Team
+ * Read the file COPYING
  *
- *           LyX, The Document Processor
+ * \author unknown
- *
+ */
- *           Copyright 1995 Matthias Ettrich
+
- *           Copyright 1995-2001 The LyX Team.
+// FIXME: I can think of a better name for this file ...
- *
- * ====================================================== */
  
 #ifndef TEXTUTILS_H
 #define TEXTUTILS_H
 
-///
+/// return true if the char is a meta-character newline
 inline
 bool IsNewlineChar(char c) {
 	return (c == Paragraph::META_NEWLINE);
 }
 
 
-///
+/// return true if the char is a word separator
 inline
 bool IsSeparatorChar(char c) {
 	return (c == ' ');
 }
 
 
-///
+/// return true if the char is a line separator
+inline
+bool IsLineSeparatorChar(char c) {
+	return (c == ' ');
+}
+ 
+
+/// return true if the char is a meta-character for hfill
 inline
 bool IsHfillChar(char c) {
 	return (c == Paragraph::META_HFILL);
 }
 
 
-///
+/// return true if the char is a meta-character for an inset
 inline
 bool IsInsetChar(char c) {
 	return (c == Paragraph::META_INSET);
 }
 
 
-///
+/// return true if the char is "punctuation"
-inline
-bool IsLineSeparatorChar(char c) {
-	return (c == ' ');
-}
-
-///
 inline
 bool IsKommaChar(char c) {
 	return (c == ','
@@ -77,7 +78,7 @@ bool IsKommaChar(char c) {
 }
 
 
-///
+/// return true if a char is alphabetical (including accented chars)
 inline
 bool IsLetterChar(unsigned char c) {
 	return ((c >= 'A' && c <= 'Z')
@@ -86,21 +87,21 @@ bool IsLetterChar(unsigned char c) {
 }
 
 
-///
+/// return true if the char is printable (masked to 7-bit ASCII)
 inline
 bool IsPrintable(unsigned char c) {
 	return ((c & 127) >= ' ');
 }
 
 
-///
+/// return true if the char is printable and not a space (masked to 7-bit ASCII) 
 inline
 bool IsPrintableNonspace(unsigned char c) {
 	return IsPrintable(c) && (c != ' ');
 }
 
 
-/// Word is not IsSeparator or IsKomma or IsHfill or IsFloat or IsInset.
+/// return true if the char forms part of a word
 inline
 bool IsWordChar(unsigned char c) {
 	return !(IsSeparatorChar(c)
@@ -110,7 +111,7 @@ bool IsWordChar(unsigned char c) {
 }
 
 
-///
+/// completely pointless FIXME
 inline
 bool IsDigit(unsigned char ch)
 {
@@ -118,10 +119,11 @@ bool IsDigit(unsigned char ch)
 }
 
 
-///
+/// return true if the char is alphanumeric
 inline
 bool IsLetterCharOrDigit(unsigned char ch)
 {
 	return IsLetterChar(ch) || IsDigit(ch);
 }
-#endif
+ 
+#endif // TEXTUTILS_H

src/support/translator.h

@@ -1,13 +1,11 @@
 // -*- C++ -*-
-/* This file is part of
+/**
- * =================================================
+ * \file translator.h
+ * Copyright 1995-2002 the LyX Team
+ * Read the file COPYING
  *
- *          LyX, The Document Processor
+ * \author Baruch Even <baruch@lyx.org>
- *          Copyright 1995 Matthias Ettrich.
+ */
- *          Copyright 1995-2001 The LyX Team.
- *
- *          This file Copyright 2000 Baruch Even
- * ================================================= */
 
 #ifndef TRANSLATOR_H
 #define TRANSLATOR_H
@@ -19,12 +17,13 @@
 
 #include "support/LAssert.h"
 #include "support/lyxfunctional.h"
-/** This class template is used to translate between two elements, specifically
+/**
-    it was worked out to translate between an enum and strings when reading
+ * This class template is used to translate between two elements, specifically
-    the lyx file.
+ * it was worked out to translate between an enum and strings when reading
-
+ * the lyx file.
-    The two template arguments should be of different types.
+ *
-*/
+ * The two template arguments should be of different types.
+ */
 template<typename T1, typename T2>
 class Translator {
 public:
@@ -99,4 +98,4 @@ private:
 	T2 const default_t2;
 };
 
-#endif
+#endif // TRANSLATOR_H

src/support/types.h

@@ -1,11 +1,18 @@
+/**
+ * \file types.h
+ * Copyright 2002 the LyX Team
+ * Read the file COPYING
+ *
+ * Provide a set of typedefs for commonly used things like sizes and
+ * indices wile trying to stay compatible with types used
+ * by the standard containers.
+ *
+ * \author André Pönitz
+ */
+
 #ifndef LYX_TYPES_H
 #define LYX_TYPES_H
 
-// provide a set of typedefs for commonly used things like sizes and
-// indices while trying to stay compatible with types used by the standard
-// containers.
-
-
 // this probably could be improved by using <cstddef>...
 #include <vector>
 
@@ -62,4 +69,4 @@ namespace lyx
 
 }
 
-#endif
+#endif // LYX_TYPES_H