search

k4kfh / ZephyrCab

Drive a model train with prototypical controls, realistic behavior, and simulated physics; uses JMRI's WebSockets interface for layout connection
http://k4kfh.github.io/ZephyrCab
GNU Affero General Public License v3.0
10 stars 4 forks source link

Should not install in JMRI installation directory #19

Closed rhwood closed 7 years ago

rhwood commented 7 years ago

The JMRI project does not recommend users install anything in the JMRI installation directory -- its not likely to be retained in a future update.

In /docs/site/userguide/installation-guide/, you should recommend that users install the ZephyrCab in their configuration profile in the same location (i.e. in [path-to-profile]/web/locoThrottleJS )

k4kfh commented 7 years ago

Thanks for the heads up. Those docs are rather old and outdated; my apologies, I had totally forgotten to update that.

ZephyrCab (formerly LocoThrottleJS, hence the folder names on that page) is totally client-side HTML/CSS/JS, so I was only recommending installing it in JMRI's directory so that users wouldn't have to run their own web server and could use the existing JMRI web server. I totally understand why I need to remove that, but what should I replace it with? Will JMRI continue to allow custom webpages to be added to the web server, or will users need to use an external web server for ZephyrCab?

Also, on a less related note, how'd you come across this project? I'd love to work more closely with you and the rest of the JMRI team on this, I just didn't feel like it was at a functional enough point to bring it up to you guys yet.

rhwood commented 7 years ago

ZephyrCab (formerly LocoThrottleJS, hence the folder names on that page) is totally client-side HTML/CSS/JS, so I was only recommending installing it in JMRI's directory so that users wouldn't have to run their own web server and could use the existing JMRI web server. I totally understand why I need to remove that, but what should I replace it with? Will JMRI continue to allow custom webpages to be added to the web server, or will users need to use an external web server for ZephyrCab?

The JMRI web server will work, but the ZephyrCab needs to be installed in the user's JMRI configuration profile, not inside JMRI's install directory itself. The JMRI web server looks first in the web directory in the configuration profile for a requested resource, and if not found, then looks in the JMRI installation. The path to the current profile can be found in JMRI by opening the Help->Locations menu item.

Also, on a less related note, how'd you come across this project? I'd love to work more closely with you and the rest of the JMRI team on this, I just didn't feel like it was at a functional enough point to bring it up to you guys yet.

You opened an issue with us against the JSON server. I found this by clicking on your username in the issue.

k4kfh commented 7 years ago

The JMRI web server will work, but the ZephyrCab needs to be installed in the user's JMRI configuration profile, not inside JMRI's install directory itself. The JMRI web server looks first in the web directory in the configuration profile for a requested resource, and if not found, then looks in the JMRI installation. The path to the current profile can be found in JMRI by opening the Help->Locations menu item.

Awesome, thanks. I will update docs ASAP. Currently reinstalling Windows and Linux on my daily driver thanks to some spectacular NTFS corruption, but I'll make a quick commit to remove the parts about the JMRI web server, then fix it later.

You opened an issue with us against the JSON server. I found this by clicking on your username in the issue.

Oh, okay. What did you think of the README? Obviously the docs it links to are a spectacular failure and I willl fix that once I have a steady machine to operate on, but did the README do a decent job describing what the software does? I'm in high school and this is my first "real" software project, so I'm kinda learning as I go here. I appreciate your help.

rhwood commented 7 years ago

The README is reasonable. I'd make the introduction statement to any project be as terse and thorough as possible, but the specific tech is not needed.

So instead of:

ZephyrCab is an HTML/CSS/JavaScript app that is designed to simulate prototypically accurate controls for model trains. It communicates with your layout using JMRI's JSON WebSockets servlet, which is built into the JMRI web interface.

I'd leave out the details that call out technologies you don't require your audience to be familiar with (HTML/CSS/JavaScript/JSON/WebSockets) and let the details filter in under the installation and usage sections:

ZephyrCab is a web app that simulates prototypically accurate controls for model trains, built on the JMRI model train control software.

(There is a broken image though that should be fixed--generally these jump out at potential users.)

k4kfh commented 7 years ago

I went ahead and removed the old docs and replaced them with a super simple quickstart guide. I will update it more later. Thanks for the suggestions!