Help File Location, Contents, Additions and Corrections

[dacust]

Cool. Thanks for all your work.

But one more thing, originally that was a link to Inland Waters Resources

EDIT: Sorry, the editor automatically formatted that link. But it'd be fine for the link to look like that. But probably better like Dave had it originally, just dacust.com (since it's not just inland waters anymore), but with the URL in the link above.

-dan

[gmau]

robster,
Sorry I haven't tried to answer some of your questions sooner.

Originally Posted by robster

Hi Gordon,
I've just discovered OpenCPN and have been reading the help file. Is there any thought being given to making it more accessible to someone who hasn't used nav software before? I am taking the Coast Guard Aux class right now so am a true newbie. It would be great if there were advice, too.
For example, a section on raster vs vector charts, whether to use one, the other, or both, and where to download them. For USA-based boaters, a tutorial on getting NOAA charts would be great.

My first impression was 'the help file would be bigger than the program' if the help file contained everything.
It's true, the learning curve is rather steep. Newbies just have to go thru the learning curve. Do searches on the internet.

Some of the things I can think of are :
Charts = You use to go to the store to buy them. The NOAA site isn't too bad for getting them down loaded. You can select by region or individual charts, just updates and other features. There are third parties that will sell you a CD of those same files for about $25. Then you have to learn how to read them.
GPS = Hand held, fixed, puck, usb, serial, and more. Then it's how to hook them up to communicate with the other nav equipment. What protocol, speed and how to set up the nav equipment can give a person a gray hair. Then you have to learn how to use the nav equipment.
It goes on for a lot more!
Once you get some experience it won't be too bad.

Originally Posted by robster

Minor details for correction:
In "Getting Started with OpenCPN" the text beginning with "First we need to look at the bottom of the screen," is highlighted in red and is hard to read (at least on my laptop). It would look better as normal text.

It's explained in a previous post. The bottom line is the red highlighted are additions and will go away. It's to give everyone a chance for their input. It's even worse for me because I'm color blind. I can't even begin to tell the colors of LEDs. The one led with different colors are the worst. The guy who invented them should be shot!

Originally Posted by robster

The line "On the bottom is the Status Bar(s). Activated from 'Tool Box-Etc.-Show Status Bar'." Should read "Activated from Tool Box - Settings - Navigational Data - Show Status Bar."

I adoptive the convention that things in the single quotes are mouse clicks. Tool Box-Etc.-Show Status Bar' would be a mouse click for Tool Box, another for Etc and the last for Show Status Bar. Thanks for catching the error. Etc should not be in that string.

In your suggestion I have the following comments.
- Activated from Tool Box ---Should be click on the wrench Icon
- Settings ---Settings is the first to come up so no mouse click is needed
- Navigational Data ---It's the heading for the 'Show Status Bar. No click needed.
- Show Status Bar ---Requires a click to activate or di-activate the Status Bar.

Originally Posted by robster

Explain the acronym GPX.

I don't know what the letters stand for. I do know its a way of saving way points, tracks and routes to be imported and exported to different programs.

Originally Posted by robster

Grammar correction: "These allows you to zoom in and out on the chart currently being displayed for more detail. " Sould read "these allow you..."

I'm not a writer! English comp and writing were my worst subjects. Now I wish I had paid more attention or had a stricter teacher. It will take me about two hours to finish this reply. Word processors are great.

Originally Posted by robster

"The AIS function makes it is easy to interrogate targets.
It will calculate and display CPA and TCPA." What are CPA and TCPA?

Again I don't know what the letters stand for. I think they are NMEA 183 protocol sentences.

Originally Posted by robster

Can you explain how charts and currents work? I haven't gotten that far yet...

I had the same question as you do. I found out clicking the base of the current arrow it critical.

I hope I've answer some of your questions.

Keep the suggestions coming!

Gordon

[dacust]

CPA=Closest Point of Approach
TCPA=Time to Closest Point of Approach.
GPX=GPs eXchange format - the file extension for a standard type of GPS waypoint files.

[gmau]

Originally Posted by dacust

Cool. Thanks for all your work.

But one more thing, originally that was a link to Inland Waters Resources

EDIT: Sorry, the editor automatically formatted that link. But it'd be fine for the link to look like that. But probably better like Dave had it originally, just dacust.com (since it's not just inland waters anymore), but with the URL in the link above.

-dan

It wasn't even close to the above in my inbox in Hotmail!

I can work on spelling out the link to

http www dacust com/inlandwaters/

I had to delete the punctuation. My web site for the help file has the same problem

I'll just have to work at it until it comes out to your liking.

[dacust]

That's it.

Or just click on the link and then copy it from the URL bar.

Thanks!

-dan

[Ashoreschool]

Nicely done help file. Just downloaded OpenCPN. Looking forward to trying it out
Thanks

[gmau]

psyches
rhoel_asia
dacust


After 30 years of dealing with Main Frames, PCs and the internet, I look at things in a very simplistic approach. I've had access to most of Microsoft software at no cost or very little cost. It's gotten to the point that I have better places to spend my dollars rather than in up grades to any software. That's the reason I've tried to migrate to OpenOffice and OpenSoftware. I feel, if you aren't using any software to make money, all software should be free or at a nominal charge.


Dacust has a really full plate with the core development of OpenCPN. I can see how rhoel_asia's help file got left out of the last release. As a result, the help file should be made available by other means. That's why I created a web site for the help file. I also created a thread so all users would have a chance for input into the help file. It also makes it easier for new users to find and get help.


The contents of rhoel_asia's file is pretty much the same as the one I created. My file has more info on the recent changes for the new release. I've just added the following:


Indexing and Table of Contents are not fully implemented. You can use the Ctrl-f keys to find text. Try using searches in Wikipedia and Google for more information on specific topics.


Within the last two days I highlighted my help file viewed in IE, copied it to Word and got a file size of about 160 KB. I've been meaning to ask if this is too big to include with the next release? Is there a target date for the next release? I looked at rhoel_asia's file sizes and got the 37 kb for the text and 633 kb for the png files. 160 kb to 670 kb size is a no brainer to me. Go with the smaller file. I have to admit that I don't fully understand how Java and CSS fit into the help file.


I feel everyone should have an input to the help file. There should be some control. If there isn't the help file could grow very large with too much detail.


For now, I'm going to wait for directions from you and others.
I'm willing to help!


Gordon

[Psyches]

Originally Posted by gmau

Dacust has a really full plate with the core development of OpenCPN. I can see how rhoel_asia's help file got left out of the last release. As a result, the help file should be made available by other means. That's why I created a web site for the help file. I also created a thread so all users would have a chance for input into the help file. It also makes it easier for new users to find and get help.

bdbcat is the lead developer and father of OpenCPN. There are others that have been very active contributors (e.g. you mention dacust).

I think having a website is a great idea - especially one that is clearly and permanently associated with OpenCPN, like opencpn.org as Rhoel suggests. Having the help on the site as a 2nd source sounds great too. But this is a ships navigation application, and ships underway typically cannot maintain web access.

Within the last two days I highlighted my help file viewed in IE, copied it to Word and got a file size of about 160 KB. I've been meaning to ask if this is too big to include with the next release? Is there a target date for the next release? I looked at rhoel_asia's file sizes and got the 37 kb for the text and 633 kb for the png files. 160 kb to 670 kb size is a no brainer to me. Go with the smaller file. I have to admit that I don't fully understand how Java and CSS fit into the help file.

Size is a concern of mine, but my concern is more about content and maintainability than size. For scripting, if anything it'd be Javascript, not Java. CSS helps facilitate multi-tool (open tool) maintenance, whereas Word tends to produce content that is best re-edited in Word. A quick look at the raw html should show that (again I have an older version of Word so YMMV). I am not a doc expert at all, and I'm not doing the work, so I list my concerns then defer to you and others.

I feel everyone should have an input to the help file. There should be some control. If there isn't the help file could grow very large with too much detail.

I completely agree, and I think bdbcat's (Dave's) perspective and involvement is paramount. I hope we can move further towards an OpenCPN ecosystem, where Dave doesn't have to do all high and low-level planning, all integration, all release steps, all monitoring, etc. We're not there yet.

For now, I'm going to wait for directions from you and others.
I'm willing to help!

Gordon, your experience and help is very much appreciated. I've given a few comments FWIW, and now I defer.

Mark

[Rhoel_Asia]

Originally Posted by gmau;367364[FONT=Times New Roman, serif

I looked at rhoel_asia's file sizes and got the 37 kb for the text and 633 kb for the png files. 160 kb to 670 kb size is a no brainer to me. Go with the smaller file. I have to admit that I don't fully understand how Java and CSS fit into the help file.[/FONT]

PNG's and size.
I used pngs for the quality (because the file was designed to be on the local harddisc and not each page transmitted over the net. jpgs can just as easily be used and the total file-size falls. I converted the images to 80% jpgs (and removed a 241kb source file not used on the page) and the total size became 142kb - this included 2 large screenshots at 800 x 468 pixels. Including text and images, the total content became 180kb, more than manageable over the net (which was not the original brief).

CSS:
CSS is actually very simple and web101: The idea is to have all the style definitions in a single reference and use them many times across pages or the entire site. The HTML code then uses the style reference by class name It means you can change the look of the website very quickly, a one line change. With inline code, you can't ... thousands of lines have to be changed just to get a title from red to blue. If you want to change it again later, you have to go back and change a thousand lines of code again.

Here is a working example - its teh same line taken from the gmau site and from my original code.

This is HTML (originally derived from Word):

<P style="MARGIN-BOTTOM: 0pt"><B><SPAN style="FONT-FAMILY: 'Arial', 'sans-serif'; COLOR: maroon; FONT-SIZE: 13.5pt"><FONT face=Arial>Why should I use it instead of a commercial product?</FONT></SPAN></B></P>

You note its very difficult to read, let alone modify.

The same with CSS:

<div class="heading">Why should I use it instead of a commercial product?</div>

The class="heading" is doing all the work. easy to read, easy to understand.

The actual CSS description, which is written only once is:

.heading {
    color: #800000;
    font-family:Arial, Helvetica, sans-serif;
    font-size: small;
    font-weight: bold;
    border-bottom: solid 1px #800000;
    margin-top: 10px;
    margin-bottom: 8px;
    text-align:left;
    padding-left: 4px;            
}

Its very clean and elegant: Want to change the title colour to blue, no problem, change color: #800000; to #000080; once in one place and all headings will instantly change on the page. Don't like the column-wide red underline, just kill the border-bottom: solid 1px #800000; line.

If the CSS file is kept in an external reference file, then all headings across the site will change.

to understand the problem fully, open gmau and view/page source, you will see a file which is exceptionally difficult to read. To edit is even worse. It's why Web2 uses <div class="style-name> {some lines} </div>. Clean, simple and very economic.

I'm not knocking Gordon's work or efforts but from a web masters point of view, using text direct from Word or OpenOffice is fraught with problems. Compare the text files sizes, the CSS is 38kbs and the gmau code 98kb for almost the same content.

Realistically, when you compare the css vs inline style = "unchangeable code" (and using Gordon's overly harsh comment), it's a no brainer.


JavaScript:
Java and JavaScipt are two totally different languages. Basically, JavaScript is very useful for actively changing page elements in the client's browser, without a page reload. This bandwide and time saving is good for everyone. Currently, there is nothing in the help files which calls for JavaScript: That might change further down the line.

This is an example of Javascript: If a tick box is clicked, it turns a map layer on. If its unticked, it turns the layer and its linked but separate labels layer off.

 if (document.dgmr_menu.cb_borders_districts.checked == true) { 
    map.getLayersByName("District Boundaries")[0].setVisibility(true); 
}
else {
    map.getLayersByName("District Boundaries")[0].setVisibility(false);
    map.getLayersByName( "District Boundaries Labels" )[0].setVisibility(false); 
}

Don't panic, JavaScript is not compulsory and not something anyone here would be expected to write. But it has its place and the technique very useful. JavaScript is again part of Web2 and a key component in AJAX. For those who are interested JavaScript, Google "tutorial JavaScript DOM".


Personally, for ease of long term development, CSS is the only way to go forward. If you don't, eventually you get to a point where you have to stop and start again from scratch - having done a rebuild commercially on a site, I know how heartbreaking and phenomenally expensive it is to complete.

Be good to get a consensus on this so we can press forward and get the file built.


Rhoel

[cagney]

OpenCPN badly needs a well written help file, including a comprehensive " Read this if you are just starting with OpenCPN" - section. I can see, more or less every day, how newcomers are struggling to extract the relevant information from this discussion forum.
I'm with Rhoel_Asia in this discussion. Rhoel just states facts how a proper web site is structured these days. Just go ahead Rhoel and set up the framework. Then, the rest of us, hopefully including Gordon, can concentrate on the content of the help file.
Of course, as Rhoel describes, his way makes it easier to make the help file look good to.

Thomas

[Rhoel_Asia]

one way forward is this: I am happy with the code and Gordon seems to have the content well under control - that is an area I am weak in at present as I'm without a boat, 4 hours inland etc; I can;t generate all the topics needed.

what seems logical is for me to take the words which Gordon has now and put them into CSS HTML - I have the tools to do it and though its time consuming, I can arrive at a working page faster: The only person who will complain is my girlfriend (but she is in the doghouse for forgetting to tell me she is already married). This will leave Gordon to concentrate on collating the new information.

If Gordon is happy with this arrangement, I'll go look at yola to see how they upload html to the site, do some tests, etc. It should be possible to have the 1.3.5 finished in time for Jan 1st.

Rhoel.

[bdbcat]

Cagney, Rhoel, gmau, etc....

This seems like a good plan to me.

The objective IMHO should be to have a set of HTMLs/CSSs that can be added to the release set for offline viewing. File size considerations are secondary. Whatever looks good IS good. Any solution which relies on an online connection is not really in the spirit of opencpn. Opencpn is optimized for underway navigation and real cruising.

In parallel, we should be looking into a permanent web home for our little village of navigators. I'd like a volunteer to contact the current owner of opencpn.org, and sound him out regarding release of the domain. Changing to an alternate domain name is not desirable, for obvious reasons.
Lets keep in mind that this Web-site effort is (almost) entirely disjoint from the requirement for a useful local help file.

I am planning 1.3.6 release in the first week of Jan. I cruise to Bahamas in Jan/Feb/Mar, with spotty internet access. So there is a target.....

Dave

[Psyches]

Originally Posted by bdbcat

I'd like a volunteer to contact the current owner of opencpn.org, and sound him out regarding release of the domain.

Thanks for speaking up on all this, Dave.

I'm already trying to contact Yme. If I fail, my next step is to contact him via some of his business connections. The next step would be as Rhoel suggested, via the GoDaddy then ICANN route.

I won't object if others volunteer as well.

Mark

[Psyches]

Originally Posted by Psyches

Thanks for speaking up on all this, Dave.

I'm already trying to contact Yme. If I fail, my next step is to contact him via some of his business connections. The next step would be as Rhoel suggested, via the GoDaddy then ICANN route.

I won't object if others volunteer as well.

Mark

Update: Yme has responded, so we're moving along.

[Wester]

I belive he is a member on this forum

Leif