Sync SDL3 header -> wiki

SDL3/CategoryFilesystem.md

@@ -1,6 +1,27 @@
 # CategoryFilesystem
 
-SDL Filesystem API.
+SDL offers an API for examining and manipulating the system's filesystem.
+This covers most things one would need to do with directories, except for
+actual file I/O (which is covered by [CategoryIOStream](CategoryIOStream)
+and [CategoryAsyncIO](CategoryAsyncIO) instead).
+
+There are functions to answer necessary path questions:
+
+- Where is my app's data? [SDL_GetBasePath](SDL_GetBasePath)().
+- Where can I safely write files? [SDL_GetPrefPath](SDL_GetPrefPath)().
+- Where are paths like Downloads, Desktop, Music?
+  [SDL_GetUserFolder](SDL_GetUserFolder)().
+- What is this thing at this location?
+  [SDL_GetPathInfo](SDL_GetPathInfo)().
+- What items live in this folder?
+  [SDL_EnumerateDirectory](SDL_EnumerateDirectory)().
+- What items live in this folder by wildcard?
+  [SDL_GlobDirectory](SDL_GlobDirectory)().
+- What is my current working directory?
+  [SDL_GetCurrentDirectory](SDL_GetCurrentDirectory)().
+
+SDL also offers functions to manipulate the directory tree: renaming,
+removing, copying files.
 
 <!-- END CATEGORY DOCUMENTATION -->
 

SDL3/CategoryIOStream.md

@@ -1,7 +1,7 @@
 # CategoryIOStream
 
 SDL provides an abstract interface for reading and writing data streams. It
-offers implementations for files, memory, etc, and the app can provideo
+offers implementations for files, memory, etc, and the app can provide
 their own implementations, too.
 
 [SDL_IOStream](SDL_IOStream) is not related to the standard C++ iostream

SDL3/CategoryMetal.md

@@ -2,6 +2,10 @@
 
 Functions to creating Metal layers and views on SDL windows.
 
+This provides some platform-specific glue for Apple platforms. Most macOS
+and iOS apps can use SDL without these functions, but this API they can be
+useful for specific OS-level integration tasks.
+
 <!-- END CATEGORY DOCUMENTATION -->
 
 ## Functions

SDL3/CategoryStdinc.md

@@ -1,10 +1,26 @@
 # CategoryStdinc
 
-This is a general header that includes C language support. It implements a
-subset of the C runtime APIs, but with an `SDL_` prefix. For most common
-use cases, these should behave the same way as their C runtime equivalents,
-but they may differ in how or whether they handle certain edge cases. When
-in doubt, consult the documentation for details.
+SDL provides its own implementation of some of the most important C runtime
+functions.
+
+Using these functions allows an app to have access to common C
+functionality without depending on a specific C runtime (or a C runtime at
+all). More importantly, the SDL implementations work identically across
+platforms, so apps can avoid surprises like snprintf() behaving differently
+between Windows and Linux builds, or itoa() only existing on some
+platforms.
+
+For many of the most common functions, like [SDL_memcpy](SDL_memcpy), SDL
+might just call through to the usual C runtime behind the scenes, if it
+makes sense to do so (if it's faster and always available/reliable on a
+given platform), reducing library size and offering the most optimized
+option.
+
+SDL also offers other C-runtime-adjacent functionality in this header that
+either isn't, strictly speaking, part of any C runtime standards, like
+[SDL_crc32](SDL_crc32)() and [SDL_reinterpret_cast](SDL_reinterpret_cast),
+etc. It also offers a few better options, like
+[SDL_strlcpy](SDL_strlcpy)(), which functions as a safer form of strcpy().
 
 <!-- END CATEGORY DOCUMENTATION -->
 

SDL3/CategorySystem.md

@@ -1,6 +1,12 @@
 # CategorySystem
 
-Platform-specific SDL API functions.
+Platform-specific SDL API functions. These are functions that deal with
+needs of specific operating systems, that didn't make sense to offer as
+platform-independent, generic APIs.
+
+Most apps can make do without these functions, but they can be useful for
+integrating with other parts of a specific system, adding platform-specific
+polish to an app, or solving problems that only affect one target.
 
 <!-- END CATEGORY DOCUMENTATION -->
 

SDL3/SDL_PenAxisEvent.md

@@ -37,3 +37,4 @@ This struct is available since SDL 3.1.3.
 ----
 [CategoryAPI](CategoryAPI), [CategoryAPIStruct](CategoryAPIStruct), [CategoryEvents](CategoryEvents), [CategoryPen](CategoryPen)
 
+

SDL3/SDL_PenButtonEvent.md

@@ -38,3 +38,4 @@ This struct is available since SDL 3.1.3.
 ----
 [CategoryAPI](CategoryAPI), [CategoryAPIStruct](CategoryAPIStruct), [CategoryEvents](CategoryEvents), [CategoryPen](CategoryPen)
 
+

SDL3/SDL_PenMotionEvent.md

@@ -39,3 +39,4 @@ This struct is available since SDL 3.1.3.
 ----
 [CategoryAPI](CategoryAPI), [CategoryAPIStruct](CategoryAPIStruct), [CategoryEvents](CategoryEvents), [CategoryPen](CategoryPen)
 
+

SDL3/SDL_PenProximityEvent.md

@@ -41,3 +41,4 @@ This struct is available since SDL 3.1.3.
 ----
 [CategoryAPI](CategoryAPI), [CategoryAPIStruct](CategoryAPIStruct), [CategoryEvents](CategoryEvents), [CategoryPen](CategoryPen)
 
+

SDL3/SDL_PenTouchEvent.md

@@ -37,3 +37,4 @@ This struct is available since SDL 3.1.3.
 ----
 [CategoryAPI](CategoryAPI), [CategoryAPIStruct](CategoryAPIStruct), [CategoryEvents](CategoryEvents), [CategoryPen](CategoryPen)
 
+