Fix of issue #28 | dlp_VFSVolumeEnumerate() does not list the internal builtin file system

.gitignore

@@ -1,24 +1,68 @@
-config.cache
+# generic files to ignore
+# backup files (*~) and vim swap file (.swp), MacOS dir file (.DS_Store)
+*~
+*.lock
+*.DS_Store
+.*.swp
+*.out
+*.bak
+*.zip
+*.patch
+
+# except this file
+!.gitignore
+
+# from autoreconf -i
+compile
 config.guess
-config.h
-config.h.in
-config.log
-config.status
 config.sub
-configure
 install-sh
+missing
+depcomp
+ylwrap
+test-driver
+autom4te.cache
+m4
+aclocal.m4
+config.cache
+config.h.in
 configure
-libtool
 ltconfig
 ltmain.sh
-.deps
-.libs
-stamp-h*
-aclocal.m4
-Makefile
 Makefile.in
+
+# from configure
+config.h
+config.status
+config.log
+Makefile
+Makefile.PL
+stamp-h*
+libtool
+.deps
 pilot-link.m4
 pilot-link.pc
 pilot-link-pp.pc
 tags
-autom4te.cache
+include/pi-md5.h
+include/pi-version.h
+doc/xml/catalog.xml
+doc/xml/docbook.xsl
+doc/doxygen.cfg
+bindings/Python/setup*.py
+
+# from make / cc / gcc
+*.o
+*.la
+*.lo
+*.so
+.libs
+src/pilot-*
+!src/*.c
+!src/*.h
+!src/*.pl
+src/parsedate.c
+tests/*-test
+
+# from make install
+dist

README

@@ -14,7 +14,7 @@ Bugs and requests...: https://github.com/desrod/pilot-link/issues
 Code contributions..: https://github.com/desrod/pilot-link/pulls?q=is:pr
 
 If you are unwilling to use GitHub, you may instead contact me, David A.
-Desrosiers, project maintainer, via email at <desrod@gnu-designs.com>.
+Desrosiers, project maintainer, via email at <david.a.desrosiers@gmail.com>.
 
 We used to be reachable on Internet Relay Chat, "irc", at irc.pilot-link.org
 in the channel #pilot-link. I used the name "setuid" there, and there were a
@@ -43,7 +43,7 @@ List archive........: https://web.archive.org/web/2015/http://lists.pilot-link.o
 The architecture of pilot-link
 ------------------------------
 
-There are several core parts of pilot-link: 
+There are several core parts of pilot-link:
 
 	The libraries
 	-------------
@@ -79,7 +79,7 @@ There are several core parts of pilot-link:
 	your favorite language of choice.  Currently, pilot-link includes
 	language "bindings" in Perl, Python, Java, and Tcl.  This means you
 	can use those languages, instead of C directly, to talk to your Palm
-	handheld device and communicate with it. 
+	handheld device and communicate with it.
 
 	Want to write a Java application that uses pilot-link's libraries?
 	Simple! Just use the Java bindings.
@@ -120,26 +120,54 @@ Building pilot-link on Linux/Unix systems
 	options. Please make sure you use the --help option to "./configure"
 	to make sure you're enabling all of the options you wish to use.
 
+	You will also need to have your development environment set up, which
+	will require such tools as automake, autoconf, libtool, some system
+	headers, and others to be properly installed and configured on your
+	machine first. If you are running a current Linux or Unix system,
+	these common tools are probably packaged for you.
+	You also need to satisfy the dependencies of these libraries:
+		libusb, libbluetooth, libpopt and byacc
+	On Debian systems you can therefore execute:
+		$ sudo apt install build-essential automake libtool-bin
+		$ sudo apt install libusb-dev libbluetooth-dev libpopt-dev byacc
+
+	If you are using a GIT version of pilot-link, e.g. from
+	https://github.com/desrod/pilot-link/, you will have to run
+	'sh ./autogen.sh' first, from the top-level directory, which will
+	create and bootstrap the "./configure" script for you. On modern systems
+	you may alternatively use 'autoupdate' and 'autoreconf -i -s' to
+	create the "./configure" script.
+
 	If you have downloaded this code from the website, or as a tarball,
 	simply unpack the tarball and run "./configure" in the top-level
 	directory with your specific arguments. "./configure --help" will
 	describe all of them.
 
+	If you want to run some of the command line programs, e.g. `pilot-xfer`,
+	pass autogen.sh or configure the argument:
+
+		$ ./configure --enable-conduits
+
 	If you want to install in some place other than the default location of
-	/usr/local, pass configure an argument such as:
+	/usr/local, pass autogen.sh or configure an argument such as:
 
 		$ ./configure --prefix=/home/fred/pilot
 
+	If you want you want to debug the program with Linux gdb debugger,
+	pass autogen.sh or configure an argument such as:
+
+		$ ./configure CFLAGS="-ggdb -Wall" ...
+
 	If configure ran successfully, you should run 'make' to build the
 	software.
 
 		$ make
-	
+
 	After the source builds, feel free to play around in the 'src'
-	subdirectory, CAREFULLY. 'dlpsh' and 'pilot-xfer' are probably the
-	most useful programs for you, and also the safest to use
+	subdirectory, CAREFULLY. 'pilot-dlpsh' and 'pilot-xfer' are probably
+	the most useful programs for you, and also the safest to use
 	non-destructively.
-	
+
 	Once you have determined that pilot-link works and suits your needs
 	by testing with these programs, switch to the super user, typically
 	"root", to install the conduits, libraries, docs, and headers
@@ -157,17 +185,11 @@ Building pilot-link on Linux/Unix systems
 
 		# make install
 
-	If you are using a CVS version of pilot-link, you will have to run
-	'sh ./autogen.sh' instead, from the top-level directory, which will
-	create and bootstrap the "./configure" script for you.
+	For the smallest footprint of the final distribution you may consider:
 
-	You will also need to have your development environment set up, which
-	will require such tools as automake, autoconf, libtool, some system
-	headers, and others to be properly installed and configured on your
-	machine first. If you are running a current Linux or Unix system,
-	these common tools are probably packaged for you.
+		$ ./configure CFLAGS=-g0
 
-Building pilot-link on OS/2 
+Building pilot-link on OS/2
 ---------------------------
 
 	pilot-link on OS/2 only supports serial devices. USB is unsupported
@@ -179,17 +201,17 @@ Building pilot-link on OS/2
 
 	The steps are fairly straightforward.
 
-	Run the os2configure.cmd script in the top-level directory. 
-	
+	Run the os2configure.cmd script in the top-level directory.
+
 	Run make -f Makefile.os2
-	
+
 	Play around, CAREFULLY. pilot-xfer is probably the most useful
 	program for you, and also the safest of all to use non-destructively.
 	Also dlpsh is a good app to use to poke around in your Palm device.
-	
+
 	Run 'make install' if you you have tested thoroughly and are sure
 	pilot-link works well for you.
-	
+
 	Note on pilot-debug: This program is a work-in-progress, and requires
 	Tcl 7.5 (or greater) and optionally Tk 4.1 (or greater) and/or
 	Readline 2.0.  You'll need to modify Makefile to to use Readline 2.0,
@@ -261,28 +283,60 @@ Building pilot-link on Apple OSX/Darwin
 	first. The syntax to test pilot-link on OSX for USB devices is as
 	follows:
 
-		<pilot-link-command> -p usb: [arguments..] 
+		<pilot-link-command> -p usb: [arguments..]
 
-	One example of this is as follows: 
+	One example of this is as follows:
 
 		pilot-xfer --port usb: --list
 
 	This should list the record and resource databases found on your Palm
 	handheld device.
-	
+
 Building pilot-link on Cygwin under Windows
 -------------------------------------------
 
 	FIXME: Unsupported at this time, but may run under Cygwin talking to
 	COM1 through the Cygwin virtual serial port bridging.
 
 
+Basic use of pilot-link conduits
+--------------------------------
+
+	On modern systems you probably use a USB connection to your Palm device.
+	For this it is recommended to use the standard Linux kernel modules 
+	"usbserial" and "visor", which usually must be loaded first. On Debian
+	systems i.e. this looks as follows:
+
+		$ sudo modprobe -a usbserial visor
+
+	Then you can use all pilot-link commands, always with specifying a port.
+	Note that you must press the HotSync button on your device, before
+	invoking the command within few seconds at maximum.
+	On Debian systems i.e. type:
+
+		$ <pilot-link-command> -p /dev/ttyUSB1 [options..] [arguments..]
+
+	Some rare devices may prefer `ttyUSB0`.
+	For special cases and details see the chapter below.
+
+
+USB Notes
+---------
+
+	Please see doc/README.usb for more detailed information on
+	configuring your system to use USB-enabled Palm handheld devices
+	using the standard Linux "visor" kernel module.
+
+	If you would like to try the new libusb code, please see
+	doc/README.libusb for details on how to get that working properly.
+
+
 Some usage notes about pilot-link
 ---------------------------------
-	
+
 	read-ical and sync-ical will only run if you have ical-2.x installed
 	and in the path.
-	
+
 	sync-plan is a full syncronization program, though it has some
 	interesting quirks and requirements. You must run netplan from
 	plan-1.6.1 (probably available at
@@ -293,16 +347,16 @@ Some usage notes about pilot-link
 	moment.  Sync-plan leaves a file, that has a name starting with
 	"pilothash", in the current directory. This file must be present for
 	all future syncs between that plan database and that Palm.
-	
+
 	As sync-plan is a work in progress, please contact me with any
 	problems.
-	
+
 	The default connection rate is 9600 baud. You are welcome to try
 	higher baud rates (19200, 38400, or 57600) by setting the PILOTRATE
 	environment variable, but various machines have various limitations.
 	(Be careful about 38400 on a Linux box if you've been using setserial
 	to change the multiplier.)
-	
+
 	pilot-mail (which requires a Palm with the new Mail application, as
 	well as sendmail and/or a POP3 server) is still in the experimental
 	stage.  Run with an argument of '-H' for help. While I don't expect
@@ -314,34 +368,14 @@ Some usage notes about pilot-link
 	If you wish, you may easily change the default settings (pop host,
 	password, etc.) for pilot-mail by editing the top of pilot-mail.c, as
 	well as by setting the environment variables indicated in its help.
-	
+
 	Scott Grosch's "validate" program is included, and can be made via
 	'make validate', but it may not be of use to anyone but Scott.
 
 
-Debugging notes
----------------
-
-	Please see doc/README.debugging for more detailed information
-	describing how to debug pilot-link's core protocols and interfaces.
-	Debugging pilot-link will allow us to make pilot-link work better on
-	new devices and with new applications.
-
-
-USB Notes
----------
-
-	Please see doc/README.usb for more detailed information on
-	configuring your system to use USB-enabled Palm handheld devices
-	using the standard Linux "visor" kernel module.
-
-	If you would like to try the new libusb code, please see
-	doc/README.libusb for details on how to get that working properly.
-
-
 FreeBSD Notes
 -------------
-	
+
 	Please see doc/README.freebsd for more detailed information on
 	setting up pilot-link to work with FreeBSD systems. In FreeBSD, you
 	may have to set your ACLOCAL_FLAGS="-I /usr/local/share/aclocal/"
@@ -360,32 +394,41 @@ FreeBSD Notes
 
 Embedding information
 ---------------------
-	
+
 	As of 0.5.0, the headers in pilot-link have been rearranged slightly
 	so that it should be easier and more reliable to use the libpisock.a
 	library in external applications.
-	
+
 	If you want to use the pilot-link portability layer (configured via
 	autoconf), then include pi-source.h. Otherwise, do not touch this
 	file, as it sets up a mildly complex environment.
-	
+
 	For all normal operations, simply include the obvious files (pi-file
-	for pdb and .prc file access, pi-dlp for DLP sync functions, etc.). 
+	for pdb and .prc file access, pi-dlp for DLP sync functions, etc.).
 	pi-macros contains the portable byte-access routines.
 
 
+Debugging notes
+---------------
+
+	Please see doc/README.debugging for more detailed information
+	describing how to debug pilot-link's core protocols and interfaces.
+	Debugging pilot-link will allow us to make pilot-link work better on
+	new devices and with new applications.
+
+
 Reporting Bugs
 --------------
-	
+
 	Please visit https://github.com/desrod/pilot-link/issues to report any
 	bugs you find with pilot-link. From there, any issue reported can be
-	updated, audited, commented on, and resolved. You can also attach 
+	updated, audited, commented on, and resolved. You can also attach
 	other relevant items to each bug report, to help the team solve the
 	issues or add the features you have requested.
-	
-	PLEASE NOTE 
+
+	PLEASE NOTE
 	-----------
-	
+
 		Please check the existing issues in the system FIRST
 		before reporting your bug. There may be an identical
 		report from another user that matches your issue. If
@@ -415,7 +458,7 @@ License notes
 	language bindings (Perl, Python, Java, and Tcl) are licensed for use
 	under the LGPL. For more information, please see COPYING.LIB included
 	in this source tree.
-	
+
 	All contained source is the copyright of its author(s). Please see
 	the copyright notices in the individual files for more information on
 	their individual copyrights.