Mailing-List: contact dev-help@river.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@river.apache.org
Received-SPF: softfail (nike.apache.org: transitioning domain of pats@acm.org
 does not designate 74.124.218.126 as permitted sender)
Message-ID: <54D81E24.9010305@acm.org>
Date: Sun, 08 Feb 2015 18:40:36 -0800
From: Patricia Shanahan <pats@acm.org>
User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64;
 rv:31.0) Gecko/20100101 Thunderbird/31.4.0
MIME-Version: 1.0
To: dev@river.apache.org
Subject: Re: River-examples project
References: <E7200224-F01B-49C7-991D-A7A98823E638@stratuscom.com>
 <54D72D7C.202@acm.org> <75CE62CF-E94E-406F-8CF1-B5BE7526F668@stratuscom.com>
In-Reply-To: <75CE62CF-E94E-406F-8CF1-B5BE7526F668@stratuscom.com>
Content-Type: text/plain; charset=windows-1252; format=flowed
Content-Transfer-Encoding: 8bit

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 <pats@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.
>>>
>