From f982d0878429a5634972353281dca24a54b99343 Mon Sep 17 00:00:00 2001 From: Gabriel Jacobo Date: Tue, 29 Jul 2014 09:20:12 -0300 Subject: [PATCH] Rearrange documentation 1) Moves all READMEs to docs/ 2) Renames them to *.md, adds some Markdown with the idea to add a lot more 3) Moves the doxyfile config to doc/ and makes it parse the headers at ../include as well as the md files in docs. 4) Skips SDL_opengl*.h headers from the docs 5) Minor fixes to doxyfile --- README-SDL.txt => doc/README-SDL.md | 0 README-android.txt => doc/README-android.md | 3 +- README-cmake.txt => doc/README-cmake.md | 4 +- README-directfb.txt => doc/README-directfb.md | 3 +- README-dynapi.txt => doc/README-dynapi.md | 1 - README-gesture.txt => doc/README-gesture.md | 1 - README-hg.txt => doc/README-hg.md | 3 + README-ios.txt => doc/README-ios.md | 3 + README-linux.txt => doc/README-linux.md | 3 +- README-macosx.txt => doc/README-macosx.md | 3 +- README-nacl.txt => doc/README-nacl.md | 3 +- README-pandora.txt => doc/README-pandora.md | 5 +- .../README-platforms.md | 3 + README-porting.txt => doc/README-porting.md | 2 + README-psp.txt => doc/README-psp.md | 2 + .../README-raspberrypi.md | 3 +- README-touch.txt => doc/README-touch.md | 1 + README-wince.txt => doc/README-wince.md | 2 + README-windows.txt => doc/README-windows.md | 3 +- README-winrt.txt => doc/README-winrt.md | 3 +- README.txt => doc/README.md | 104 +++++++++++------- {include => doc}/doxyfile | 24 ++-- include/SDL.h | 35 ------ 23 files changed, 106 insertions(+), 108 deletions(-) rename README-SDL.txt => doc/README-SDL.md (100%) rename README-android.txt => doc/README-android.md (97%) rename README-cmake.txt => doc/README-cmake.md (86%) rename README-directfb.txt => doc/README-directfb.md (95%) rename README-dynapi.txt => doc/README-dynapi.md (98%) rename README-gesture.txt => doc/README-gesture.md (96%) rename README-hg.txt => doc/README-hg.md (95%) rename README-ios.txt => doc/README-ios.md (97%) rename README-linux.txt => doc/README-linux.md (96%) rename README-macosx.txt => doc/README-macosx.md (96%) rename README-nacl.txt => doc/README-nacl.md (97%) rename README-pandora.txt => doc/README-pandora.md (89%) rename README-platforms.txt => doc/README-platforms.md (93%) rename README-porting.txt => doc/README-porting.md (96%) rename README-psp.txt => doc/README-psp.md (92%) rename README-raspberrypi.txt => doc/README-raspberrypi.md (96%) rename README-touch.txt => doc/README-touch.md (97%) rename README-wince.txt => doc/README-wince.md (90%) rename README-windows.txt => doc/README-windows.md (94%) rename README-winrt.txt => doc/README-winrt.md (93%) rename README.txt => doc/README.md (54%) rename {include => doc}/doxyfile (99%) diff --git a/README-SDL.txt b/doc/README-SDL.md similarity index 100% rename from README-SDL.txt rename to doc/README-SDL.md diff --git a/README-android.txt b/doc/README-android.md similarity index 97% rename from README-android.txt rename to doc/README-android.md index 3275a1111..c061f95a7 100644 --- a/README-android.txt +++ b/doc/README-android.md @@ -1,5 +1,4 @@ -================================================================================ -Simple DirectMedia Layer for Android +Android ================================================================================ Requirements: diff --git a/README-cmake.txt b/doc/README-cmake.md similarity index 86% rename from README-cmake.txt rename to doc/README-cmake.md index 63c762b53..b5daad908 100644 --- a/README-cmake.txt +++ b/doc/README-cmake.md @@ -1,6 +1,6 @@ +CMake ================================================================================ -CMake build system for SDL (www.cmake.org) -================================================================================ +(www.cmake.org) SDL's build system was traditionally based on autotools. Over time, this approach has suffered from several issues across the different supported diff --git a/README-directfb.txt b/doc/README-directfb.md similarity index 95% rename from README-directfb.txt rename to doc/README-directfb.md index e358278ca..a7b542fa3 100644 --- a/README-directfb.txt +++ b/doc/README-directfb.md @@ -1,4 +1,5 @@ -SDL on DirectFB +DirectFB +======== Supports: diff --git a/README-dynapi.txt b/doc/README-dynapi.md similarity index 98% rename from README-dynapi.txt rename to doc/README-dynapi.md index e28ac59b7..5669fd76e 100644 --- a/README-dynapi.txt +++ b/doc/README-dynapi.md @@ -1,4 +1,3 @@ -================================================================================ Dynamic API ================================================================================ Originally posted by Ryan at https://plus.google.com/103391075724026391227/posts/TB8UfnDYu4U diff --git a/README-gesture.txt b/doc/README-gesture.md similarity index 96% rename from README-gesture.txt rename to doc/README-gesture.md index c2cad7be5..fc8a093c7 100644 --- a/README-gesture.txt +++ b/doc/README-gesture.md @@ -1,4 +1,3 @@ -=========================================================================== Dollar Gestures =========================================================================== SDL Provides an implementation of the $1 gesture recognition system. This allows for recording, saving, loading, and performing single stroke gestures. diff --git a/README-hg.txt b/doc/README-hg.md similarity index 95% rename from README-hg.txt rename to doc/README-hg.md index 32fb8f99d..27396327c 100644 --- a/README-hg.txt +++ b/doc/README-hg.md @@ -1,3 +1,6 @@ +Mercurial +========= + The latest development version of SDL is available via Mercurial. Mercurial allows you to get up-to-the-minute fixes and enhancements; as a developer works on a source tree, you can use "hg" to mirror that diff --git a/README-ios.txt b/doc/README-ios.md similarity index 97% rename from README-ios.txt rename to doc/README-ios.md index 4e6ca0eb9..62ec395d5 100644 --- a/README-ios.txt +++ b/doc/README-ios.md @@ -1,3 +1,6 @@ +iOS +====== + ============================================================================== Building the Simple DirectMedia Layer for iPhone OS 5.1 ============================================================================== diff --git a/README-linux.txt b/doc/README-linux.md similarity index 96% rename from README-linux.txt rename to doc/README-linux.md index f3f2fb8d8..d9cf40fb9 100644 --- a/README-linux.txt +++ b/doc/README-linux.md @@ -1,5 +1,4 @@ -================================================================================ -Simple DirectMedia Layer for Linux +Linux ================================================================================ By default SDL will only link against glibc, the rest of the features will be diff --git a/README-macosx.txt b/doc/README-macosx.md similarity index 96% rename from README-macosx.txt rename to doc/README-macosx.md index 895b9d142..ca6b7ee12 100644 --- a/README-macosx.txt +++ b/doc/README-macosx.md @@ -1,5 +1,4 @@ -============================================================================== -Using the Simple DirectMedia Layer with Mac OS X +Mac OS X ============================================================================== These instructions are for people using Apple's Mac OS X (pronounced diff --git a/README-nacl.txt b/doc/README-nacl.md similarity index 97% rename from README-nacl.txt rename to doc/README-nacl.md index d868e9180..b664f05ee 100644 --- a/README-nacl.txt +++ b/doc/README-nacl.md @@ -1,5 +1,4 @@ -================================================================================ -Simple DirectMedia Layer for Native Client +Native Client ================================================================================ Requirements: diff --git a/README-pandora.txt b/doc/README-pandora.md similarity index 89% rename from README-pandora.txt rename to doc/README-pandora.md index f70ed6725..e50e0c279 100644 --- a/README-pandora.txt +++ b/doc/README-pandora.md @@ -1,6 +1,7 @@ -SDL 2.0 with open pandora console support ( http://openpandora.org/ ) +Pandora ===================================================================== - + +( http://openpandora.org/ ) - A pandora specific video driver was written to allow SDL 2.0 with OpenGL ES support to work on the pandora under the framebuffer. This driver do not have input support for now, so if you use it you will have to add your own control code. diff --git a/README-platforms.txt b/doc/README-platforms.md similarity index 93% rename from README-platforms.txt rename to doc/README-platforms.md index 1fe2c87ee..3f1950a91 100644 --- a/README-platforms.txt +++ b/doc/README-platforms.md @@ -1,3 +1,6 @@ +Platforms +========= + This is a list of the platforms SDL supports, and who maintains them. diff --git a/README-porting.txt b/doc/README-porting.md similarity index 96% rename from README-porting.txt rename to doc/README-porting.md index bea194a4a..d93c65bd3 100644 --- a/README-porting.txt +++ b/doc/README-porting.md @@ -1,3 +1,5 @@ +Porting +======= * Porting To A New Platform diff --git a/README-psp.txt b/doc/README-psp.md similarity index 92% rename from README-psp.txt rename to doc/README-psp.md index e9e32ea5c..41fc9040a 100644 --- a/README-psp.txt +++ b/doc/README-psp.md @@ -1,3 +1,5 @@ +PSP +====== SDL port for the Sony PSP contributed by Captian Lex diff --git a/README-raspberrypi.txt b/doc/README-raspberrypi.md similarity index 96% rename from README-raspberrypi.txt rename to doc/README-raspberrypi.md index 22b4bbc9e..de920cce1 100644 --- a/README-raspberrypi.txt +++ b/doc/README-raspberrypi.md @@ -1,5 +1,4 @@ -================================================================================ -SDL2 for Raspberry Pi +Raspberry Pi ================================================================================ Requirements: diff --git a/README-touch.txt b/doc/README-touch.md similarity index 97% rename from README-touch.txt rename to doc/README-touch.md index 07823c934..5850b4f8f 100644 --- a/README-touch.txt +++ b/doc/README-touch.md @@ -1,3 +1,4 @@ +Touch =========================================================================== System Specific Notes =========================================================================== diff --git a/README-wince.txt b/doc/README-wince.md similarity index 90% rename from README-wince.txt rename to doc/README-wince.md index b7fd3f12f..c543ed65d 100644 --- a/README-wince.txt +++ b/doc/README-wince.md @@ -1,3 +1,5 @@ +WinCE +===== Windows CE is no longer supported by SDL. diff --git a/README-windows.txt b/doc/README-windows.md similarity index 94% rename from README-windows.txt rename to doc/README-windows.md index 7f9c4a35f..076b1556e 100644 --- a/README-windows.txt +++ b/doc/README-windows.md @@ -1,5 +1,4 @@ -================================================================================ -Simple DirectMedia Layer for Windows +Windows ================================================================================ ================================================================================ diff --git a/README-winrt.txt b/doc/README-winrt.md similarity index 93% rename from README-winrt.txt rename to doc/README-winrt.md index efc181b29..ee3a30327 100644 --- a/README-winrt.txt +++ b/doc/README-winrt.md @@ -1,5 +1,4 @@ -================================================================================ -Simple DirectMedia Layer for WinRT +WinRT ================================================================================ SDL/WinRT layer allows SDL2-based applications to run on many of Microsoft's diff --git a/README.txt b/doc/README.md similarity index 54% rename from README.txt rename to doc/README.md index 735637b94..d538dca0d 100644 --- a/README.txt +++ b/doc/README.md @@ -1,42 +1,62 @@ - - Simple DirectMedia Layer - - (SDL) - - Version 2.0 - ---- -http://www.libsdl.org/ - -Simple DirectMedia Layer is a cross-platform development library designed -to provide low level access to audio, keyboard, mouse, joystick, and graphics -hardware via OpenGL and Direct3D. It is used by video playback software, -emulators, and popular games including Valve's award winning catalog -and many Humble Bundle games. - -SDL officially supports Windows, Mac OS X, Linux, iOS, and Android. -Support for other platforms may be found in the source code. - -SDL is written in C, works natively with C++, and there are bindings -available for several other languages, including C# and Python. - -This library is distributed under the zlib license, which can be found -in the file "COPYING.txt". - -The best way to learn how to use SDL is to check out the header files in -the "include" subdirectory and the programs in the "test" subdirectory. -The header files and test programs are well commented and always up to date. -More documentation and FAQs are available online at: - http://wiki.libsdl.org/ - -If you need help with the library, or just want to discuss SDL related -issues, you can join the developers mailing list: - http://www.libsdl.org/mailing-list.php - -If you want to report bugs or contribute patches, please submit them to -bugzilla: - http://bugzilla.libsdl.org/ - -Enjoy! - Sam Lantinga (slouken@libsdl.org) - +Simple DirectMedia Layer {#mainpage} +======================== + + (SDL) + + Version 2.0 + +--- +http://www.libsdl.org/ + +Simple DirectMedia Layer is a cross-platform development library designed +to provide low level access to audio, keyboard, mouse, joystick, and graphics +hardware via OpenGL and Direct3D. It is used by video playback software, +emulators, and popular games including Valve's award winning catalog +and many Humble Bundle games. 42 + +SDL officially supports Windows, Mac OS X, Linux, iOS, and Android. +Support for other platforms may be found in the source code. + +SDL is written in C, works natively with C++, and there are bindings +available for several other languages, including C# and Python. + +This library is distributed under the zlib license, which can be found +in the file "COPYING.txt". + +The best way to learn how to use SDL is to check out the header files in +the "include" subdirectory and the programs in the "test" subdirectory. +The header files and test programs are well commented and always up to date. + +More documentation and FAQs are available online at [the wiki](http://wiki.libsdl.org/) + +- [Android](README-android.md) +- [CMake](README-cmake.md) +- [DirectFB](README-directfb.md) +- [DynAPI](README-dynapi.md) +- [Gesture](README-gesture.md) +- [Mercurial](README-hg.md) +- [iOS](README-ios.md) +- [Linux](README-linux.md) +- [OS X](README-macosx.md) +- [Native Client](README-nacl.md) +- [Pandora](README-pandora.md) +- [Supported Platforms](README-platforms.md) +- [Porting information](README-porting.md) +- [PSP](README-psp.md) +- [Raspberry Pi](README-raspberrypi.md) +- [Touch](README-touch.md) +- [WinCE](README-wince.md) +- [Windows](README-windows.md) +- [WinRT](README-winrt.md) + +If you need help with the library, or just want to discuss SDL related +issues, you can join the [developers mailing list](http://www.libsdl.org/mailing-list.php) + +If you want to report bugs or contribute patches, please submit them to +[bugzilla](http://bugzilla.libsdl.org/) + +Enjoy! + + +Sam Lantinga + diff --git a/include/doxyfile b/doc/doxyfile similarity index 99% rename from include/doxyfile rename to doc/doxyfile index 495dbc19b..151fa896a 100644 --- a/include/doxyfile +++ b/doc/doxyfile @@ -38,7 +38,7 @@ PROJECT_NUMBER = 2.0.0 # If a relative path is entered, it will be relative to the location # where doxygen was started. If left blank the current directory will be used. -OUTPUT_DIRECTORY = . +OUTPUT_DIRECTORY = ./output # If the CREATE_SUBDIRS tag is set to YES, then doxygen will create # 4096 sub-directories (in 2 levels) under the output directory of each output @@ -569,7 +569,7 @@ WARN_LOGFILE = ./doxygen_warn.txt # directories like "/usr/src/myproject". Separate the files or directories # with spaces. -INPUT = . +INPUT = . ../include # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is @@ -618,7 +618,8 @@ FILE_PATTERNS = *.c \ *.vhd \ *.vhdl \ *.h.in \ - *.h.default + *.h.default \ + *.md # The RECURSIVE tag can be used to turn specify whether or not subdirectories # should be searched for input files as well. Possible values are YES and NO. @@ -630,12 +631,15 @@ RECURSIVE = YES # excluded from the INPUT source files. This way you can easily exclude a # subdirectory from a directory tree whose root is specified with the INPUT tag. -EXCLUDE = ../doxy \ - ../test \ - ../Xcode \ - ../VisualC \ - ../VisualCE \ - ../Xcode-iOS +EXCLUDE = ../include/SDL_opengles2_gl2ext.h \ + ../include/SDL_opengles2_gl2platform.h \ + ../include/SDL_opengles2_khrplatform.h \ + ../include/SDL_opengl_glext.h \ + ../include/SDL_opengles2_gl2.h \ + ../include/SDL_opengles2.h \ + ../include/SDL_opengles.h \ + ../include/SDL_opengl.h \ + # The EXCLUDE_SYMLINKS tag can be used select whether or not files or # directories that are symbolic links (a Unix filesystem feature) are excluded @@ -1271,7 +1275,7 @@ SEARCH_INCLUDES = YES # contain include files that are not input files but should be processed by # the preprocessor. -INCLUDE_PATH = +INCLUDE_PATH = # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard # patterns (like *.h and *.hpp) to filter out the header-files in the diff --git a/include/SDL.h b/include/SDL.h index 206214753..703dc3d94 100644 --- a/include/SDL.h +++ b/include/SDL.h @@ -25,41 +25,6 @@ * Main include header for the SDL library */ -/** - * \mainpage Simple DirectMedia Layer (SDL) - * - * http://www.libsdl.org/ - * - * \section intro_sec Introduction - * - * Simple DirectMedia Layer is a cross-platform development library designed - * to provide low level access to audio, keyboard, mouse, joystick, and - * graphics hardware via OpenGL and Direct3D. It is used by video playback - * software, emulators, and popular games including Valve's award winning - * catalog and many Humble Bundle games. - * - * SDL officially supports Windows, Mac OS X, Linux, iOS, and Android. - * Support for other platforms may be found in the source code. - * - * SDL is written in C, works natively with C++, and there are bindings - * available for several other languages, including C# and Python. - * - * This library is distributed under the zlib license, which can be found - * in the file "COPYING.txt". - * - * The best way to learn how to use SDL is to check out the header files in - * the "include" subdirectory and the programs in the "test" subdirectory. - * The header files and test programs are well commented and always up to date. - * More documentation and FAQs are available online at: - * http://wiki.libsdl.org/ - * - * If you need help with the library, or just want to discuss SDL related - * issues, you can join the developers mailing list: - * http://www.libsdl.org/mailing-list.php - * - * Enjoy! - * Sam Lantinga (slouken@libsdl.org) - */ #ifndef _SDL_H #define _SDL_H