[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