STR #1604: Explicit reference to installed "examples" directory would be useful

STR #1604

Application:	FLTK Library
Status:	1 - Closed w/Resolution
Priority:	2 - Low, e.g. a documentation error or undocumented side-effect
Scope:	3 - Applies to all machines and operating systems
Subsystem:	Documentation
Summary:	Explicit reference to installed "examples" directory would be useful
Version:	1.3-current
Created By:	duncan.gibson
Assigned To:	engelsman
Fix Version:	1.3-feature (SVN: v7731)
Update Notification:	Receive EMails Don't Receive EMails

Trouble Report Files:

No files

Trouble Report Comments:

#1	duncan.gibson 08:50 Feb 15, 2007

When 1.1.8 is released (any day soon :-) there will be a lot of distros that will package it up as RPMs or whatever, and the target users won't see the source code. Appendix I of the installed documentation under Linux now explicitly mentions the "test" directory in the source, but maybe it needs to also refer to the new "examples" directory under the installed documentation tree. Appendix I gives a summary of each of the test programs. It might also be helpful if the summaries contained links to the test program source files. [I presume these links could be generated automatically as part of the installation process, but I don't work with OSX or Win32 so I don't know]

#2	greg.ercolano 10:00 Feb 15, 2007

BTW, feel free to raid my 'cheat' page for things to put in the new 'examples' directory.

#3	matt 10:37 Feb 15, 2007

Thanks for the offer, Greg! I would like to avoid adding new code in any way at this point, because I'd have to add the test program to all IDE's to work correctly. Some of them, I don't have access to, like VisualStudio 7, etc.

#4	greg.ercolano 18:07 Feb 15, 2007

IDEs? Bleh. But I hear ya. I have access to the IDEs, like VS7, but never use them to build my own projects.. I just use them to build FLTK itself. Then I jump to the command line and create a Makefile for my projects instead.

#5	greg.ercolano 22:54 Feb 15, 2007

I suppose one possibility is to post the code examples in the dir, but include a README.txt disclaierm that indicates some files are for copy/paste example use only, and do not build as part of the FLTK compile (yet). In many cases, people only need to see the code to understand it. Then as time permits, you can add them to the default build, and later remove the disclaimer. This will give you (and other folks) time to merge in the IDE build files just because the files are there. Anywho, just a thought.

#6	matt 02:42 Feb 16, 2007

What's needed is a program (we could write that in FLTK, for example ;-) that makes it easy to add more tests and more source files to all IDE's and Makefiles. For most IDE's, that would be easy, but some use silly binary formats that we can't patch easily. This goes along with desperately needed FLTK templates for the IDE's that support templated projects. But since this will be the last iteration of FLTK 1.1, I will file this for 1.2, 2.0 and 3.0... .

#7	matt 02:10 Feb 19, 2007

Duncan, thanks for the original suggestions. Installation is so different on the platforms that we will not be able to create automatic links any time soon. It would probably not work, depending on how the distros pack their rpm's anyway. We do have a text at the top of the file though that suggests downloading the archive from fltk.org if your machine does not come with the source code. I pushed this up to 1.2, even if we may never touch 1.2 itself (who knows), but that way, your request will stay in the database.

#8	duncan.gibson 05:35 Feb 19, 2007

As I mentioned, I don't work with Win32 or OSX so have no idea how the docs are installed. I also work with the source, so I don't know how the various distro RPMs install the docs either. If creating the links to the source files is not as simple as I thought, why not just add something to the Appendix I header along the lines of: Source code for the examples described in the documentation may already be available under the documentation files on your system. If not, or if the FLTK archive you received does not contain a "test" directory...

#9	engelsman 16:58 Mar 19, 2009

I'm moving this to 1.4 because it's clearly not a "must have" for 1.3 although I'm also tempted to close/withdraw it completely if it will be as difficult to implement as Matt suggests...

#10	engelsman 13:02 Nov 09, 2010

I (duncan.gibson == engelsman) recently added a paragraph to the Examples Source Code appendix of the 1.3 Programming Manual that mentioned that additional examples were available in 'examples'. Based on the other comments here about the difficulty of creating links to the source files themselves, that part is a non-starter. Therefore, unless someone else has some constructive comments, I shall close this in the next few days as "fixed in r7731"

#11	engelsman 09:33 Nov 12, 2010

Fixed in Subversion repository.