#include documentation

I'm trying to figure out how to use #include (as it doesn't seem to be working "intuitively").

I have my .h include files in the same directory as the sketch and have #include statements with < >.
Someone told me I should uses quotes " " but they still don't work although the .h files open up in tabs when I open the sketch.

Where do the include files go?
When should I use " " or < > ?
Can I use a path?
Is there a library?
How do I reference the library with includes?

The documentation on http://arduino.cc/it/Reference/Include is rather sparse.

When you say they don't work, what specifically is the error message you are getting?

Probably best to just point you to the discussion where I am trying to work out this problem.

http://arduino.cc/forum/index.php/topic,108647.0.html

The code, errors and my efforts to fix them are documented there.

They tell me it's probably not the code but a problem with the includes... which I don't seem to be using properly.

mspohr:
The documentation on http://arduino.cc/it/Reference/Include is rather sparse.

Yep.

Doing multifile programs in the Arduino IDE is not easy - despite the fact that it is good programming practice. On the other hand, most Arduino projects are only 50 or 200 lines. For a single project getting to big, just write several .PDE/.INO files, and have them in the same sketchbook folder. When you compile the IDE will compile them as one file. (The IDE also "cheats", compared to pure "C" - it rearranges the functions so they are defined before being called - thus the order of the PDE files is irrelevant). No need to use .h

I have found that you must have a subfolder called LIbraries in your Arduino sketch folder, and in there you can have folders wich contain a .h and .cpp files. This is a proper library. The IDE looks both in this "user-library" folder and in the system library folder (and I think also in a subfolder to the compiler). As far as I know it makes no difference if you use " or <>

In the link you provided you already received what I believe to be the correct answer.

You are attempting to use someone else's library, yet instead of placing that library in the libraries subdirectory of the sketchbook (which is not the same as your sketches folder) you appear to have placed them in your sketches folder which is why the IDE is finding the .h file but I suspect it is not also opening the .cpp file? The IDE is configured to search a predetermined set of paths (which is different on different platforms) and it expects to find files in that path.

Assuming you on windows and you are using two libraries; OneWire and DallasTemperature, the files will need to be placed in

c:/users//my documents/Arduino/libraries/OneWire

and

c:/users//my documents/Arduino/libraries/OneWire

Then use

#include <OneWire.h>
#include <DallasTemperature.h>

Now if you are just starting out the libraries sub-directory described above will not exist and you will need to creating BEFORE attempting to place the libraries there.

I read some of your other thread:

The Arduino IDE doesn't seem to have a problem finding the .h files since it opens them up in separate tabs with the sketch window automatically when I open the sketch.

This means they are in your sketch directory. In this situation you must use quotes, i.e:

#include "MySketchDirFile.h"

Brackets: '<' and '>' are used to specify common files, or in the IDE's case files that are accessible to other sketches.

#include <LibraryHeader.h>

The IDE does non standard things which enforces the use of <>.
When compiling the IDE copies your sketch files and any other files specified in '#include <>' to a temporary folder for compilation.

So ensure all libraries are included using <>, and even more so, you must include any libraries that your libraries include ( strange I know ).
This is to ensure that the files your libraries use are copied to the temporary directory.

So... I'm afraid I'm still confused.
I have the .h in " " since they are in the same directory but they don't seem to be recognized by the compiler... so I assume that the "non-standard" stuff requires the use of < > but it doesn't seem to work with these either.

Should I use both?

#include <"OneWire.h"> ???

Effectively it doesn't matter if you use "" or <>

The problem is that you have placed these files in the wrong place. See my answer in either of your threads for instructions on how to fix that problem (or the reference manual for libraries).

Libraries don't belong in your sketch directory.
Remove all files that aren't part of your sketch out of the sketch folder ( libraries ).

Place libraries in the libraries folder, if you have them there already, just delete all the copies you made elsewhere.

Should I use both?

#include <"OneWire.h"> ???

No that is wrong.
Do not use <> for files in your sketch directory, and do not put libraries in your sketch directory either.

It seems to me that there should be some straightforward way to handle #include but I am having a very difficult time figuring it out and the documentation is very sparse.

So far, very helpful people have told me that I need to have a "libraries" folder in the same folder as my sketches. So on my Mac, the Arduino IDE puts my sketches in a folder: Documents/Arduino
I have my sketches in this folder... the first is a sample project "Alarm" which is in: Documents/Arduino/Alarm
I created a folder: Documents/Arduino/libraries
I put the OneWire .h files in: Documents/Arduino/libraries/OneWire
I have these lines in the "Alarm" sketch:

#include <OneWire/OneWire.h>
#include <OneWire/DallasTemperature.h>

From what I have been told, this should work, but it doesn't. I get these errors:
Alarm:1: error: variable or field 'printAddress' declared void
Alarm:1: error: 'DeviceAddress' was not declared in this scope
Alarm:2: error: variable or field 'printTemperature' declared void
Alarm:2: error: 'DeviceAddress' was not declared in this scope
... etc.

Is there some clear, complete documentation somewhere on how to use the #include ?

You have the same question posted to a thread in Programming, which is probably the best location. And for which you have received the answer that I believe you need.

Thanks to everyone I finally got the #include sorted out. I will post my suggested documentation clarifications here in this section in the hopes that someone updates the documentation.

Thanks to everyone for your help.
I finally got the code to successfully verify.

I would suggest that the #include documentation (#include - Arduino Reference) be updated... something like:

#include
You can add libraries from third parties by downloading and unzipping the libraries into a folder called "libraries" which should be created in the same folder as your sketches. (On a Mac, the default is: Documents/Arduino/ and the folder should be created Documents/Arduino/libraries). There should be a separate sub-directory of libraries for each contributed library (Documents/Arduino/libraries/yourlibrary). These sub-directories should contain .h and .cpp files.

After you restart the Arduino IDE, these libraries will show up under the menu Sketch - Import Library - Contributed section.
(I don't know where the other built-in libraries are but I guess I don't need to know.)

You can use these libraries by choosing the menu option Sketch - Import Library and choosing a library. This will put the statement at the start of your sketch:
#include <yourlibrary.h>