Cruisers Forum
 


Join CruisersForum Today

Reply
 
Thread Tools Rate Thread Display Modes
Old 19-05-2010, 04:23   #1
Registered User
 
Netsurfer's Avatar

Join Date: Jan 2010
Location: Cologne, Germany
Boat: Beneteau Oceanis 331
Posts: 557
Coordinate the Help File(s) for OpenCPN

Hi all,

as the new version 2.1.0 becomes more and more stable (thanks Dave and all supporters) , I do believe that it is time to discuss another part of the story, namely the (included) help (file).

The existing one needs to be revised anyway. But the existing solution seems far from being ideal to me. So I want to make some suggestions.

The most important thing in my opinion is that the help is also available in localized versions (as the program itself).

And of course it has to be available offline. For this reason there are 2 suitable formats:
  1. HTML file(s) which requires a browser to be installed
  2. PDF file which requires a PDF-reader
Both should be assumable. And both should be included in the program package.

The question is how to achieve this (best)? Because the content, both text and screenshots, is completely different, it will be best to administer each language version separately, starting with the English version to be used as prototype.

There are some additional requirements that should be complied:
  • if possible there should be only one source (for all formats)
  • collaborate work on the document should be possible
Any suggestions for a suited program/ software?

As to my investigations it would be most ideal if the source data will be in XML format.

Or what do you think about the whole question?

Gunther
__________________

__________________
Netsurfer is offline   Reply With Quote
Old 19-05-2010, 04:58   #2
Senior Cruiser
 
idpnd's Avatar

Cruisers Forum Supporter

Join Date: Sep 2007
Location: Almería, ES
Boat: Chiquita 46 - Libertalia
Posts: 1,551
I concur. I find the easiest solution is to export the wiki(s). If you click on printer-firendly version on the wiki, you get this.

As we could see from the download figures, languages other than English are clearly in high demand, and I feel this should be reflected in the navigation for the main site as well.

Third language sites should get prominent links on the homepage, perhaps little flag thingies in the menu bar, they used to be on the initial page but were displaced by the news page.

I found this comment on the wiki homepage pointing to the French help files:

"Tutorial en français pour petits et grands... par le collectif opencpn/STW (71 pages en français)
Bravo pour le travail
MANUEL :
http://www.stw.fr/Download/OpenCPN/Tuto … -03-30.pdf
DOSSIERS :
Bateaux autour du monde - Sail The World - L'Univers de la grande croisière en voilier - STW"

Naturally visitors who arent logged in can't even see this, so its a bit of a shame really, so perhaps there should be links to external wikis and help files on the initial wiki page as well.
__________________

__________________
sv Libertalia
idpnd is offline   Reply With Quote
Old 19-05-2010, 06:57   #3
Registered User
 
manimaul's Avatar

Join Date: Feb 2008
Location: Seattle, WA
Posts: 416
Quote:
Originally Posted by idpnd View Post
Naturally visitors who arent logged in can't even see this, so its a bit of a shame really, so perhaps there should be links to external wikis and help files on the initial wiki page as well.
idpnd, I think you have full edit access to the website... feel free to implement your ideas. Everyone else is also welcome to make these needed changes. Drop me an email if you need assistance or access.

Will
__________________
Marine Navigation for Android:
http://mxmariner.com
manimaul is offline   Reply With Quote
Old 19-05-2010, 07:00   #4
Registered User
 
Netsurfer's Avatar

Join Date: Jan 2010
Location: Cologne, Germany
Boat: Beneteau Oceanis 331
Posts: 557
Quote:
Originally Posted by manimaul View Post
idpnd feel free to implement your ideas.
Here you'll find some icons for the start ...
country flags icons - Google-Suche
__________________
Netsurfer is offline   Reply With Quote
Old 14-06-2010, 08:16   #5
Senior Cruiser
 
idpnd's Avatar

Cruisers Forum Supporter

Join Date: Sep 2007
Location: Almería, ES
Boat: Chiquita 46 - Libertalia
Posts: 1,551
Hello Gillet,

the idea is currently to get your team's permission to include the existing French manual into the French version of Opencpn. I think it would need to be licensed under the GNU license for that.

If you have problems with html, perhaps another wiki or a subwiki could be created on opencpn.org. The existing French content could be converted so you and your team can work on it there.

Best wishes
__________________
sv Libertalia
idpnd is offline   Reply With Quote
Old 14-06-2010, 11:01   #6
Marine Service Provider
 
bdbcat's Avatar

Join Date: Mar 2008
Posts: 4,884
idpnd...

I like your idea of the wiki export for the short term.

Will you, (or someone) please collect a package of all the required html files and all graphics from the opencpn.org site for inclusion in Release 2.1.0? We need to test it locally without a web connection to make sure there are not any hidden web accesses...

Post it here as a zip, we can all preview it, and I will add it to the release.

I fully support the further discussions regarding manageable framework for localized help files. Its a big job. 2.1.0 needs to release before this could possibly be ready, I'm afraid. But do carry on.....

If we can get a French version tidied up in the next few days, we can include that as well. I can hack a quick locale check to choose the correct help file. German, too, if it is ready.

But the big thing is something/anything that is accurate if incomplete for inclusion in 2.1.0 THIS WEEK.


Thanks
Dave
__________________
bdbcat is online now   Reply With Quote
Old 14-06-2010, 11:27   #7
Senior Cruiser
 
idpnd's Avatar

Cruisers Forum Supporter

Join Date: Sep 2007
Location: Almería, ES
Boat: Chiquita 46 - Libertalia
Posts: 1,551
Hello Dave,

on GPRS at this end, no bandwidth - been missing out on the beta fun even!

Considering the imminent release, I was expecting this to be 2.1.0 +1 really..
__________________
sv Libertalia
idpnd is offline   Reply With Quote
Old 14-06-2010, 11:34   #8
Registered User

Join Date: Dec 2005
Location: WNA
Boat: Dufour 35
Posts: 3,250
Dave

This morning I made such a package available here:Download OpenCPN | Official OpenCPN Homepage
It's a zipped snapshot of the wiki earlier today. It is documenting the 1.3.6 as it is now. I'll probably can find some time to update some of it this week. A snapshot like this can be taken any time, so go ahead and test it, and lets include a snapshot that can be made on Friday, as the documentation. Far from perfect, but it will be sorted out until the first maintenance release.

Thomas
__________________
cagney is offline   Reply With Quote
Old 14-06-2010, 11:54   #9
Registered User
 
Gilletarom's Avatar

Join Date: Mar 2010
Location: France
Boat: 10.50 mètres
Posts: 2,295
Hello,

I have read the post #2.

1° It is necessary to understand that, generally, french mariners do not speak very well english. And, this explain this work.

2° We fabricate at first the html pages. These pages are placed with software "filezilla" at a host of site. Every html page of the site web is "printed" with "pdfcreator" who creates a document pdf. The different documents pdf are pieced in an only global document pdf togetherith with the software "GiosPSM.exe" . With the new html page that I prepare currently, the global document will get soon 90 pages about. One places in uploading at STW, the separated pdf and the global pdf.
It allows the mariners to be able to print the pages of their choice. At every modification of a html page, one must make a pdf and remake the assembling. Somebody must be available for that. It is very demanding. This method is too heavy. It will be very hard to hold a team on the long term to ensure the updating of the French tutorial. And this because the cards S 63 can not be displayed by OpenCPN.

I offer to use the CMS of the site web opencpn.org and to create pages designed for every language. One must give to mariners every nationality the opportunity for write in the pages of their own nationality. One must find and he suffices to find a moderator for every nationality to prevent bad mariners to make foolishnesses.

Best regards,

Gilletarom.
__________________
Gilletarom is offline   Reply With Quote
Old 14-06-2010, 12:45   #10
Registered User
 
Netsurfer's Avatar

Join Date: Jan 2010
Location: Cologne, Germany
Boat: Beneteau Oceanis 331
Posts: 557
Dave,

Quote:
Originally Posted by bdbcat View Post
I fully support the further discussions regarding manageable framework for localized help files. Its a big job. 2.1.0 needs to release before this could possibly be ready, I'm afraid. But do carry on.....

If we can get a French version tidied up in the next few days, we can include that as well. I can hack a quick locale check to choose the correct help file. German, too, if it is ready.

But the big thing is something/anything that is accurate if incomplete for inclusion in 2.1.0 THIS WEEK.
The German version will not be ready/ available to the end of the week. Therefor it is too much work to do - sorry.

But the more important question is/ was, how such a localized help will be implemented or if it will be implemented at all?
Because without knowing this, it does not make much sense to create a localized help.

For the ease of maintenance I propose to separate the html files from images and other stuff, like this e.g.:
Code:
.../OpenCPN/doc/ for the HTML files
.../OpenCPN/doc/images/ for the images
.../OpenCPN/doc/js/ for Javascript files
.../OpenCPN/doc/css/ for CSS files
And as already proposed the naming convention could be something like:
<filename>_en_US.<filetype> or <filename>_de_DE.<filetype>
Maybe it is enough to use the first part of the locale (en, de, etc.)?

The working on the translated help files will start as soon as you tell us how they need to be structured for correct implementation.

I am really looking forward to complete this piece of a jigsaw (I hope this formulation is correct?).

Gunther
__________________
Deutschsprachige Community- und Support-Website unter OpenCPN.de
Netsurfer is offline   Reply With Quote
Old 14-06-2010, 14:22   #11
Registered User

Join Date: Feb 2010
Location: On the go. Not in Prague.
Posts: 4,019
Quote:
Originally Posted by Netsurfer View Post
  • if possible there should be only one source (for all formats)
  • collaborate work on the document should be possible
Any suggestions for a suited program/ software?
DocBook comes to my mind here. The question is whether it's not too techie to discourage the authors who are sailors, not nerds - I personally am afraid it is But as a reward we would get the mature toolchain and almost complete freedom in visual presentation and formats produced.
As a short-to-middle term solution I can hardly imagine anything better than the wiki snapshots.

Pavel
__________________
nohal is online now   Reply With Quote
Old 14-06-2010, 14:43   #12
Registered User
 
Netsurfer's Avatar

Join Date: Jan 2010
Location: Cologne, Germany
Boat: Beneteau Oceanis 331
Posts: 557
Pavel,
Quote:
Originally Posted by nohal View Post
As a short-to-middle term solution I can hardly imagine anything better than the wiki snapshots.
I agree with you.

As the content (text and images) is nearly 100% different for any language, the advantages of an collaborate script are very low. And the wiki is one the easiest possibilities to allow all users to contribute.

The only thing I personally would like to handle in another way as proposed here is the presentation. Just to take the printer-friendly version is imho a bit too simplistic . But for the start better than nothing.

So if we could come to a settlement, e.g. that we use (who wants to) JQuery and that it is located in the (relative) path .../OpenCPN/doc/js/ then everybody can use it and it needs to be there only once. Same with a general CSS file which could be the basis for all language versions.

IMHO it would be most useful to set up these (naming) conventions before starting to create any files.

Gunther
__________________
Deutschsprachige Community- und Support-Website unter OpenCPN.de
Netsurfer is offline   Reply With Quote
Old 14-06-2010, 19:17   #13
Marine Service Provider
 
bdbcat's Avatar

Join Date: Mar 2008
Posts: 4,884
Hello Help Group...

For Version 2.1.0 at least, I can accept Gunther's proposal for naming of document files in the installed package, to wit:

Code:
    .../OpenCPN/doc/ for the HTML files
.../OpenCPN/doc/images/ for the images
.../OpenCPN/doc/js/ for Javascript files
.../OpenCPN/doc/css/ for CSS files
As far as I can tell, opencpn itself need only be concerned with the first on the list, namely ..../OpenCPN/doc

Also, I will create code for 2.1.0 which checks the system locale and selects (if available) the proper help file formatted as a subset of Gunther's suggestion:

Code:
   .../opencpn/doc/help_en_US.html
 or .../opencpn/doc/help_de_DE.html
or whatever, according to the standard locale suffixes.

If the locale specific help file is not available, I will open
Code:
  .../opencpn/doc/help_en_US.html
If that is not available, then I will open a generic help screen directing the user to opencpn.org, as at present Beta.


Further, I think Cagney's idea is good.
We will take a snapshot of the Wiki on Saturday 0000Z and include this with the 2.1.0 Release. It will be named:

Code:
help_en_US.html
Users may "self-install" help files of their choice, consistent with the naming rules above.

In Version 2.1.0 we will have no way for the user to revert to the en_US version after loading, say, a French version, without deleting or renaming the French version. Dialogs are frozen....

What have I overlooked?
Comments?

Dave
__________________
bdbcat is online now   Reply With Quote
Old 15-06-2010, 03:55   #14
Senior Cruiser
 
idpnd's Avatar

Cruisers Forum Supporter

Join Date: Sep 2007
Location: Almería, ES
Boat: Chiquita 46 - Libertalia
Posts: 1,551
I have just been notified by Gillet that he is seeking permission from his co-writers on the French tutorial to republish under GPL.
__________________
sv Libertalia
idpnd is offline   Reply With Quote
Old 15-06-2010, 07:56   #15
Registered User
 
Gilletarom's Avatar

Join Date: Mar 2010
Location: France
Boat: 10.50 mètres
Posts: 2,295
hello,

Quote:
Originally Posted by idpnd View Post
I have just been notified by Gillet that he is seeking permission from his co-writers on the French tutorial to republish under GPL.
I do not understand all in your offers.

The tutorial is, currently, hosted by the personal web site "www.eauxturquoises.fr" of one amongst us.

Questions :
If we integrate the French tutorial in OpenCPN :
- Will it be hosted in "www.openCPN.org" ?
- Will it be hosted in "www.eauxturquoises.fr" ?

Best regards

Gilletarom.

------- En Français ......
Je ne comprends pas tout dans votre proposition.

Actuellement, le site est hébergé dans le site web personnel "www.eauxturquoises.fr" de l'un d'entre nous.

Questions :
Si nous intégrons le tutoriel en Français dans OpenCPN :
- Sera-t-il hébergé dans "www.openCPN.org" ?
- Sera-t-il hébergé dans "www.eauxturquoises.fr" ?


Cordialement



Gilletarom
__________________

__________________
Gilletarom is offline   Reply With Quote
Reply

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
KAP-File Utility Netsurfer OpenCPN 7 23-01-2012 22:30
How to Use these File Types in OpenCPN edsailing Navigation 2 26-04-2010 09:03
Disaster File: Cat vs Powerboat knottybuoyz Off Topic Forum 16 17-03-2009 16:51
File this under... knottybuoyz The Sailor's Confessional 25 20-10-2007 04:41
File a Float Plan GordMay Health, Safety & Related Gear 6 08-02-2006 08:35



Copyright 2002- Social Knowledge, LLC All Rights Reserved.

All times are GMT -7. The time now is 07:53.


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.