Getting at the Help manuals

[John Hill]

I have just downloaded Audacity 1.3.9, and installed as directed. All seems to be well so far, apart from one point.
If I select Help/QuickHelp (in web browser) or Help/Manual (in web browser) all I get is "You do not appear to have 'help' installed on your computer.
Please view or download it online."
So I followed the link and found that the manual *should* be on the .dmg. It is not (and it wasn't in 1.3.8 either).
I followed the instructions for downloading and installing the manual (download .zip file, unpack into a folder called help, put the help folder in the Audacity folder in Applications).
This still does not work.
I can get at the manual via the index.html file in the Manual folder, but this is less convenient.
Has anyone found out how to make the manual accessible from within Audacity? What am I doing wrong?
I have an Intel iMac 7.1, using System 10.5.8.
John.

[steve]

I've got the same issue on Linux.
I've contacted one of the developers to ask for advice on this.

[Gale Andrews]

John, I replied you to your e-mail on the same topic sent to [email protected] Does the Manual open if you place a folder called "help" (containing at the next level a folder called "manual", and inside that the "images, "manual" and "skins" folders and the html files) inside the Audacity installation folder?

Same question to Steve, except I've tested this twice on Ubuntu so I know Audacity does see the "help" folder at usr/local/share/audacity. What you need to do is create a folder called "help", then put the "manual" folder that the extraction utility gave you inside "help". Step 1 in the instructions on the front page of the Manual do try and explain this. I've changed the wording slightly to stress the help > manual structure is required.

The problem is that on Windows (users of which we defer to because they usuaIlly need help the most), most file extraction utilities will take "help.zip" and produce a folder called "help" with the "manual" folder inside that. That's perfect for dropping into the Audacity installation folder. But the default Ubuntu archive manager extracts into a "manual" folder without putting that inside a folder bearing the name of the zip folder (that is, "help" in this case). I think that is far more logical, but it's not what happens on Windows.

I assumed given the Windows 1.3.8 zip had nearly 50000 downloads from us compared to under 2000 for the 1.3.8 Linux minimal tarball, and given almost no Linux distros have a 1.3.8 or later package, that the priority was to target the zip structure at Windows users. It's unfortunate our Mac developer left out the help in the 1.3.9 dmg but 1.3.10 should include it. If experience shows we need to structure the zip so that "manual" is inside a "help" folder we can change it, of course.


Gale

[steve]

Same question to Steve, except I've tested this twice on Ubuntu so I know Audacity does see the "help" folder at usr/local/share/audacity.

Made a folder called "help", and put the extracted "manual" folder in it - works now. Thanks.

I think the wording could be made a little more clear in the paragraph below the one you have updated:

On '''Windows''' or '''Mac OS X''', place the "help" folder inside the folder containing the Audacity program. In an Audacity installation, this would usually be under "Program Files" on Windows or "Applications" on Mac OS X.
On '''Linux''', the "help" folder should usually go in /usr/share/audacity if Audacity was installed from a repository package, or /usr/local/share/audacity if you compiled Audacity from our source code.

When I read the (new) instructions I did the same as I did the first time - that is to skim read down to the paragraph that starts "On Linux" and assume that the "help" folder being referred to is the extracted contents of the zip file. Without reading the preceding paragraph carefully (about making a "help" folder if one is not created automatically), then it is easy to miss that step.

So how about something like:

On '''Linux''', the installation folder is usually /usr/share/audacity/ if Audacity was installed from a repository package, or /usr/local/share/audacity/ if you compiled Audacity from our source code. Create a folder in the audacity installation folder and name it "help", then extract the "manual" folder from the zip file into the "help" folder.

Alternatively, would it not be possible for the Audacity installation to create the empty "help" folder during Mac/Linux installation?

[John Hill]

John, I replied you to your e-mail on the same topic sent to [email protected] Does the Manual open if you place a folder called "help" (containing at the next level a folder called "manual", and inside that the "images, "manual" and "skins" folders and the html files) inside the Audacity installation folder?

Snip...

Gale

As I said in my e-mail reply to you, this does NOT work on my iMac. The help folder is inside the Audacity folder, at the same level as Audacity itself, and the Manual folder is inside this help folder. AFAIK the contents of the manual folder are OK and I can access it via the index.html file therein.

John.

[steve]

The help folder is inside the Audacity folder, at the same level as Audacity itself,

I'm not a Mac user, but in the absence of anyone else.....

If you mean that it's in the same folder as the Audacity executable, then that is not where I have it on my (Linux) machine.

I don't know where Macs put things, but in Linux the executable is in a folder called "bin" and not in the "audacity" folder.
The "help" folder goes into the same directory as the "plug-ins" folder and the "nyquist" folder.

It may well be different on Macs (it is on Windows), but I would expect the help folder would be in the same directory as the nyquist folder and the plug-ins folder.
In the instructions it just says that it usually goes in the "Applications" folder for Mac OS X.

I think it's most likely that the help folder is just in the wrong place, but hopefully Gale will be able to shed some light on this. In the mean time you could try experimenting with different locations.

[John Hill]

The help folder is inside the Audacity folder, at the same level as Audacity itself,

I'm not a Mac user, but in the absence of anyone else.....

If you mean that it's in the same folder as the Audacity executable, then that is not where I have it on my (Linux) machine.

I don't know where Macs put things, but in Linux the executable is in a folder called "bin" and not in the "audacity" folder.
The "help" folder goes into the same directory as the "plug-ins" folder and the "nyquist" folder.

It may well be different on Macs (it is on Windows), but I would expect the help folder would be in the same directory as the nyquist folder and the plug-ins folder.
In the instructions it just says that it usually goes in the "Applications" folder for Mac OS X.

I think it's most likely that the help folder is just in the wrong place, but hopefully Gale will be able to shed some light on this. In the mean time you could try experimenting with different locations.

It *is* different on the Mac; the Applications folder contains the Audacity folder, and that contains:
Audacity
help
Languages
LICENSE.txt
modules
nyquist
plug-ins
README.txt
The help folder contains the manual folder.

usr, bin etc. folders exist on the Mac, but they are hidden from normal view.

[Gale Andrews]

It *is* different on the Mac; the Applications folder contains the Audacity folder, and that contains:
Audacity
help
Languages
LICENSE.txt
modules
nyquist
plug-ins
README.txt
The help folder contains the manual folder.

usr, bin etc. folders exist on the Mac, but they are hidden from normal view.

Hi John

I'm not on a Mac either, and we suffer from essentially only having a single Mac developer who has long periods where he is too busy with his "real" job to work on Audacity. The "help" was developed on Windows and for the reasons above may not even have been tested on Mac, however help was included in the previous Mac 1.3.8 Beta and I don't recall any complaints that it could not be found.

I'll see what I can find out, but if you go to Audacity > Preferences: Interface tab and change "Location of Manual" to "From Internet" then you will be able to view the Manual in your web browser just as if Audacity was finding the local version. The only difference will be that it will be the live online version and of course you will need to be connected to the internet.

Koz, do you see any problems accessing the Manual in 1.3.8, or in 1.3.9 if you get the Manual zip file, extract the "manual" folder in the root of the zip into a folder called "help" then place that where you installed Audacity?


Gale

[Gale Andrews]

Made a folder called "help", and put the extracted "manual" folder in it - works now. Thanks.

I think the wording could be made a little more clear in the paragraph below the one you have updated... When I read the (new) instructions I did the same as I did the first time - that is to skim read down to the paragraph that starts "On Linux" and assume that the "help" folder being referred to is the extracted contents of the zip file. Without reading the preceding paragraph carefully (about making a "help" folder if one is not created automatically), then it is easy to miss that step.

So how about something like:

On '''Linux''', the installation folder is usually /usr/share/audacity/ if Audacity was installed from a repository package, or /usr/local/share/audacity/ if you compiled Audacity from our source code. Create a folder in the audacity installation folder and name it "help", then extract the "manual" folder from the zip file into the "help" folder.

I don't want to say that because the "audacity" folder is not the installation folder in the sense of it containing the executable. Looks like the main problem is the Linux eye skimming to the bold text.

I've changed it to:

1. Extract the contents to a folder called "help". Most Windows extraction tools will do this automatically. If your extraction utility produces only a folder called "manual", create a new folder called "help" and place the extracted "manual" folder inside that new "help" folder.
2. Place the help folder in the correct location. On Windows or Mac OS X, it should go inside the folder containing the Audacity program. In an Audacity installation, this would usually be under "Program Files" on Windows or under "Applications" on Mac OS X.
On Linux, the "help" folder should usually go in /usr/share/audacity if Audacity was installed from a repository package, or /usr/local/share/audacity if you compiled Audacity from our source code.

Alternatively, would it not be possible for the Audacity installation to create the empty "help" folder during Mac/Linux installation?

Well that's possible anyway, but it's based on the assumption that Mac and Linux extraction utilities won't create the enclosing "help" folder themselves as they will on Windows. If a utility does produce the help folder, already having that folder in "audacity" could itself confuse novices. And to modify either "audacity" folder, superuser permissions are needed aren't they, so novices would still have to understand that even if the help folder was already created?


Gale

[John Hill]

I'll see what I can find out, but if you go to Audacity > Preferences: Interface tab and change "Location of Manual" to "From Internet" then you will be able to view the Manual in your web browser just as if Audacity was finding the local version. The only difference will be that it will be the live online version and of course you will need to be connected to the internet.

Gale

After a bit of experimentation, I found the right place and made the change - so I can get at the Quick Help and the Manual OK now. I'm on broadband so getting at it should not be a problem.
But it would be nice to find out why the local manual doesn't work as it should and get it fixed!

John.