[xiph-cvs] cvs commit: positron/doc commands.html common-tasks.html install.html troubleshooting.html user-guide.html
Stan Seibert
volsung at xiph.org
Wed May 28 08:39:08 PDT 2003
volsung 03/05/28 11:39:08
Modified: doc commands.html common-tasks.html install.html
troubleshooting.html user-guide.html
Log:
First draft of user's guide finished.
Revision Changes Path
1.2 +197 -11 positron/doc/commands.html
Index: commands.html
===================================================================
RCS file: /usr/local/cvsroot/positron/doc/commands.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- commands.html 28 May 2003 05:41:36 -0000 1.1
+++ commands.html 28 May 2003 15:39:08 -0000 1.2
@@ -16,11 +16,11 @@
<dl class="option">
-<dt>-m mountpoint</dt>
+<dt>-m mountpoint, --mount-point=mountpoint</dt>
<dd>The directory where the Neuros is mounted. This overrides
whatever is stoed in the configuration file.</dd>
-<dt>-c config_dir</dt>
+<dt>-c config_dir, --config=config_dir</dt>
<dd>The directory where the positron configuration is stored. By
default this is <tt>~/.positron</tt>.</dd>
@@ -28,7 +28,7 @@
The commands are described below.
</p>
-<h2>add</h2>
+<h2 id="add">add</h2>
<p>
Adds files to the Neuros database, copying as necessary. Files that
@@ -61,29 +61,215 @@
Copies sourcefiles to the default music directory. Copy directories
to the default music directory the same way.
</dd>
+</dl>
+<h2 id="del">del</h2>
-<h2>del</h2>
+<p>
+Removes files both from the Neuros database and from the Neuros
+filesystem. Positron will only delete files that have database
+entries, and will remove directories only if they are empty. Positron
+remembers which files have been deleted using this command, and will
+not recopy them during synchronization. Deleted
+files can be recopied using the add command. The
+list of deleted files can also be purged using the
+<tt>--reset-deleted</tt> option to the sync
+command.
+</p>
-<h2>clear</h2>
+<h3>Usage</h3>
-<h2>config</h2>
+<dl class="option">
+<dt>
+positron del [files or directories]
+</dt>
+<dd>
+Searches a list of files and/or directories on
+the Neuros itself (ex: /mnt/neuros/music/rock) to be removed.
+Directories will be recursively searched for music files to delete.
+</dd>
+</dl>
-<h2>help</h2>
+<h2 id="clear">clear</h2>
+<p>
+Clears all entries from the databases. This does not remove any
+files, however.
+</p>
-<h2>list</h2>
+<h3>Usage</h3>
-<h2>pack</h2>
+<dl class="option">
+<dt>
+positron clear
+</dt>
+<dd>
+Clears all databases.
+</dd>
-<h2>rebuild</h2>
+<dt>
+positron clear [database1] [database2] ...
+</dt>
+<dd>
+Clears all entries from a particular database. Valid database names
+are: audio, pcaudio, unidedhisi, idedhisi, failedhisi
+</dd>
+</dl>
-<h2>sync</h2>
+<h2 id="config">config</h2>
+<p>
+Creates or modifies the current configuration interactively. Positron
+will ask you a series of questions and create a configuration files
+based upon your answers. If you already have a configuration, those
+options will be the default answers. See the
+configuration guide for more information.
+</p>
+<h2 id="help">help</h2>
+<p>
+Displays help information about positron commands.
+</p>
+<h3>Usage</h3>
+<dl class="option">
+<dt>
+positron help
+</dt>
+<dd>
+Shows general help about positron and a brief listing of commands.
+</dd>
+
+<dt>
+positron help [command]
+</dt>
+<dd>
+Displays detailed help about a specific command.
+</dd>
+</dl>
+<h2 id="list">list</h2>
+
+<p>
+Lists all of the entries in a database. Only listing the audio
+database is supported at this time.
+</p>
+
+<h3>Usage</h3>
+<dl class="option">
+<dt>
+positron list
+</dt>
+<dd>
+Lists entries in the audio database
+</dd>
+
+<dt>
+positron list [database1] [database2] ...
+</dt>
+<dd>
+List all entries from a particular database. Valid database names
+are: audio, pcaudio, unidedhisi, idedhisi, failedhisi
+</dd>
+</dl>
+<h2 id="pack">pack</h2>
+<p>
+Removes unused space from databases. This is created when entries are
+deleted from the database. Note that packing is automatically done
+whenever you synchronize with positron, so you
+should seldom need to do this manually.
+</p>
+
+<h3>Usage</h3>
+
+<dl class="option">
+<dt>
+positron pack
+</dt>
+<dd>
+Packs all databases.
+</dd>
+
+<dt>
+positron pack [database1] [database2] ...
+</dt>
+<dd>
+Packs all entries from a particular database. Valid database names
+are: audio, pcaudio, unidedhisi, idedhisi, failedhisi
+</dd>
+</dl>
+
+<h2 id="rebuild">rebuild</h2>
+
+<p>
+Recreates the Positron databases from the music tracks found on the
+Neuros. This command completed wipes the Neuros databases and
+rebuilds them from scratch. It is needed if your databases have
+become corrupted. Positron will locate all of the music files already
+on the Neuros and put their entries back into the database as best as
+it can guess. The database of music stored on your computer
+("pcaudio") will cleared and all HiSi clips will be marked as
+unidentified even if they had been previously identified.
+</p>
+
+<h3>Usage</h3>
+<dl class="option">
+<dt>
+positron rebuild
+</dt>
+<dd>
+Rebuilds all of the databases.
+</dd>
+</dl
+
+<h2 id="sync">sync</h2>
+
+<p>
+Synchronizes your Neuros with your music library. This will scan all
+of the syncpoints specified during <a
+href="config.html">configuration</a> for new files and copy them to
+your Neuros. It also scans your Neuros for new FM, microphone or
+line-in recordings and copies them to your, if you specified a
+location for them during configuration.
+</p>
+
+<p>
+Positron remembers which files have been removed with <tt>positron
+del</tt> and which recordings have already been copied to the
+computer. They will not be recopied. You can clear these lists with the options shown below.
+</p>
+
+<h3>Usage</h3>
+
+<dl class="option">
+<dt>
+positron sync
+</dt>
+<dl>
+Synchronizes Neuros with your computer.
+</dl>
+
+<dt>
+positron sync --reset-deleted
+</dt>
+
+<dd>
+Clears the list of deleted tracks. This does not perform
+synchronization. Rerun <tt>sync</tt> without options to
+synchronize.
+</dd>
+
+<dt>
+positron sync --reset-recordings
+</dt>
+
+<dd>
+Clears the list of recordings that have already by copied to the
+computer. This does not perform synchronization. Rerun <tt>sync</tt>
+without options to synchronize.
+</dd>
+</dl>
</body>
</html>
<p><p>1.2 +2 -2 positron/doc/common-tasks.html
Index: common-tasks.html
===================================================================
RCS file: /usr/local/cvsroot/positron/doc/common-tasks.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- common-tasks.html 28 May 2003 05:10:34 -0000 1.1
+++ common-tasks.html 28 May 2003 15:39:08 -0000 1.2
@@ -20,8 +20,8 @@
Neuros, you must unmount it. This is very important because Linux
buffers disk writes, and if you do not unmount before disconnecting,
it is possible to corrupt the Neuros database. (See
-Troubleshooting for what to do if that
-happens.)
+Troubleshooting for what to do
+if that happens.)
</p>
<h2>Adding Files</h2>
<p><p>1.4 +1 -1 positron/doc/install.html
Index: install.html
===================================================================
RCS file: /usr/local/cvsroot/positron/doc/install.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- install.html 28 May 2003 05:10:34 -0000 1.3
+++ install.html 28 May 2003 15:39:08 -0000 1.4
@@ -48,7 +48,7 @@
The next thing to check is that you have the required kernel modules.
</p>
-<ul>
+<ul id="reqmodules">
<li>usbcore - This is required for any USB device.</li>
<li>usb-uhci/usb-ohci - One of these is used depending upon
<p><p>1.2 +63 -4 positron/doc/troubleshooting.html
Index: troubleshooting.html
===================================================================
RCS file: /usr/local/cvsroot/positron/doc/troubleshooting.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- troubleshooting.html 28 May 2003 05:41:36 -0000 1.1
+++ troubleshooting.html 28 May 2003 15:39:08 -0000 1.2
@@ -13,16 +13,75 @@
<h2>Operating System Issues</h2>
-<h3>Problem: I plug my Neuros in to my computer, but it is never
-assigned a device.</h2>
+<p>
+A common problem is that you plug my Neuros in to my computer, but it is never
+assigned a device. There are several possible causes for this:
+<ul class="biglist">
-<h3>Solution</h3>
+ <li>The <a href="install.html#reqmodules">required kernel
+ modules</a> are not loaded. Usually most of them are autoloaded,
+ but there are some systems where <tt>usb-storage</tt> needs to be
+ forced in by hand. The
+ installation guide gives some
+ explanation of how to do this.</li> You can use <tt>lsmod</tt> to
+ verify the modules are loaded and <tt>dmesg</tt> to see if there are
+ any informative kernel messages.</li>
+ <li>Some kernels just don't seem to work. All the correct modules
+ are loaded, but the usb modules just lock up when a Mass Storage
+ device is attached. This can even be a semi-random failure, like
+ lockups during transfers. Unfortunately, there is not much you
+ can do in this case but upgrade your kernel. The latest kernels
+ (>= 2.4.20) seem to work well.</li>
+
+ <li>The firmware on your Neuros might also contribute to this
+ problem. There have been reports that the 1.34 beta firmware causes
+ periodic freezing in Linux during transfers. If this is the
+ firmware you are running, downgrading to the latest stable firmware
+ might help.</li>
+
+</ul>
+</p>
<h2>Database Problems</h2>
+<p>
+Database problems frequently cause the unit to freeze while you are
+using it, or they cause songs to be missing or misfiled. This is
+usually caused when the connection between the Neuros and the computer
+is interrupted during transfer. If the OS freezes, the Neuros
+freezes, or the link cable is disconnected before you unmount the
+device, the database can be corrupted. To fix this, use the following command:
+<pre>
+positron rebuild
+</pre>
+
+This will reconstruct your databases from scratch based upon the music
+files it finds on the Neuros. If problems persist, there is a good
+chance you found a bug in positron. Please report it to us using one
+of the methods outlined below. You will
+probably want to zip up your <tt>WOID_DB</tt> subdirectory on the Neuros and
+include it with the bug report.
+</p>
+
+<h2>Music File Detection Problems</h2>
+
+<p>
+While we've tested positron on a wide variety of MP3s, sometimes we
+stumble across one that is not identified by positron, so it will
+refuse to add it to the Neuros database. Quite often, this is because
+the file is corrupted in some way. Many MP3 players are
+extremely</em> tolerant of damaged MP3s, so some of these files
+are actually playable. At this time, positron has no override switch
+to allow you to force a file to be uploaded. This may or may not be a
+good thing because it is unclear how the Neuros firmware would handle
+such damaged files. Our suggestion is that you try to acquire the
+file from another source or recreate it using a different tool.
+Please contact us about problem files: we are interested in improving
+our detection algorithm if it fails on legitimate files.
+</p>
-<h2>If All Else Fails</h2>
+<h2 id="contact">If All Else Fails</h2>
<p>
If you can't seem to resolve a problem, you have a couple options:
<p><p>1.3 +8 -2 positron/doc/user-guide.html
Index: user-guide.html
===================================================================
RCS file: /usr/local/cvsroot/positron/doc/user-guide.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- user-guide.html 28 May 2003 04:14:47 -0000 1.2
+++ user-guide.html 28 May 2003 15:39:08 -0000 1.3
@@ -4,7 +4,7 @@
<title>Positron User's Guide</title>
</head>
<body>
-<h1>Positron User's Guide</h1>
+<h1>Positron User's Guide: Version 1.0</h1>
<p>
Positron is a synchronization tool for the
@@ -38,8 +38,14 @@
<li>Configuration</li>
<li>Common Tasks</li>
<li>Command Reference</li>
- <li>Troubleshooting</li>
+ <li>Troubleshooting</li>
</ul>
+
+<p>
+If you are interested in positron development or have other questions
+or comments, take a look at our
+contact information
+</p>
</body>
</html>
<p><p>--- >8 ----
List archives: http://www.xiph.org/archives/
Ogg project homepage: http://www.xiph.org/ogg/
To unsubscribe from this list, send a message to 'cvs-request at xiph.org'
containing only the word 'unsubscribe' in the body. No subject is needed.
Unsubscribe messages sent to the list will be ignored/filtered.
More information about the commits
mailing list