If you feel confident about a change to the examples, feel free to edit the files and commit it.
Otherwise, or if you’re making general suggestions, we may as well just reply to this thread and I’ll collect the required changes later. Cheers, Greg Trasuk. On Feb 8, 2015, at 9:40 PM, Patricia Shanahan <p...@acm.org> wrote: > On a meta-issue, should we be editing the results and ideas into a file in > SVN, or plan to review these threads later? > > I hope we can end up with full, well-tested instructions for a few different > environments. > > On 2/8/2015 7:48 AM, Greg Trasuk wrote: >> >> Thanks for trying this out… Some answers below… >> >> Cheers, >> >> Greg Trasuk >> >> On Feb 8, 2015, at 4:33 AM, Patricia Shanahan <p...@acm.org> wrote: >> >>> Thanks very much for getting this done. >>> >>> I am playing naive new user. I checked out the svn files, and viewed >>> README.md. Note that it might be nice to provide it as a README.txt as >>> well - a user who is getting the code from SVN may not be familiar with >>> Github conventions. >>> >> >> I was thinking that README.anything was likely to get the user’s first >> attention, and that the md text was still readable as text. But I see your >> point - it’s trivial to include a README.txt as well. >> >> >>> I think the instructions need a bit more information: >>> >>> "To build the examples, simply unpack the source distribution of >>> 'river-examples', >>> and then, >>> >>> cd river-examples >>> mvn install >>> mvn site" >>> >>> What am I supposed to unpack? How do I unpack it? >>> >> >> Instructions need clarification here - you pulled it from cvs, so it’s not >> “the source distribution”, > > which would have been in a “.tgz” file. >> > > Actually SVN, not CVS, but same principle. > > A readme file should assume the user reads it at the first point at which the > readme becomes accessible, no earlier. Is the readme going to be inside the > .tgz, or outside it? What is a .tgz? > > >>> It should say where to type this. Windows command tool? Cygwin shell? >>> Unix/Linux shell? I assume I need a JDK, but that should be specified. >>> Which JDK versions? >>> >>> I skipped the "unpack" part of the instructions and used Netbeans. I >>> created a new Maven project from existing POM, and built it. I then used >>> right click on project, Custom, Goals to run "install" and "site". That >>> all worked fine, including smoothly downloading from Maven Central. >>> >>> I opened the index.html file that resulted. Clicking on e.g. the >>> "browser" link got "Firefox can't find the file at >>> /C:/river-examples/target/site/browser/index.html.". The browser >>> directory contains a file "browser-start.png" but no "index.html”. >> >> Ahh… Need for more instructions here. Netbeans bundles an older version of >> Maven that doesn’t understand Markdown text in the site generation. What >> you need to do is install the latest Maven from ‘maven.apache.org’ and >> configure Netbeans to use it. I’ll add a note to the instructions (although >> this is really Maven setup). For your immediate use, >> >> - Download Maven 3.2.5 from http://maven.apache.org/download.cgi. If you’re >> on Windows, download the zip file. If on Linux/Unix, get the “.tar.gz”. >> - Unpack it to a convenient directory (Windows: right-click on the zip and >> select “Extract all”. OSX: Just open the tar.gz file. *nix: should be >> something like ‘tar xvzf apache-maven-3.2.5.bin.tar.gz >> /usr/local/apache-maven-3.2.5 >> - In Netbeans, select Preferences (OSX: Netbeans —> Preferences. Windows: >> Tools —> Options) then select the “Maven” tab) and then set the Maven Home >> field to point to your local installation. >> > > For Windows, it is Tools -> Option ->Java -> Maven > >> Then, I suspect you’ll need to do a Custom —> clean install site. > > Did that, followed by the "install" and "site" goals. There were several > warnings. Would you like the console output, or are they expected? > >> >> I suppose the smart thing to do is just publish the examples documentation > > to the River Web site when we release it -that would replace the “Getting > started” page. >> > > Yes, I see the end point of this exercise as a much better "Getting started" > page. > >> >>> >> >>> Thanks again for your efforts. >>> >>> Patricia >>> >>> On 2/7/2015 6:27 AM, Greg Trasuk wrote: >>>> Hi all: >>>> >>>> This doesn’t seem to have gone through the mail system yesterday, so >>>> I’m posting again. Apologies if we eventually have a storm of >>>> similar messages. >>>> >>>> Hi all: >>>> >>>> Finally finished the examples project. Please review and comment. >>>> >>>> You can get it from svn at >>>> https://svn.apache.org/repos/asf/river/river-examples/river-examples/trunk >>>> >>>> My thinking is that a new user trying out the examples will start >>>> with the read me file at: “README.md” (formatted as markdown so that >>>> in case someone is looking at the github mirror, they’ll see it on >>>> the front page of the project). So, if one or more of you could >>>> checkout the project and begin by following the README.md >>>> instructions, that would give us a feel for the “new-user” >>>> experience. >>>> >>>> I’m picturing that we should be able to release the examples project >>>> fairly quickly, and then start trying to publicize it. Also, we can >>>> add more advanced examples as time goes on (e.g. event notifications, >>>> transactions, JavaSpaces, web app client, etc). >>>> >>>> Thanks, >>>> >>>> Greg Trasuk.
