Documentation suggestion (drivers for OSX) and format question

[Dirk Hohndel]

Amit Chaudhuri <amit.k.chaudhuri at gmail.com> writes:

> Hi,
>
> I have some proposed text to help Mac users get started with subsurface.  I
> * think * the right way to submit is to edit the user-manual.txt file in a
> git branch and then send in a diff.  If someone can confirm, I'll follow
> through with this and any further submissions.

Yes, that would be the way to do it.

> I'm curious to know how I should handle line ending/word wrap.  If I use a
> carriage return at the end of each line, will I be messing up anything?

The tools are supposed to get this right - but sometimes they
don't. Still, you won't be messing anything up :-)

> I'm also wondering if the proposed text should be inline in the "Import new
> dives from your divecomputer" section just after the bullet on Mac, or
> maybe referenced from there and placed in its own Appendix?

I think an Appendix would be a great idea.

> Text is written based my own experience getting started on subsurface.  I
> think I risk a bit of an "everyone knows this stuff" reaction from
> experienced users, but this is aimed at the others.  In my dive club I
> think only one person (a VLSI chip designer) would have gotten an OSX
> installation up and running on the old docs.  Comments welcome..as ever.

I think you are absolutely right about this. Documentation is one of our
very weak areas. I know from casual conversations that many people who
try Subsurface quickly give up as it is too hard to use for the novice.

> DOC EXTRACT START
>
> Working out which driver to use for a Mac requires for a particular dive
> computer may require some experimentation. The libdivecomputer website
> provides
> a useful point from which to start:
> http://www.divesoftware.org/libdc/drivers.html. It lists a number of sites
> for
> manufacturers of the serial to usb chips which provide the necessary
> conversions.  Typically, one then needs to navigate to the relevant sub
> page for
> "drivers" and then for "VCP drivers."  VCP stands for Virtual Com Port. You
> want
> VCP rather than D2XX drivers. Make sure to download the correct version for
> your
> particular version of OS X.

Can you list links to the sites for some of the more common dive
computers? Clearly Suuntos are very popular, as are Mares, Aeris and
Uwatec. If you could pick a couple and list direct links, I think that
would be very helpful.

With enough volunteers I'm sure we could provide a full list of links
and keep them updated :-)

> These can be downloaded to the Mac and installed in the usual way.  Details
> on
> how to install on OS X 10.8 differ from earlier versions due to the new
> security
> functions. Put simply, unless the driver has been digitally signed in an
> approved way OS X will block the installation. You can either make some
> changes
> to your system security settings or manually override the block. The latter
> seems more sensible and only involves control-clicking the installation
> package
> and answering some standard dialogs. You can find a high-level explanation
> of
> the new security features from apple here:
> https://www.apple.com/osx/what-is/security.html.

This seems almost too high level. Can you walk the reader through the
type of dialog to expect?

> Until you have the correct driver installed, subsurface will not connect to
> your
> dive computer. If you try one VCP driver and it still doesn't work, try the
> next
> manufacturer until it does.  If you run out of drivers and still can't get
> things working perhaps its time to contact us via the subsurface mail
> lists.

:-)

This is a great start!

/D