From 63026450dedbf7d8aeee99d9086719f425b2bb4d Mon Sep 17 00:00:00 2001
From: Anonymous Maarten <[EMAIL REDACTED]>
Date: Mon, 10 Mar 2025 23:39:19 +0100
Subject: [PATCH] cmake: generate and install man pages (#119)
* cmake: only install runtime dependencies when using vendored dependencies
* Handle absolute include and lib paths in cmake
* Make download location or prebuilt DirectXSHaderCompiler configurable
* Update PrivateSdlFunctions.cmake from SDL3_image
* cmake: generate and install man pages
---
.github/workflows/main.yml | 1 +
.wikiheaders-options | 22 +
CMakeLists.txt | 26 +-
...nload-prebuilt-DirectXShaderCompiler.cmake | 4 +-
build-scripts/wikiheaders.pl | 3360 +++++++++++++++++
cmake/GetGitRevisionDescription.cmake | 284 ++
cmake/GetGitRevisionDescription.cmake.in | 43 +
cmake/PrivateSdlFunctions.cmake | 200 +-
cmake/sdl3-shadercross.pc.in | 4 +-
cmake/sdlmanpages.cmake | 68 +
10 files changed, 3912 insertions(+), 100 deletions(-)
create mode 100644 .wikiheaders-options
create mode 100755 build-scripts/wikiheaders.pl
create mode 100644 cmake/GetGitRevisionDescription.cmake
create mode 100644 cmake/GetGitRevisionDescription.cmake.in
create mode 100644 cmake/sdlmanpages.cmake
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index ce8b2e0..93352a1 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -105,6 +105,7 @@ jobs:
-DSDLSHADERCROSS_INSTALL=ON \
-DSDLSHADERCROSS_INSTALL_RUNTIME=ON \
-DSDLSHADERCROSS_INSTALL_CPACK=ON \
+ -DSDLSHADERCROSS_INSTALL_MAN=ON \
-DCMAKE_INSTALL_PREFIX="${PWD}/prefix" \
${{ matrix.platform.cmake-arguments }}
diff --git a/.wikiheaders-options b/.wikiheaders-options
new file mode 100644
index 0000000..4fc36cb
--- /dev/null
+++ b/.wikiheaders-options
@@ -0,0 +1,22 @@
+projectfullname = SDL_shadercross
+projectshortname = SDL_shadercross
+incsubdir = include/SDL3_shadercross
+wikisubdir = SDL_shadercross
+apiprefixregex = SDL_ShaderCross_
+mainincludefname = SDL3_shadercross/SDL_shadercross.h
+versionfname = include/SDL3_shadercross/SDL_shadercross.h
+versionmajorregex = \A\#define\s+SDL_SHADERCROSS_MAJOR_VERSION\s+(\d+)\Z
+versionminorregex = \A\#define\s+SDL_SHADERCROSS_MINOR_VERSION\s+(\d+)\Z
+versionmicroregex = \A\#define\s+SDL_SHADERCROSS_MICRO_VERSION\s+(\d+)\Z
+selectheaderregex = \ASDL_shadercross\.h\Z
+projecturl = https://libsdl.org/projects/SDL_shadercross
+wikiurl = https://wiki.libsdl.org/SDL_shadercross
+bugreporturl = https://github.com/libsdl-org/sdlwiki/issues/new
+warn_about_missing = 0
+wikipreamble = (This function is part of SDL_shadercross, a separate library from SDL.)
+wikiheaderfiletext = Defined in [<SDL3_shadercross/%fname%>](https://github.com/libsdl-org/SDL_shadercross/blob/main/include/SDL3_shadercross/%fname%)
+manpageheaderfiletext = Defined in SDL3_shadercross/%fname%
+quickrefenabled = 1
+quickreftitle = SDL3_shadercross API Quick Reference
+quickrefurl = https://libsdl.org/
+quickrefdesc = The latest version of this document can be found at https://wiki.libsdl.org/SDL3_shadercross/QuickReference
diff --git a/CMakeLists.txt b/CMakeLists.txt
index e987f0c..36c7b28 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -16,9 +16,11 @@ project(SDL3_shadercross LANGUAGES C VERSION "${MAJOR_VERSION}.${MINOR_VERSION}.
list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
include(CMakeDependentOption)
+include("${CMAKE_CURRENT_LIST_DIR}/cmake/GetGitRevisionDescription.cmake")
include("${CMAKE_CURRENT_LIST_DIR}/cmake/PrivateSdlFunctions.cmake")
include("${CMAKE_CURRENT_LIST_DIR}/cmake/sdlcpu.cmake")
include("${CMAKE_CURRENT_LIST_DIR}/cmake/sdlplatform.cmake")
+include("${CMAKE_CURRENT_LIST_DIR}/cmake/sdlmanpages.cmake")
if(NOT TARGET SDL3::SDL3-static)
find_package(SDL3 ${SDL_REQUIRED_VERSION})
@@ -43,7 +45,8 @@ cmake_dependent_option(SDLSHADERCROSS_CLI_STATIC "Link CLI with static libraries
option(SDLSHADERCROSS_WERROR "Enable Werror" OFF)
option(SDLSHADERCROSS_INSTALL "Enable installation" OFF)
cmake_dependent_option(SDLSHADERCROSS_INSTALL_CPACK "Enable CPack installation" OFF "SDLSHADERCROSS_INSTALL" OFF)
-cmake_dependent_option(SDLSHADERCROSS_INSTALL_RUNTIME "Download, build and install runtime dependencies" OFF "SDLSHADERCROSS_INSTALL" OFF)
+cmake_dependent_option(SDLSHADERCROSS_INSTALL_MAN "Install man pages for SDL3_shadercross" OFF "SDLSHADERCROSS_INSTALL" OFF)
+cmake_dependent_option(SDLSHADERCROSS_INSTALL_RUNTIME "Download, build and install runtime dependencies" OFF "SDLSHADERCROSS_VENDORED;SDLSHADERCROSS_INSTALL" OFF)
sdl_calculate_derived_version_variables(${MAJOR_VERSION} ${MINOR_VERSION} ${MICRO_VERSION})
SDL_DetectTargetCPUArchitectures(SDL_CPU_NAMES)
@@ -364,6 +367,17 @@ if(SDLSHADERCROSS_INSTALL)
)
endif()
+ if(IS_ABSOLUTE "${CMAKE_INSTALL_INCLUDEDIR}")
+ set(INCLUDEDIR_FOR_PKG_CONFIG "${CMAKE_INSTALL_INCLUDEDIR}")
+ else()
+ set(INCLUDEDIR_FOR_PKG_CONFIG "\${prefix}/${CMAKE_INSTALL_INCLUDEDIR}")
+ endif()
+ if(IS_ABSOLUTE "${CMAKE_INSTALL_LIBDIR}")
+ set(LIBDIR_FOR_PKG_CONFIG "${CMAKE_INSTALL_LIBDIR}")
+ else()
+ set(LIBDIR_FOR_PKG_CONFIG "\${prefix}/${CMAKE_INSTALL_LIBDIR}")
+ endif()
+
file(RELATIVE_PATH SDL_PATH_PREFIX_RELATIVE_TO_PKGCONFIG "${CMAKE_INSTALL_PREFIX}/${SDLSHADERCROSS_PKGCONFIG_INSTALLDIR}" "${CMAKE_INSTALL_PREFIX}")
string(REGEX REPLACE "[/]+$" "" SDL_PATH_PREFIX_RELATIVE_TO_PKGCONFIG "${SDL_PATH_PREFIX_RELATIVE_TO_PKGCONFIG}")
set(SDL_PKGCONFIG_PREFIX "\${pcfiledir}/${SDL_PATH_PREFIX_RELATIVE_TO_PKGCONFIG}")
@@ -400,6 +414,16 @@ if(SDLSHADERCROSS_INSTALL)
endif()
endif()
+if(SDLSHADERCROSS_INSTALL_MAN)
+ sdl_get_git_revision_hash(SDLSHADERCROSS_REVISION)
+ SDL_generate_manpages(
+ HEADERS_DIR "${PROJECT_SOURCE_DIR}/include/SDL3_shadercross"
+ SYMBOL "SDL_ShaderCross_Init"
+ WIKIHEADERS_PL_PATH "${CMAKE_CURRENT_SOURCE_DIR}/build-scripts/wikiheaders.pl"
+ REVISION "${SDLSHADERCROSS_REVISION}"
+ )
+endif()
+
set(DXC_LINUX_X64_URL "https://github.com/microsoft/DirectXShaderCompiler/releases/download/v1.8.2407/linux_dxc_2024_07_31.x86_64.tar.gz")
set(DXC_LINUX_X64_HASH "SHA256=b58725ac191df0686994fb9d54d27ee8dd3f180b023d562733112a499ea1195c")
set(DXC_WINDOWS_X86_X64_ARM64_URL "https://github.com/microsoft/DirectXShaderCompiler/releases/download/v1.8.2407/dxc_2024_07_31.zip")
diff --git a/build-scripts/download-prebuilt-DirectXShaderCompiler.cmake b/build-scripts/download-prebuilt-DirectXShaderCompiler.cmake
index 76ff8c2..1a4bf06 100644
--- a/build-scripts/download-prebuilt-DirectXShaderCompiler.cmake
+++ b/build-scripts/download-prebuilt-DirectXShaderCompiler.cmake
@@ -4,7 +4,9 @@ set(DXC_WINDOWS_X86_X64_ARM64_URL "https://github.com/microsoft/DirectXShaderCom
set(DXC_WINDOWS_X86_X64_ARM64_HASH "SHA256=70b1913a1bfce4a3e1a5311d16246f4ecdf3a3e613abec8aa529e57668426f85")
get_filename_component(EXTERNAL_PATH "${CMAKE_CURRENT_LIST_DIR}/../external" ABSOLUTE)
-set(DXC_ROOT "${EXTERNAL_PATH}/DirectXShaderCompiler-binaries")
+if(NOT DEFINED DXC_ROOT)
+ set(DXC_ROOT "${EXTERNAL_PATH}/DirectXShaderCompiler-binaries")
+endif()
set(DOWNLOAD_LINUX ON)
set(DOWNLOAD_WINDOWS ON)
diff --git a/build-scripts/wikiheaders.pl b/build-scripts/wikiheaders.pl
new file mode 100755
index 0000000..9859149
--- /dev/null
+++ b/build-scripts/wikiheaders.pl
@@ -0,0 +1,3360 @@
+#!/usr/bin/perl -w
+
+# Simple DirectMedia Layer
+# Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
+#
+# This software is provided 'as-is', without any express or implied
+# warranty. In no event will the authors be held liable for any damages
+# arising from the use of this software.
+#
+# Permission is granted to anyone to use this software for any purpose,
+# including commercial applications, and to alter it and redistribute it
+# freely, subject to the following restrictions:
+#
+# 1. The origin of this software must not be misrepresented; you must not
+# claim that you wrote the original software. If you use this software
+# in a product, an acknowledgment in the product documentation would be
+# appreciated but is not required.
+# 2. Altered source versions must be plainly marked as such, and must not be
+# misrepresented as being the original software.
+# 3. This notice may not be removed or altered from any source distribution.
+
+use warnings;
+use strict;
+use File::Path;
+use Text::Wrap;
+
+$Text::Wrap::huge = 'overflow';
+
+my $projectfullname = 'Simple Directmedia Layer';
+my $projectshortname = 'SDL';
+my $wikisubdir = '';
+my $incsubdir = 'include';
+my $readmesubdir = undef;
+my $apiprefixregex = undef;
+my $versionfname = 'include/SDL_version.h';
+my $versionmajorregex = '\A\#define\s+SDL_MAJOR_VERSION\s+(\d+)\Z';
+my $versionminorregex = '\A\#define\s+SDL_MINOR_VERSION\s+(\d+)\Z';
+my $versionmicroregex = '\A\#define\s+SDL_MICRO_VERSION\s+(\d+)\Z';
+my $mainincludefname = 'SDL.h';
+my $selectheaderregex = '\ASDL.*?\.h\Z';
+my $projecturl = 'https://libsdl.org/';
+my $wikiurl = 'https://wiki.libsdl.org';
+my $bugreporturl = 'https://github.com/libsdl-org/sdlwiki/issues/new';
+my $srcpath = undef;
+my $wikipath = undef;
+my $wikireadmesubdir = 'README';
+my $warn_about_missing = 0;
+my $copy_direction = 0;
+my $optionsfname = undef;
+my $wikipreamble = undef;
+my $wikiheaderfiletext = 'Defined in %fname%';
+my $manpageheaderfiletext = 'Defined in %fname%';
+my $manpagesymbolfilterregex = undef;
+my $headercategoryeval = undef;
+my $quickrefenabled = 0;
+my @quickrefcategoryorder;
+my $quickreftitle = undef;
+my $quickrefurl = undef;
+my $quickrefdesc = undef;
+my $quickrefmacroregex = undef;
+my $changeformat = undef;
+my $manpath = undef;
+my $gitrev = undef;
+
+foreach (@ARGV) {
+ $warn_about_missing = 1, next if $_ eq '--warn-about-missing';
+ $copy_direction = 1, next if $_ eq '--copy-to-headers';
+ $copy_direction = 1, next if $_ eq '--copy-to-header';
+ $copy_direction = -1, next if $_ eq '--copy-to-wiki';
+ $copy_direction = -2, next if $_ eq '--copy-to-manpages';
+ $copy_direction = -3, next if $_ eq '--report-coverage-gaps';
+ $copy_direction = -4, next if $_ eq '--copy-to-latex';
+ if (/\A--options=(.*)\Z/) {
+ $optionsfname = $1;
+ next;
+ } elsif (/\A--changeformat=(.*)\Z/) {
+ $changeformat = $1;
+ next;
+ } elsif (/\A--manpath=(.*)\Z/) {
+ $manpath = $1;
+ next;
+ } elsif (/\A--rev=(.*)\Z/) {
+ $gitrev = $1;
+ next;
+ }
+ $srcpath = $_, next if not defined $srcpath;
+ $wikipath = $_, next if not defined $wikipath;
+}
+
+my $default_optionsfname = '.wikiheaders-options';
+$default_optionsfname = "$srcpath/$default_optionsfname" if defined $srcpath;
+
+if ((not defined $optionsfname) && (-f $default_optionsfname)) {
+ $optionsfname = $default_optionsfname;
+}
+
+if (defined $optionsfname) {
+ open OPTIONS, '<', $optionsfname or die("Failed to open options file '$optionsfname': $!\n");
+ while (<OPTIONS>) {
+ next if /\A\s*\#/; # Skip lines that start with (optional whitespace, then) '#' as comments.
+
+ chomp;
+ if (/\A(.*?)\=(.*)\Z/) {
+ my $key = $1;
+ my $val = $2;
+ $key =~ s/\A\s+//;
+ $key =~ s/\s+\Z//;
+ $val =~ s/\A\s+//;
+ $val =~ s/\s+\Z//;
+ $warn_about_missing = int($val), next if $key eq 'warn_about_missing';
+ $srcpath = $val, next if $key eq 'srcpath';
+ $wikipath = $val, next if $key eq 'wikipath';
+ $apiprefixregex = $val, next if $key eq 'apiprefixregex';
+ $projectfullname = $val, next if $key eq 'projectfullname';
+ $projectshortname = $val, next if $key eq 'projectshortname';
+ $wikisubdir = $val, next if $key eq 'wikisubdir';
+ $incsubdir = $val, next if $key eq 'incsubdir';
+ $readmesubdir = $val, next if $key eq 'readmesubdir';
+ $versionmajorregex = $val, next if $key eq 'versionmajorregex';
+ $versionminorregex = $val, next if $key eq 'versionminorregex';
+ $versionmicroregex = $val, next if $key eq 'versionmicroregex';
+ $versionfname = $val, next if $key eq 'versionfname';
+ $mainincludefname = $val, next if $key eq 'mainincludefname';
+ $selectheaderregex = $val, next if $key eq 'selectheaderregex';
+ $projecturl = $val, next if $key eq 'projecturl';
+ $wikiurl = $val, next if $key eq 'wikiurl';
+ $bugreporturl = $val, next if $key eq 'bugreporturl';
+ $wikipreamble = $val, next if $key eq 'wikipreamble';
+ $wikiheaderfiletext = $val, next if $key eq 'wikiheaderfiletext';
+ $manpageheaderfiletext = $val, next if $key eq 'manpageheaderfiletext';
+ $manpagesymbolfilterregex = $val, next if $key eq 'manpagesymbolfilterregex';
+ $headercategoryeval = $val, next if $key eq 'headercategoryeval';
+ $quickrefenabled = int($val), next if $key eq 'quickrefenabled';
+ @quickrefcategoryorder = split(/,/, $val), next if $key eq 'quickrefcategoryorder';
+ $quickreftitle = $val, next if $key eq 'quickreftitle';
+ $quickrefurl = $val, next if $key eq 'quickrefurl';
+ $quickrefdesc = $val, next if $key eq 'quickrefdesc';
+ $quickrefmacroregex = $val, next if $key eq 'quickrefmacroregex';
+ }
+ }
+ close(OPTIONS);
+}
+
+sub escLaTeX {
+ my $str = shift;
+ $str =~ s/([_\#\&\^])/\\$1/g;
+ return $str;
+}
+
+my $wordwrap_mode = 'mediawiki';
+sub wordwrap_atom { # don't call this directly.
+ my $str = shift;
+ my $retval = '';
+
+ # wordwrap but leave links intact, even if they overflow.
+ if ($wordwrap_mode eq 'mediawiki') {
+ while ($str =~ s/(.*?)\s*(\[https?\:\/\/.*?\s+.*?\])\s*//ms) {
+ $retval .= fill('', '', $1); # wrap it.
+ $retval .= "\n$2\n"; # don't wrap it.
+ }
+ } elsif ($wordwrap_mode eq 'md') {
+ while ($str =~ s/(.*?)\s*(\[.*?\]\(https?\:\/\/.*?\))\s*//ms) {
+ $retval .= fill('', '', $1); # wrap it.
+ $retval .= "\n$2\n"; # don't wrap it.
+ }
+ }
+
+ return $retval . fill('', '', $str);
+}
+
+sub wordwrap_with_bullet_indent { # don't call this directly.
+ my $bullet = shift;
+ my $str = shift;
+ my $retval = '';
+
+ #print("WORDWRAP BULLET ('$bullet'):\n\n$str\n\n");
+
+ # You _can't_ (at least with Pandoc) have a bullet item with a newline in
+ # MediaWiki, so _remove_ wrapping!
+ if ($wordwrap_mode eq 'mediawiki') {
+ $retval = "$bullet$str";
+ $retval =~ s/\n/ /gms;
+ $retval =~ s/\s+$//gms;
+ #print("WORDWRAP BULLET DONE:\n\n$retval\n\n");
+ return "$retval\n";
+ }
+
+ my $bulletlen = length($bullet);
+
+ # wrap it and then indent each line to be under the bullet.
+ $Text::Wrap::columns -= $bulletlen;
+ my @wrappedlines = split /\n/, wordwrap_atom($str);
+ $Text::Wrap::columns += $bulletlen;
+
+ my $prefix = $bullet;
+ my $usual_prefix = ' ' x $bulletlen;
+
+ foreach (@wrappedlines) {
+ s/\s*\Z//;
+ $retval .= "$prefix$_\n";
+ $prefix = $usual_prefix;
+ }
+
+ return $retval;
+}
+
+sub wordwrap_one_paragraph { # don't call this directly.
+ my $retval = '';
+ my $p = shift;
+ #print "\n\n\nPARAGRAPH: [$p]\n\n\n";
+ if ($p =~ s/\A([\*\-] )//) { # bullet list, starts with "* " or "- ".
+ my $bullet = $1;
+ my $item = '';
+ my @items = split /\n/, $p;
+ foreach (@items) {
+ if (s/\A([\*\-] )//) {
+ $retval .= wordwrap_with_bullet_indent($bullet, $item);
+ $item = '';
+ }
+ s/\A\s*//;
+ $item .= "$_\n"; # accumulate lines until we hit the end or another bullet.
+ }
+ if ($item ne '') {
+ $retval .= wordwrap_with_bullet_indent($bullet, $item);
+ }
+ } elsif ($p =~ /\A\s*\|.*\|\s*\n/) { # Markdown table
+ $retval = "$p\n"; # don't wrap it (!!! FIXME: but maybe parse by lines until we run out of table...)
+ } else {
+ $retval = wordwrap_atom($p) . "\n";
+ }
+
+ return $retval;
+}
+
+sub wordwrap_paragraphs { # don't call this directly.
+ my $str = shift;
+ my $retval = '';
+ my @paragraphs = split /\n\n/, $str;
+ foreach (@paragraphs) {
+ next if $_ eq '';
+ $retval .= wordwrap_one_paragraph($_);
+ $retval .= "\n";
+ }
+ return $retval;
+}
+
+my $wordwrap_default_columns = 76;
+sub wordwrap {
+ my $str = shift;
+ my $columns = shift;
+
+ $columns = $wordwrap_default_columns if not defined $columns;
+ $columns += $wordwrap_default_columns if $columns < 0;
+ $Text::Wrap::columns = $columns;
+
+ my $retval = '';
+
+ #print("\n\nWORDWRAP:\n\n$str\n\n\n");
+
+ $str =~ s/\A\n+//ms;
+
+ while ($str =~ s/(.*?)(\`\`\`.*?\`\`\`|\<syntaxhighlight.*?\<\/syntaxhighlight\>)//ms) {
+ #print("\n\nWORDWRAP BLOCK:\n\n$1\n\n ===\n\n$2\n\n\n");
+ $retval .= wordwrap_paragraphs($1); # wrap it.
+ $retval .= "$2\n\n"; # don't wrap it.
+ }
+
+ $retval .= wordwrap_paragraphs($str); # wrap what's left.
+ $retval =~ s/\n+\Z//ms;
+
+ #print("\n\nWORDWRAP DONE:\n\n$retval\n\n\n");
+ return $retval;
+}
+
+# This assumes you're moving from Markdown (in the Doxygen data) to Wiki, which
+# is why the 'md' section is so sparse.
+sub wikify_chunk {
+ my $wikitype = shift;
+ my $str = shift;
+ my $codelang = shift;
+ my $code = shift;
+
+ #print("\n\nWIKIFY CHUNK:\n\n$str\n\n\n");
+
+ if ($wikitype eq 'mediawiki') {
+ # convert `code` things first, so they aren't mistaken for other markdown items.
+ my $codedstr = '';
+ while ($str =~ s/\A(.*?)\`(.*?)\`//ms) {
+ my $codeblock = $2;
+ $codedstr .= wikify_chunk($wikitype, $1, undef, undef);
+ if (defined $apiprefixregex) {
+ # Convert obvious API things to wikilinks, even inside `code` blocks.
+ $codeblock =~ s/(\A|[^\/a-zA-Z0-9_])($apiprefixregex[a-zA-Z0-9_]+)/$1\[\[$2\]\]/gms;
+ }
+ $codedstr .= "<code>$codeblock</code>";
+ }
+
+ # Convert obvious API things to wikilinks.
+ if (defined $apiprefixregex) {
+ $str =~ s/(\A|[^\/a-zA-Z0-9_])($apiprefixregex[a-zA-Z0-9_]+)/$1\[\[$2\]\]/gms;
+ }
+
+ # Make some Markdown things into MediaWiki...
+
+ # links
+ $str =~ s/\[(.*?)\]\((https?\:\/\/.*?)\)/\[$2 $1\]/g;
+
+ # bold+italic
+ $str =~ s/\*\*\*(.*?)\*\*\*/'''''$1'''''/gms;
+
+ # bold
+ $str =~ s/\*\*(.*?)\*\*/'''$1'''/gms;
+
+ # italic
+ $str =~ s/\*(.*?)\*/''$1''/gms;
+
+ # bullets
+ $str =~ s/^\- /* /gm;
+
+ $str = $codedstr . $str;
+
+ if (defined $code) {
+ $str .= "<syntaxhighlight lang='$codelang'>$code<\/syntaxhighlight>";
+ }
+ } elsif ($wikitype eq 'md') {
+ # convert `code` things first, so they aren't mistaken for other markdown items.
+ my $codedstr = '';
+ while ($str =~ s/\A(.*?)(\`.*?\`)//ms) {
+ my $codeblock = $2;
+ $codedstr .= wikify_chunk($wikitype, $1, undef, undef);
+ if (defined $apiprefixregex) {
+ # Convert obvious API things to wikilinks, even inside `code` blocks,
+ # BUT ONLY IF the entire code block is the API thing,
+ # So something like "just call `SDL_Whatever`" will become
+ # "just call [`SDL_Whatever`](SDL_Whatever)", but
+ # "just call `SDL_Whatever(7)`" will not. It's just the safest
+ # way to do this without resorting to wrapping things in html <code> tags.
+ $codeblock =~ s/\A\`($apiprefixregex[a-zA-Z0-9_]+)\`\Z/[`$1`]($1)/gms;
+ }
+ $codedstr .= $codeblock;
+ }
+
+ # Convert obvious API things to wikilinks.
+ if (defined $apiprefixregex) {
+ $str =~ s/(\A|[^\/a-zA-Z0-9_])($apiprefixregex[a-zA-Z0-9_]+)/$1\[$2\]\($2\)/gms;
+ }
+
+ $str = $codedstr . $str;
+
+ if (defined $code) {
+ $str .= "```$codelang\n$code\n```\n";
+ }
+ }
+
+ #print("\n\nWIKIFY CHUNK DONE:\n\n$str\n\n\n");
+
+ return $str;
+}
+
+sub wikify {
+ my $wikitype = shift;
+ my $str = shift;
+ my $retval = '';
+
+ #print("WIKIFY WHOLE:\n\n$str\n\n\n");
+
+ while ($str =~ s/\A(.*?)\`\`\`(.*?)\n(.*?)\n\`\`\`(\n|\Z)//ms) {
+ $retval .= wikify_chunk($wikitype, $1, $2, $3);
+ }
+ $retval .= wikify_chunk($wikitype, $str, undef, undef);
+
+ #print("WIKIFY WHOLE DONE:\n\n$retval\n\n\n");
+
+ return $retval;
+}
+
+
+my $dewikify_mode = 'md';
+my $dewikify_manpage_code_indent = 1;
+
+sub dewikify_chunk {
+ my $wikitype = shift;
+ my $str = shift;
+ my $codelang = shift;
+ my $code = shift;
+
+ #print("\n\nDEWIKIFY CHUNK:\n\n$str\n\n\n");
+
+ if ($dewikify_mode eq 'md') {
+ if ($wikitype eq 'mediawiki') {
+ # Doxygen supports Markdown (and it just simply looks better than MediaWiki
+ # when looking at the raw headers), so do some conversions here as necessary.
+
+ # Dump obvious wikilinks.
+ if (defined $apiprefixregex) {
+ $str =~ s/\[\[($apiprefixregex[a-zA-Z0-9_]+)\]\]/$1/gms;
+ }
+
+ # links
+ $str =~ s/\[(https?\:\/\/.*?)\s+(.*?)\]/\[$2\]\($1\)/g;
+
+ # <code></code> is also popular. :/
+ $str =~ s/\<code>(.*?)<\/code>/`$1`/gms;
+
+ # bold+italic
+ $str =~ s/'''''(.*?)'''''/***$1***/gms;
+
+ # bold
+ $str =~ s/'''(.*?)'''/**$1**/gms;
+
+ # italic
+ $str =~ s/''(.*?)''/*$1*/gms;
+
+ # bullets
+ $str =~ s/^\* /- /gm;
+ } elsif ($wikitype eq 'md') {
+ # Dump obvious wikilinks. The rest can just passthrough.
+ if (defined $apiprefixregex) {
+ $str =~ s/\[(\`?$apiprefixregex[a-zA-Z0-9_]+\`?)\]\($apiprefixregex[a-zA-Z0-9_]+\)/$1/gms;
+ }
+ }
+
+ if (defined $code) {
+ $str .= "\n```$codelang\n$code\n```\n";
+ }
+ } elsif ($dewikify_mode eq 'manpage') {
+ $str =~ s/\./\\[char46]/gms; # make sure these can't become control codes.
+ if ($wikitype eq 'mediawiki') {
+ # Dump obvious wikilinks.
+ if (defined $apiprefixregex) {
+ $str =~ s/\s*\[\[($apiprefixregex[a-zA-Z0-9_]+)\]\]\s*/\n.BR $1\n/gms;
+ }
+
+ # links
+ $str =~ s/\[(https?\:\/\/.*?)\s+(.*?)\]/\n.URL "$1" "$2"\n/g;
+
+ # <code></code> is also popular. :/
+ $str =~ s/\s*\<code>(.*?)<\/code>\s*/\n.BR $1\n/gms;
+
+ # bold+italic (this looks bad, just make it bold).
+ $str =~ s/\s*'''''(.*?)'''''\s*/\n.B $1\n/gms;
+
+ # bold
+ $str =~ s/\s*'''(.*?)'''\s*/\n.B $1\n/gms;
+
+ # italic
+ $str =~ s/\s*''(.*?)''\s*/\n.I $1\n/gms;
+
+ # bullets
+ $str =~ s/^\* /\n\\\(bu /gm;
+ } elsif ($wikitype eq 'md') {
+ # Dump obvious wikilinks.
+ if (defined $apiprefixregex) {
+ $str =~ s/\[(\`?$apiprefixregex[a-zA-Z0-9_]+\`?)\]\($apiprefixregex[a-zA-Z0-9_]+\)/\n.BR $1\n/gms;
+ }
+
+ # links
+ $str =~ s/\[(.*?)]\((https?\:\/\/.*?)\)/\n.URL "$2" "$1"\n/g;
+
+ # <code></code> is also popular. :/
+ $str =~ s/\s*\`(.*?)\`\s*/\n.BR $1\n/gms;
+
+ # bold+italic (this looks bad, just make it bold).
+ $str =~ s/\s*\*\*\*(.*?)\*\*\*\s*/\n.B $1\n/gms;
+
+ # bold
+ $str =~ s/\s*\*\*(.*?)\*\*\s*/\n.B $1\n/gms;
+
+ # italic
+ $str =~ s/\s*\*(.*?)\*\s*/\n.I $1\n/gms;
+
+ # bullets
+ $str =~ s/^\- /\n\\\(bu /gm;
+ }
+
+ if (defined $code) {
+ $code =~ s/\A\n+//gms;
+ $code =~ s/\n+\Z//gms;
+ if ($dewikify_manpage_code_indent) {
+ $str .= "\n.IP\n"
+ } else {
+ $str .= "\n.PP\n"
+ }
+ $str .= ".EX\n$code\n.EE\n.PP\n";
+ }
+ } elsif ($dewikify_mode eq 'LaTeX') {
+ if ($wikitype eq 'mediawiki') {
+ # Dump obvious wikilinks.
+ if (defined $apiprefixregex) {
+ $str =~ s/\s*\[\[($apiprefixregex[a-zA-Z0-9_]+)\]\]/$1/gms;
+ }
+
+ # links
+ $str =~ s/\[(https?\:\/\/.*?)\s+(.*?)\]/\\href{$1}{$2}/g;
+
+ # <code></code> is also popular. :/
+ $str =~ s/\s*\<code>(.*?)<\/code>/ \\texttt{$1}/gms;
+
+ # bold+italic
+ $str =~ s/\s*'''''(.*?)'''''/ \\textbf{\\textit{$1}}/gms;
+
+ # bold
+ $str =~ s/\s*'''(.*?)'''/ \\textbf{$1}/gms;
+
+ # italic
+ $str =~ s/\s*''(.*?)''/ \\textit{$1}/gms;
+
+ # bullets
+ $str =~ s/^\*\s+/ \\item /gm;
+ } elsif ($wikitype eq 'md') {
+ # Dump obvious wikilinks.
+ if (defined $apiprefixregex) {
+ $str =~ s/\[(\`?$apiprefixregex[a-zA-Z0-9_]+\`?)\]\($apiprefixregex[a-zA-Z0-9_]+\)/$1/gms;
+ }
+
+ # links
+ $str =~ s/\[(.*?)]\((https?\:\/\/.*?)\)/\\href{$2}{$1}/g;
+
+ # <code></code> is also popular. :/
+ $str =~ s/\s*\`(.*?)\`/ \\texttt{$1}/gms;
+
+ # bold+italic
+ $str =~ s/\s*\*\*\*(.*?)\*\*\*/ \\textbf{\\textit{$1}}/gms;
+
+ # bold
+ $str =~ s/\s*\*\*(.*?)\*\*/ \\textbf{$1}/gms;
+
+ # italic
+ $str =~ s/\s*\*(.*?)\*/ \\textit{$1}/gms;
+
+ # bullets
+ $str =~ s/^\-\s+/ \\item /gm;
+ }
+
+ # Wrap bullet lists in itemize blocks...
+ $str =~ s/^(\s*\\item .*?)(\n\n|\Z)/\n\\begin{itemize}\n$1$2\n\\end{itemize}\n\n/gms;
+
+ $str = escLaTeX($str);
+
+ if (defined $code) {
+ $code =~ s/\A\n+//gms;
+ $code =~ s/\n+\Z//gms;
+
+ if (($codelang eq '') || ($codelang eq 'output')) {
+ $str .= "\\begin{verbatim}\n$code\n\\end{verbatim}\n";
+ } else {
+ if ($codelang eq 'c') {
+ $codelang = 'C';
+ } elsif ($codelang eq 'c++') {
+ $codelang = 'C++';
+ } else {
+ die("Unexpected codelang '$codelang'");
+ }
+ $str .= "\n\\lstset{language=$codelang}\n";
+ $str .= "\\begin{lstlisting}\n$code\n\\end{lstlisting}\n";
+ }
+ }
+ } else {
+ die("Unexpected dewikify_mode");
+ }
+
+ #print("\n\nDEWIKIFY CHUNK DONE:\n\n$str\n\n\n");
+
+ return $str;
+}
+
+sub dewikify {
+ my $wikitype = shift;
+ my $str = shift;
+ return '' if not defined $str;
+
+ #print("DEWIKIFY WHOLE:\n\n$str\n\n\n");
+
+ $str =~ s/\A[\s\n]*\= .*? \=\s*?\n+//ms;
+ $str =~ s/\A[\s\n]*\=\= .*? \=\=\s*?\n+//ms;
+
+ my $retval = '';
+ if ($wikitype eq 'mediawiki') {
+ while ($str =~ s/\A(.*?)<syntaxhighlight lang='?(.*?)'?>(.*?)<\/syntaxhighlight\>//ms) {
+ $retval .= dewikify_chunk($wikitype, $1, $2, $3);
+ }
+ } elsif ($wikitype eq 'md') {
+ while ($str =~ s/\A(.*?)\n```(.*?)\n(.*?)\n```\n//ms) {
+ $retval .= dewikify_chunk($wikitype, $1, $2, $3);
+ }
+ }
+ $retval .= dewikify_chunk($wikitype, $str, undef, undef);
+
+ #print("DEWIKIFY WHOLE DONE:\n\n$retval\n\n\n");
+
+ return $retval;
+}
+
+sub filecopy {
+ my $src = shift;
+ my $dst = shift;
+ my $endline = shift;
+ $endline = "\n" if not defined $endline;
+
+ open(COPYIN, '<', $src) or die("Failed to open '$src' for reading: $!\n");
+ open(COPYOUT, '>', $dst) or die("Failed to open '$dst' for writing: $!\n");
+ while (<COPYIN>) {
+ chomp;
+ s/[ \t\r\n]*\Z//;
+ print COPYOUT "$_$endline";
+ }
+ close(COPYOUT);
+ close(COPYIN);
+}
+
+sub usage {
+ die("USAGE: $0 <source code git clone path> <wiki git clone path> [--copy-to-headers|--copy-to-wiki|--copy-to-manpages] [--warn-about-missing] [--manpath=<man path>]\n\n");
+}
+
+usage() if not defined $srcpath;
+usage() if not defined $wikipath;
+#usage() if $copy_direction == 0;
+
+if (not defined $manpath) {
+ $manpath = "$srcpath/man";
+}
+
+my @standard_wiki_sections = (
+ 'Draft',
+ '[Brief]',
+ 'Deprecated',
+ 'Header File',
+ 'Syntax',
+ 'Function Parameters',
+ 'Macro Parameters',
+ 'Fields',
+ 'Values',
+ 'Return Value',
+ 'Remarks',
+ 'Thread Safety',
+ 'Version',
+ 'Code Examples',
+ 'See Also'
+);
+
+# Sections that only ever exist in the wiki and shouldn't be deleted when
+# not found in the headers.
+my %only_wiki_sections = ( # The ones don't mean anything, I just need to check for key existence.
+ 'Draft', 1,
+ 'Code Examples', 1,
+ 'Header File', 1
+);
+
+
+my %headers = (); # $headers{"SDL_audio.h"} -> reference to an array of all lines of text in SDL_audio.h.
+my %headersyms = (); # $headersyms{"SDL_OpenAudio"} -> string of header documentation for SDL_OpenAudio, with comment '*' bits stripped from the start. Newlines embedded!
+my %headerdecls = ();
+my %headersymslocation = (); # $headersymslocation{"SDL_OpenAudio"} -> name of header holding SDL_OpenAudio define ("SDL_audio.h" in this case).
+my %headersymschunk = (); # $headersymschunk{"SDL_OpenAudio"} -> offset in array in %headers that should be replaced for this symbol.
+my %headersymshasdoxygen = (); # $headersymshasdoxygen{"SDL_OpenAudio"} -> 1 if there was no existing doxygen for this function.
+my %headersymstype = (); # $headersymstype{"SDL_OpenAudio"} -> 1 (function), 2 (macro), 3 (struct), 4 (enum), 5 (other typedef)
+my %headersymscategory = (); # $headersymscategory{"SDL_OpenAudio"} -> 'Audio' ... this is set with a `/* WIKI CATEGEORY: Audio */` comment in the headers that sets it on all symbols until a new comment changes it. So usually, once at the top of the header file.
+my %headercategorydocs = (); # $headercategorydocs{"Audio"} -> (fake) symbol for this category's documentation. Undefined if not documented.
+my %headersymsparaminfo = (); # $headersymsparaminfo{"SDL_OpenAudio"} -> reference to array of parameters, pushed by name, then C type string, repeating. Undef'd if void params, or not a function.
+my %headersymsrettype = (); # $headersymsrettype{"SDL_OpenAudio"} -> string of C datatype of return value. Undef'd if not a function.
+my %wikitypes = (); # contains string of wiki page extension, like $wikitypes{"SDL_OpenAudio"} == 'mediawiki'
+my %wikisyms = (); # contains references to hash of strings, each string being the full contents of a section of a wiki page, like $wikisyms{"SDL_OpenAudio"}{"Remarks"}.
+my %wikisectionorder = (); # contains references to array, each array item being a key to a wikipage section in the correct order, like $wikisectionorder{"SDL_OpenAudio"}[2] == 'Remarks'
+my %quickreffuncorder = (); # contains references to array, each array item being a key to a c
(Patch may be truncated, please check the link at the top of this post.)