Cruisers Forum
 


Join CruisersForum Today

Reply
 
Thread Tools Rate Thread Display Modes
Old 07-01-2016, 19:23   #61
Registered User
 
rgleason's Avatar

Join Date: Mar 2012
Location: Boston, MA
Boat: 1981 Bristol 32 Sloop
Posts: 9,421
Re: Opencpn 4.1.1108 Documentation

I've fixed the bad links from the beginning of OpenCPN User Manual all the way through to the end of Advanced Features.

What remains left to do is FAQ and Links (with the exception of those that I may have missed.) One more pass should do it.

====

David, Good. A couple of comments, then to bed.

"OS Install details" how about "Installing OpenCPN under Different Operating Systems",
--We are limited in length in the menu to the left. Maybe just "Installing" in the left menu.
Then add in the right document "under Different Operating Systems"?
Quote:
Windows
Mac OS
Linux
Ubuntu
Fedora
Dedicated Marine OS
--OK
Quote:
Move Configure Ubuntu PPA, ---> under Ubuntu
Move Install Linux Plugins ---> Plugins
Move OpenGL under ---> Options_Charts
Move Low Power Systems --->Advanced Features
Portable OpenCPN under --->Advanced Features
--Good


Quote:
I think this reads better as Chart Options ditto Connection Options.
--Every time you change the underlying URL names to make them more rational you have to go through ALL the documentation and change any links. I just did it and it is not fun and takes awhile. I might not have gotten all of the links.
--We can change the menu names, but need short ones, because multiple lines make it more difficult to read. Options > Chart and is how you get to what is being described, similar to Toolbar > Options > Charts.

Do still want to switch them?

Quote:
As another general principal topics under a single heading should be sorted with most likely to be used first by the inexperienced.
I thought this yesterday, thinking about the new user, and did it that way, but did not like the result, because it will hamper the new user as the are learning and referring to the documentation. So today I went back and reorganized and improved it, so that the structure after
"Getting Started" basically mimics the organization of the program.
IE:
Getting Started
MenuBar
Toolbar ButtonsRight Click Menu
Options_Charts
Options_Connections
Advanced Features
FAQ
Links
Edit User Manual


Quote:
Before I go further is this what you are looking for?
Yes, please.

Thanks!
__________________

__________________
rgleason is online now   Reply With Quote
Old 07-01-2016, 19:56   #62
Registered User
 
rgleason's Avatar

Join Date: Mar 2012
Location: Boston, MA
Boat: 1981 Bristol 32 Sloop
Posts: 9,421
Re: Opencpn 4.1.1108 Documentation

It cut me out while editing. Sorry

====

David, Good. A couple of comments, then to bed.

"OS Install details" how about "Installing OpenCPN under Different Operating Systems",
--We are limited in length in the menu to the left. Maybe just "Installing" in the left menu.
Then add in the right document "under Different Operating Systems"?
Quote:
Windows
Mac OS
Linux
Ubuntu
Fedora
Dedicated Marine OS
--OK
Quote:
Move Configure Ubuntu PPA, ---> under Ubuntu
Move Install Linux Plugins ---> Plugins
Move OpenGL under ---> Options_Charts
Move Low Power Systems --->Advanced Features
Portable OpenCPN under --->Advanced Features
--Good. I jumped the gun in checking the links. By moving these to Plugins, Advanced etc, We may want to rename the URL for the page for organization... so then we would have some bad links in all the text again. I could leave the URL the same, with "Start_low-poer-system, etc. I'll have to check it, but we will move them!


Quote:
I think this reads better as Chart Options ditto Connection Options.
--Every time you change the underlying URL names to make them more rational you have to go through ALL the documentation and change any links. I just did it and it is not fun and takes awhile. I might not have gotten all of the links.
--We can change the menu names, but need short ones, because multiple lines make it more difficult to read. Options > Chart and is how you get to what is being described, similar to Toolbar > Options > Charts.

Do still want to switch them?

Quote:
As another general principal topics under a single heading should be sorted with most likely to be used first by the inexperienced.
I thought this yesterday, thinking about the new user, and did it that way, but did not like the result, because it will hamper the new user as the are learning and referring to the documentation. So today I went back and reorganized and improved it, so that the structure after
"Getting Started" basically mimics the organization of the program.
IE:
Getting Started
MenuBar
Toolbar ButtonsRight Click Menu
Options_Charts
Options_Connections
Advanced Features
FAQ
Links
Edit User Manual


Quote:
Before I go further is this what you are looking for?
Yes, please.

Thanks!
__________________

__________________
rgleason is online now   Reply With Quote
Old 08-01-2016, 01:55   #63
Registered User
 
Aart K.'s Avatar

Join Date: Oct 2015
Location: the Netherlands
Boat: Kelt 800
Posts: 111
Re: Opencpn 4.1.1108 Documentation

Rick, David and other people working on the documentation,

Maybe this is the time to do things something “completely different”. Last year, as a complete newby for OpenCPN, the English (American) Manual in 4.0 seemed very complicated to me. And confusing because many old images are used. Some images with version number 3.xx.xx in top. That is why I decided to do it in a different way.

I am working on the documentation for the 4.2 version in Dutch. I made a completely different lay-out. Have a look at OpenCPN Handleiding It is a bèta version of the Dutch manual. Is not published yet because I am waiting for some new images but in a few days after 4.2 is launched it will be ready. And this can be implemented in the installation in the file “doc” like it is now done.

OK, this example is in Dutch but maybe it inspires you.

Aart
the Netherlands
__________________
Aart K. is offline   Reply With Quote
Old 08-01-2016, 08:09   #64
Registered User

Join Date: Jan 2007
Location: Minneapolis
Boat: Irwin 37 CC
Posts: 660
Re: Opencpn 4.1.1108 Documentation

Rick,

" Maybe just "Installing" in the left menu.
Then add in the right document "under Different Operating Systems"?" OK

"Options > Chart and is how you get to what is being described, similar to Toolbar > Options > Charts." This is OK but this style must be discussed before using and include the > so it is clear we are using shorthand. I think this would be the only 2 titles with this style and I think adding the > will cause the same problem as changing to chart options. The reason for doing this is semantic. Options don't have Charts; Charts have Options. You cold say Options for Charts but you have the same problem. Give me a good description of how to find and change the references and I'll do it.

I like the outline
"Getting Started
MenuBar
Toolbar Buttons
Zooming
Scaling Charts
Marks and Routes
Chart Status Bar
Chart Info
GPS Setup and Status
Display Orientation
Auto Follow
Options Setting
Vector Display
AIS
Tides and Currents
Route Manager & Gpx
Ship Track
Help?
Night Navigation
Plugins
Man OverBoa
Right Click Menu
Options_Charts
Options_Connections
Advanced Features
FAQ
Links
Edit User Manual"

I don't particularly like the suggestion (in Getting Started) of reading the whole manual before starting. I'm 75 and I probably would it but if I were 25 I might quit and go home.

We must make sure that there is enough documentation in Getting Started to get Opencpn installed and then links to the Chartloader PI and GPS Connections. Most problems occur in these two areas.. There should be a strong suggestion to use the default Chartloader file structure. I deleted my mess and started over with the default.

David
__________________
David Kester
Pegasus IV
wdkester is offline   Reply With Quote
Old 08-01-2016, 08:45   #65
Registered User
 
rgleason's Avatar

Join Date: Mar 2012
Location: Boston, MA
Boat: 1981 Bristol 32 Sloop
Posts: 9,421
Re: Opencpn 4.1.1108 Documentation

Quote:
Rick, David and other people working on the documentation,

Maybe this is the time to do things something “completely different”. Last year, as a complete newby for OpenCPN, the English (American) Manual in 4.0 seemed very complicated to me. And confusing because many old images are used. Some images with version number 3.xx.xx in top. That is why I decided to do it in a different way.

I am working on the documentation for the 4.2 version in Dutch. I made a completely different lay-out. Have a look at OpenCPN Handleiding It is a bèta version of the Dutch manual. Is not published yet because I am waiting for some new images but in a few days after 4.2 is launched it will be ready. And this can be implemented in the installation in the file “doc” like it is now done.

OK, this example is in Dutch but maybe it inspires you.

Aart
the Netherlands
Aart, fabulous job. Your outline gives me some good ideas. To bad we couldn't have yours in English as an alternative, for those who would like. I wonder if Google would translate it? I tried it but google needs an https secure webpage to translate.
https://translate.google.com/transla...dex.htm&anno=2

I tried using https://www.opencpn.aartkorstjens.nl etc on google translate and it did not work.
If you could have a secured (encrypted) https:// access to the pages then google translate would work.

There are lots of Outline Ideas I like including the Menubar - expanding it to show each of the selections with snapshots and others. I will be referring to it... like the index too!

Great job
__________________
rgleason is online now   Reply With Quote
Old 08-01-2016, 09:28   #66
Registered User
 
Aart K.'s Avatar

Join Date: Oct 2015
Location: the Netherlands
Boat: Kelt 800
Posts: 111
Re: Opencpn 4.1.1108 Documentation

Quote:
Originally Posted by rgleason View Post
To bad we couldn't have yours in English as an alternative, for those who would like
There are about 140 .html pages. If you (or somebody else) can give me content (in English) and correct images page by page, maybe we (together) can make an English version.

Aart
__________________
Aart K. is offline   Reply With Quote
Old 08-01-2016, 09:48   #67
Registered User
 
rgleason's Avatar

Join Date: Mar 2012
Location: Boston, MA
Boat: 1981 Bristol 32 Sloop
Posts: 9,421
Re: Opencpn 4.1.1108 Documentation

Quote:
" Maybe just "Installing" in the left menu.
Then add in the right document "under Different Operating Systems"?"
OK
OK will start that and get it roughed out.

Rick:
Quote:
-"Options > Chart and is how you get to what is being described, similar to Toolbar > Options > Charts."
David:
Quote:
This is OK but this style must be discussed before using and include the > so it is clear we are using shorthand. I think this would be the only 2 titles with this style and I think adding the > will cause the same problem as changing to chart options. The reason for doing this is semantic. Options don't have Charts; Charts have Options. You cold say Options for Charts but you have the same problem.
Ok, David, you have some good points. I was thinking about it last night too.



Give me a good description of how to find and change the references and I'll do it.

Quote:
I like the outline
"Getting Started
MenuBar
Toolbar Buttons
Zooming
Scaling Charts
Marks and Routes
Chart Status Bar
Chart Info
GPS Setup and Status
Display Orientation
Auto Follow
Options Setting
Vector Display
AIS
Tides and Currents
Route Manager & Gpx
Ship Track
Help?
Night Navigation
Plugins
Man OverBoard
Right Click Menu
Options_Charts
Options_Connections
Advanced Features
FAQ
Links
Edit User Manual"
Did you want to flatten it? See: Toolbar Buttons | Official OpenCPN Homepage
All Under "Toolbar Buttons"
Quote:
Zooming, Scaling Charts, Marks and Routes, Chart Status Bar, Chart Info, GPS Setup and Status, Display Orientation, Auto Follow, Options Setting, Vector Display, AIS, Tides and Currents, Route Manager & Gpx, Ship Track, Help?, Night Navigation, Plugins, Man OverBoard
Did you want to move these out to the first level? I will wait for your response before doing this.

Quote:
I don't particularly like the suggestion (in Getting Started) of reading the whole manual before starting. I'm 75 and I probably would it but if I were 25 I might quit and go home.
Yes, of course, Sorry, That was me! trying to get people to read. But of course we have a lot of work to get this whittled down and focused on installation for each OS and stuff not duplicated. Not too much, but just enough! If something is too complicated we need to simplify and delete too. Agreed.

Quote:
We must make sure that there is enough documentation in Getting Started to get Opencpn installed and then links to the Chartloader PI and GPS Connections. Most problems occur in these two areas.. There should be a strong suggestion to use the default Chartloader file structure. I deleted my mess and started over with the default.
Good suggestions. I like that. Yes, get them up and running and using it with charts Pronto! and Simple.

David, I have written how to Add Pages.
I have mentioned the URL that can be added at the bottom.
How we use that URL might be critical. I know that if you change it, all the links in the documentation change, and you have to go back and fix them by hand. It is not really a true CMS (content management system). I think it is drupal, because there is an error that says drupal, but it is probably an old version.

Right now I have a problem and a question
--nobody has answered about using that URL.

Somewhere I saw that the documentation would not export unless the reference was identical. --I'd like to know exactly what that means and be able to test "export" the documentation to make sure it works and learn
.

Next is how to
change the outline, and what the pitfalls are. That is relatively easy.
When you are logged in. At the top, there is
VIEW EDIT OUTLINE REVISIONS
To Edit the current page. Pick "Edit".
To Change the current page outline location. Pick "Outline:.
To View the changes of the current page. Pick "View">

Taking the Toolbar Buttons Page. When you pick Outline there will be
Book: OpenCPN User Manual (dropdown) - Keep our pages in this area.
Parent Item: Opencpn User Manual (dropdown) - Use this to move pages around.

What I know about Adding a new page and URLs
When you Add a new page, it is given an arbitrary page name (a number) with the path to the file and this URL can be used for linking to in the text.
Go to Toolbar Buttons Page and select Edit at the bottom you will see
URL Path Setting: toolbar-buttons
I entered that URL in there...Actually I changed what it was, so that all similar page file names would be in the same place when you looked at the directory of files. In so doing I messed up all the links to that page, but since we are reorganizing the manual and I've gone through all the links now, we should be back to normal.... I think.

For example, what I did for the URL's under toolbar-buttons was toolbar_zoom-in-out
toolbar_scaling-charts
toolbar_marks-and-routes
toolbar_chart_status-bar
toolbar_chart-Info
toolbar_gps-setup-and-status

etc.

Now I am hoping that this does not mess up our "Exporting" capability, but since I have never done it and there is no instruction how to do it, WE ARE GOING TO BE XXXXX!

So that's about what I know so far. I have written Thomas but not heard back.



__________________
rgleason is online now   Reply With Quote
Old 08-01-2016, 10:22   #68
Registered User
 
rgleason's Avatar

Join Date: Mar 2012
Location: Boston, MA
Boat: 1981 Bristol 32 Sloop
Posts: 9,421
Re: Opencpn 4.1.1108 Documentation

Ok David, I pretty much changed the Getting Started as you suggest.

I should have said

How to Change the Outline
Select Outline
Book: Keep the same Opencpn User Manual
Parent: Select from the dropdown, and it will move the page.
Below the Book and Parent selections there is Weight
To get the page in the right order, select the right weight
-15, -14, ...-1, 0 , 1, 2, ...15
The first item on top I usually set as -15, then next as -14, etch.
__________________
rgleason is online now   Reply With Quote
Old 08-01-2016, 11:07   #69
Registered User
 
rgleason's Avatar

Join Date: Mar 2012
Location: Boston, MA
Boat: 1981 Bristol 32 Sloop
Posts: 9,421
Re: Opencpn 4.1.1108 Documentation

David,
I changed Options > Charts to just Charts
Also Options > Connections to just Connections

Under Getting Started I made the new pages but have not copied from the Plain Text Screen in the "Installing Opencpn" page to the newly added pages for various OS Installations.

We have some choices to make about where to put the main Chart Installation page because it is essentially the Toolbar > Options > Charts Tab Chart Files Tab | Official OpenCPN Homepage

This same page also handled installation of charts!
So I have put a jump page called Chart Installation

Which will get users to Chart Files Tab
I think it still makes a lot of sense to keep it here but could be convinced otherwise. What do you think? We are going to have to chase down some redundancies for Installing Charts.

---
Also you asked where Plugins has been put.
It is under Toolbar > Plugins because that is the way it is accessed and the actual programs command structure is being used to organize the content of this Manual!

Since it is a frequent access item, and since we had it as an item in the main directory for v4.0, I am going to put a very simple jump page there to the full Toolbar_plugin section. Hope that will take care of that.

======
I have not changed many of the URL pages in doing this, but we are still going to have to check all the URL's again which is a pain but its going to be necessary.

Also I still don't have an answer on the URL question and Exporting the Manual for the program.
__________________
rgleason is online now   Reply With Quote
Old 08-01-2016, 11:09   #70
Registered User
 
rgleason's Avatar

Join Date: Mar 2012
Location: Boston, MA
Boat: 1981 Bristol 32 Sloop
Posts: 9,421
Re: Opencpn 4.1.1108 Documentation

David
Feel free to change the outline,
and Add pages, trying to use URL names system we have started.

However I would not change the old URL names unless you find it necessary, as the links with change and I don't know about Exporting yet.

See how the Plugins jump page works here.

http://opencpn.org/ocpn/plugins
__________________
rgleason is online now   Reply With Quote
Old 08-01-2016, 15:54   #71
Registered User
 
rgleason's Avatar

Join Date: Mar 2012
Location: Boston, MA
Boat: 1981 Bristol 32 Sloop
Posts: 9,421
Re: Opencpn 4.1.1108 Documentation

David and others who are working on the Organization of the Wiki, there are several
Posts in a separate thread that you should be aware of.

Thomas Cagney wrote in response to my questions:
Quote:
Export, go to Download OpenCPN | Official OpenCPN Homepage scroll down to "Live Snapshot". This is basically the "final" documentation (I believe this is v4.0). For links to work internally in this document the names of the links must match the headings in the wiki for each page, to the letter. Just check out how it's done now. This is all down to a php script that Will wrote (and that I've never seen). This may lead to some, sometimes awkward, workarounds to make the writing understandable.
My response:
Quote:
So the names of the links (this is the url we type at the bottom of the editor page in view mode) must match exactly the Title or Heading that appears in the menu to the left (page edit mode, Title of the page).

Every page's URL must match the TITLE of the page exactly.
Also we are going to have to check every document link again. Not good news.

What I suggest is
1. Get the outline right.
2. Get the Page Titles clear and agreed to.
3. Change the URLs to match the Titles.
4. Check every link in all pages and paste in the proper one.

The last to steps can be done towards the end, but I think we should be changing the URL to match the TITLES as we work.
This will cause links in the docs to break until we get to fixing them yet again. This is a bit backwards, and maybe clever... but now I remember the problem from before!
It is my assumption that Will runs the PHP script from the server and there is no way we can 'test' it to see if we have the links right?

Also Ptulp responded to the other thread "Wiki Links must match the Heading for export"

Quote:
What I get from the mail from Thomas in the OpenCPN RC 4.1.1301 Release thread is that the link references in the document should exactly match the names in the Table of Contents.

I found a problem in the Getting Started part:
Original:
Getting started using OpenCPN consists of 5 basic steps:
  1. Read the rest of Getting Started , Basic Features and Advanced Features to learn about the program.
  2. Install OpenCPN
Here step 2 says Install OpenCPN but the Table of Contents says Installing OpenCPN
This caused that in the document the link was not handled correct and still pointed to the online document i.s.o the export document.
When I edited the online document to Installing OpenCPN and ran the export again, the problem was solved.

The other problem I saw that in step 1 Getting Started was including a space and comma, so it was not processed correctly.

The problem still there is in step 1 Basic Features , this phrase cannot be found in the Table of Contents as it refers to the Options Settings use.
================

Also I just found these in the DEVELOPMENT MANUAL

Beta Development Change Log Change log is always available in one place.

Upating the User Manual Thomas and others wrote this. (Just Moved to Top level)

Edit the User Manual Document I started.

User Manual Export
OpenCPN User Manual
__________________
rgleason is online now   Reply With Quote
Old 08-01-2016, 16:29   #72
Registered User
 
rgleason's Avatar

Join Date: Mar 2012
Location: Boston, MA
Boat: 1981 Bristol 32 Sloop
Posts: 9,421
Re: Opencpn 4.1.1108 Documentation

Ptulp adds

Quote:
As a quick check you can hover over a link in the export document and see if it is pointing to something like:
opencpn.org/ocpn/ocpn_manual_export/#<linktext
__________________
rgleason is online now   Reply With Quote
Old 08-01-2016, 16:54   #73
Registered User

Join Date: Jan 2007
Location: Minneapolis
Boat: Irwin 37 CC
Posts: 660
Re: Opencpn 4.1.1108 Documentation

I moved the the basic Downloader PI documentation to Charts>Options>Chart Downloader Tab.

I hate to move it(especially duplicate it); but there's also "Plugins_included_chart-downloader". Maybe put the advanced documentation here.

Rick,
"The problem still there is in step 1 Basic Features , this phrase cannot be found in the Table of Contents as it refers to the Options Settings use."
Earlier today I edited the text to make these work.
__________________
David Kester
Pegasus IV
wdkester is offline   Reply With Quote
Old 08-01-2016, 17:02   #74
Registered User
 
rgleason's Avatar

Join Date: Mar 2012
Location: Boston, MA
Boat: 1981 Bristol 32 Sloop
Posts: 9,421
Re: Opencpn 4.1.1108 Documentation

Ptulp is correct. The situation is much better than I thought.

1. The php script takes all the wiki pages and converts them to a single HTML page using internal links (that is the # sign at the beginning of the internal link).
2. The php script is dynamic and always updating the changes we make, so we can just check the Opencpn Wiki Export page to see if the link is now working there. If it does not work, go back and fix it in the Edit window.
3. Also after checking the automatically exported wiki, Toolbar Buttons page, Toolbar Buttons | Official OpenCPN Homepage I found that most of the links are working! This is great news. It is not as complicated as I thought.
  • The Heading of the page is used to create the automatic Menu items to the left.
  • The Outline mode is used to move a page to a new location.
  • In Edit mode, the URL Path Settings below the edit area, are used create and edit at distinct URL. This URL does NOT have to be exactly the same as the Heading. However if you change it, you may have to fix any links that have already been created.
  • The php code for the Wiki simply takes the content at the URL for a page copies it to a single export page and adds an internal link which uses the #[Heading] as the link, so the URL is no longer used in the Exported Wiki.
  • So go ahead and open the Exported Wiki and look at the links. - As a quick check you can hover over a link in the export document and see if it is pointing to something like:
    opencpn.org/ocpn/ocpn_manual_export/#<linktext
So based on this understanding, I think the overall Outline is coming along ok and we do have some flexibility to make the URL's a meaningful organization tool. We just have to keep moving forward and will have to check all the links, for each document as we are working on them, and do a final sweep right at the end.

Thanks Thomas and ptulp for the links and pointers.

Quote:
Where is the Export Wiki?
Found at the bottom
of Downloads page

OpenCPN Documentation
Live snapshot of Wiki->User's Manual
__________________
rgleason is online now   Reply With Quote
Old 08-01-2016, 18:17   #75
Registered User

Join Date: Jan 2007
Location: Minneapolis
Boat: Irwin 37 CC
Posts: 660
Re: Opencpn 4.1.1108 Documentation

For my next task I would like to go thru Options>Chart and update all the screens that fail to show Chart Downloader tab
__________________

__________________
David Kester
Pegasus IV
wdkester is offline   Reply With Quote
Reply

Tags
documentation, enc, men, opencpn

Thread Tools
Display Modes Rate This Thread
Rate This Thread:

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are Off
Pingbacks are Off
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
OpenCPN Beta test 4.1.1108 Release bdbcat OpenCPN 694 14-01-2016 08:10
Beta test 4.1.1108 on ARM NahanniV OpenCPN 9 07-12-2015 09:09
Value of USCG documentation? Wahoo Sails Rules of the Road, Regulations & Red Tape 18 07-09-2008 14:13
federal documentation/state requirements?? cadye Rules of the Road, Regulations & Red Tape 3 24-08-2005 13:23
USCG Documentation delay? alicemacinnes Rules of the Road, Regulations & Red Tape 2 14-12-2004 07:12



Copyright 2002- Social Knowledge, LLC All Rights Reserved.

All times are GMT -7. The time now is 06:44.


Google+
Powered by vBulletin® Version 3.8.8 Beta 1
Copyright ©2000 - 2017, vBulletin Solutions, Inc.
Social Knowledge Networks
Powered by vBulletin® Version 3.8.8 Beta 1
Copyright ©2000 - 2017, vBulletin Solutions, Inc.

ShowCase vBulletin Plugins by Drive Thru Online, Inc.