phpMan.php

<?php
declare(strict_types=1);
// +--------------------------------------------------------------------------------+
// | phpMan:      Unix Man page / Perldoc / Info page Web Interface                 |
// +--------------------------------------------------------------------------------+
// | Copyright (C) 2002 - 2026 Che, Dong chedong AT chedong.com                     |
// +--------------------------------------------------------------------------------+
// | This program is free software; you can redistribute it and/or                  |
// | modify it under the terms of the GNU General Public License                    |
// | the Free Software Foundation; either version 2 of the License, or              |
// | (at your option) any later version.                                            |
// |                                                                                |
// | This program is distributed in the hope that it will be useful,                |
// | but WITHOUT ANY WARRANTY; without even the implied warranty of                 |
// | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the                  |
// | GNU General Public License for more details.                                   |
// |                                                                                |
// | You should have received a copy of the GNU General Public License              |
// | along with this program; if not, write to the Free Software                    |
// | Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.    |
// +--------------------------------------------------------------------------------+
// $Id$


// ASCII char classes RE_ASCII / RE_ASCII_SAFE now defined in src/config.php
// (v4.9.9: moved for CLI tool access)

// #49: Named constants — placeholders replaced by make deploy/release
define('PHPMAN_HOME', '__PHPMAN_HOME__');
define('PHPMAN_VERSION', '__PHPMAN_VERSION__');
define('GIT_DESCRIBE', '__GIT_DESCRIBE__');


// Load all source files (config defaults + functions + classes)
// Resolve src/: dev (next to phpMan.php) or deployed (PHPMAN_HOME/src/)
$srcDir = is_dir(__DIR__ . '/src') ? __DIR__ . '/src' : PHPMAN_HOME . '/src';
require_once $srcDir . '/config.php';
require $srcDir . '/bootstrap.php';

// Test mode: load functions only, skip dispatch
if (defined("PHPMAN_TEST_MODE")) { return; }

// CLI tools define PHPMAN_NO_CLI_DISPATCH to skip web dispatch
if (defined("PHPMAN_NO_CLI_DISPATCH")) return;


// page content
$content = "";
//output mode
$mode = "";
$parameter = "";
$section = "";
$isSearchFallback = false;
$isListContent = false;

$check['man'] = "";
$check['perldoc'] = "";
$check['info'] = "";
$check['search'] = "";
$check['pydoc'] = "";
$check['ri'] = "";

// Detect format preference via: 1) GET param, 2) Accept header, 3) PATH_INFO segment, 4) default HTML
$format = "html";
$formatSource = "default"; // track where format was decided

// 1) GET parameter always takes highest priority
if (getQueryParam("format") === "json") {
    $format = "json";
    $formatSource = "get";
} elseif (getQueryParam("format") === "markdown") {
    $format = "markdown";
    $formatSource = "get";
} else {
    // 2) Accept header negotiation
    $accept = strtolower(serverValue("HTTP_ACCEPT", ""));
    if (strpos($accept, "application/json") !== false) {
        $format = "json";
        $formatSource = "accept_header";
    } elseif (strpos($accept, "text/markdown") !== false || strpos($accept, "text/x-markdown") !== false) {
        $format = "markdown";
        $formatSource = "accept_header";
    }
}

// 3) PATH_INFO segment overrides Accept header (but not GET)
/**
 * trans$_SERVER["ORIG_PATH_INFO"] to $_SERVER["PATH_INFO"]
 * for cgi/fcgi mode of php
 */
if ( serverValue("ORIG_PATH_INFO") !== "" ){
    $_SERVER["PATH_INFO"] = serverValue("ORIG_PATH_INFO");
}

// Handle /.well-known/mcp.json for MCP server discovery (GET only)
if (serverValue("PATH_INFO") !== "" && strpos(serverValue("PATH_INFO"), "/.well-known/mcp.json") === 0) {
    handleWellKnown();
    exit;
}

// Guard: reject URL attacks and scanner probes.
// Normal URLs like /man/tar/1/markdown (4 segments, ~24 chars) are unaffected.
// Catches: /man/DUPLICITY/sftp:/onedrive:/gdocs:/... (protocol prefix crawl trap)
//          /man/Dpkg::Control::HashCore (Perl module with ::) is ALLOWED.
$pathInfo = serverValue("PATH_INFO", "");
$pathError = validatePathInfo($pathInfo);
if ($pathInfo !== "" && $pathError !== "") {
    http_response_code(403);
    header("Content-Type: text/plain; charset=UTF-8");
    die("403 Forbidden: malformed PATH_INFO ({$pathError})\n");
}

/**
 * parse parameters from $_SERVER["PATH_INFO"]: phpMan.php/MODE/COMMAND/SECTION/FORMAT
 * or parse parameters from HTTP/GET
 */
if ( serverValue("PATH_INFO") !== "" && trim(serverValue("PATH_INFO")) != "") {
    $array_param = explode('/', serverValue("PATH_INFO"));
    $segments = [];
    foreach ($array_param as $p) {
        $p_trimmed = trim($p);
        if ($p_trimmed !== "") {
            $segments[] = $p_trimmed;
        }
    }
    
    $allowed_modes = array("man", "perldoc", "info", "search", "copyright", "mcp", ".well-known", "pydoc", "ri");
    $seg_count = count($segments);
    
    if ($seg_count >= 1) {
        $first_seg = strtolower($segments[0]);
        if (in_array($first_seg, $allowed_modes)) {
            $mode = $first_seg;
            
            if ($seg_count >= 2) {
                $parameter = urldecode($segments[1]);
            }
            if ($seg_count >= 3) {
                $third_seg_lower = strtolower($segments[2]);
                if (in_array($third_seg_lower, PHPMAN_OUTPUT_FORMATS)) {
                    $format = $third_seg_lower;
                } else {
                    $section = $segments[2];
                }
            }
            if ($seg_count >= 4) {
                $fourth_seg_lower = strtolower($segments[3]);
                if (in_array($fourth_seg_lower, PHPMAN_OUTPUT_FORMATS)) {
                    $format = $fourth_seg_lower;
                } else {
                    $section = $segments[3];
                }
            }
        } else {
            // Mode is NOT explicitly provided, default to 'man'
            $mode = "man";
            $parameter = urldecode($segments[0]);
            
            if ($seg_count >= 2) {
                $second_seg_lower = strtolower($segments[1]);
                if (in_array($second_seg_lower, PHPMAN_OUTPUT_FORMATS)) {
                    $format = $second_seg_lower;
                } else {
                    $section = $segments[1];
                }
            }
            if ($seg_count >= 3) {
                $third_seg_lower = strtolower($segments[2]);
                if (in_array($third_seg_lower, PHPMAN_OUTPUT_FORMATS)) {
                    $format = $third_seg_lower;
                } else {
                    $section = $segments[2];
                }
            }
        }

        // #45: a format-eligible segment that is neither a known format nor a
        // valid section name used to be erased by normalizeSection() and then
        // served as the default section in HTML — a silent 200 for what is
        // really a bad URL. Converge on the canonical URL instead, before any
        // content lookup, so the client gets what it asked for and no page is
        // rendered. malformedSegmentRedirect() builds the target.
        // Path mode is passed on so the check knows whether a section segment
        // means anything here (man/search) or is noise to converge away.
        $pathMode = in_array(strtolower($segments[0]), $allowed_modes) ? strtolower($segments[0]) : "";
        $canonical = malformedSegmentRedirect($segments, $pathMode !== "" ? 2 : 1, $pathMode);
        if ($canonical !== null) {
            header('Location: ' . baseUrl() . $canonical, true, 301);
            header('Cache-Control: public, max-age=86400');
            exit;
        }
    }
}
else {
    if ( getQueryParam("mode") != "" ) {
        $mode = getQueryParam("mode");
    }

    if ( getQueryParam("parameter") != "" ) {
        $parameter = getQueryParam("parameter");
    }

    if ( getQueryParam("section") != "") {
        $section = getQueryParam("section");
    }
}

// GET parameter always overrides
if ( getQueryParam("format") != "" ) {
    $format = strtolower(trim(getQueryParam("format")));
}
$format = in_array($format, PHPMAN_OUTPUT_FORMATS) ? $format : "html";

// .well-known discovery endpoint (e.g. /.well-known/mcp.json)
if ( $mode === ".well-known" ) {
    handleWellKnown();
    exit;
}

// set default mode
$mode = normalizeMode($mode);
$parameter = normalizeParameter($parameter);
$section = normalizeSection($section);
Profiler::mark('parse');

// ETag/304 check before exec-heavy dispatch (#83)
// Key-based ETag: include the cache timestamp so re-indexing invalidates stale ETags.
if ($format === "html" && $mode !== "mcp" && $mode !== "copyright" && $mode !== "search" && $parameter !== "") {
    $cacheAge = '';
    try {
        $db = cacheDb();
        if ($db) {
            $cacheAge = $db->querySingle("SELECT value FROM meta WHERE key = 'search_index_updated'") ?: '';
        }
    } catch (\Throwable $ignored) {
        phpManLog("ETag DB query failed: " . $ignored->getMessage());
    }
    $etag = '"' . md5($mode . '/' . $parameter . '/' . $section . '/' . PHPMAN_VERSION . '/' . $cacheAge) . '"';
    $ifNoneMatch = serverValue("HTTP_IF_NONE_MATCH", "");
    if ($ifNoneMatch === $etag) {
        http_response_code(304);
        exit;
    }
} else {
    $etag = "";
}

/**
 * 获取标题用的一句话说明（man page NAME 段 / apropos description）。
 * man/pydoc/ri/perldoc 都在 search_fts 有 description（perldoc 的 name 在
 * section 3perl/3pm 段）；info 无 FTS5 索引返回空串。
 * 查询失败时安全退化为空串，不影响页面渲染。
 */
function getTitleDescription (string $mode, string $parameter, string $section): string {
    if ($mode === 'info') return '';  // info 无 FTS5 索引
    try {
        $db = cacheDb();
        if ($db === null) return '';
        // section 过滤：pydoc/ri 用模式名；man 有 section 用真实 section；
        // man 无 section / perldoc 不按 section 过滤（perldoc name 在 3perl/3pm 段）
        $sec = '';
        if ($mode === 'pydoc' || $mode === 'ri') {
            $sec = $mode;
        } elseif ($mode === 'man' && $section !== '') {
            $sec = $section;
        }
        if ($sec === '') {
            $stmt = $db->prepare("SELECT description FROM search_fts WHERE name = :n OR name LIKE :p LIMIT 1");
            $stmt->bindValue(':n', $parameter, SQLITE3_TEXT);
            $stmt->bindValue(':p', $parameter . ' %', SQLITE3_TEXT);
        } else {
            $stmt = $db->prepare("SELECT description FROM search_fts WHERE section = :s AND (name = :n OR name LIKE :p) LIMIT 1");
            $stmt->bindValue(':s', $sec, SQLITE3_TEXT);
            $stmt->bindValue(':n', $parameter, SQLITE3_TEXT);
            $stmt->bindValue(':p', $parameter . ' %', SQLITE3_TEXT);
        }
        $row = $stmt->execute()->fetchArray(SQLITE3_ASSOC);
        if ($row && !empty($row['description'])) {
            $desc = trim(strip_tags((string)$row['description']));
            if (function_exists('mb_strlen') && mb_strlen($desc) > 80) {
                $desc = mb_substr($desc, 0, 80) . '...';
            }
            return $desc;
        }
    } catch (\Throwable $ignored) {
        // 忽略 description 查询失败，标题退化为无 description
    }
    return '';
}

/**
 * Resolve the section a man page actually lives in, for a request that named a
 * different one. Returns a section only when it is unambiguous: a command
 * present in several sections (time(1) vs time(3am) vs time(7)) must not be
 * guessed at, or we would pick one of them arbitrarily.
 *
 * Legacy URLs arrive here too. "mcp" was a public output format until 78d2a11
 * removed it, so /man/<cmd>/mcp now parses as section "mcp" — not a section at
 * all, just a leftover format segment. Treating it as an unresolvable section
 * sends those links to the command's real page rather than 404.
 *
 * Uses search_index_meta rather than search_fts: it is indexed on
 * (name, section, source), so this is a covering-index lookup, whereas the same
 * filter against the FTS5 table scans it.
 */
function resolveManSection (string $name): ?string {
    if ($name === '') return null;
    try {
        $db = cacheDb();
        if ($db === null) return null;
        $stmt = $db->prepare(
            "SELECT DISTINCT section FROM search_index_meta
             WHERE name = :n AND source = 'man' AND section <> ''"
        );
        $stmt->bindValue(':n', $name, SQLITE3_TEXT);
        $result = $stmt->execute();
        $sections = [];
        while ($row = $result->fetchArray(SQLITE3_ASSOC)) $sections[] = $row['section'];
        $result->finalize();
        return count($sections) === 1 ? $sections[0] : null;
    } catch (\Throwable $ignored) {
        // A failed lookup must not turn a 404 into a 500.
        return null;
    }
}

if ( $parameter != "" ) {
    $desc = getTitleDescription($mode, $parameter, $section);
    $namePart = $parameter . ($desc !== "" ? " - " . $desc : "");
    $modePart = ($section !== "") ? $mode . "(" . $section . ")" : $mode;
    $PHPMAN_TITLE = $namePart . " - " . $modePart . " - [phpMan]";
} elseif ($mode !== "" && $mode !== "search" && in_array($mode, PHPMAN_CONTENT_MODES)) {
    $PHPMAN_TITLE = $mode . " - [phpMan]";
}

//show GPL
else if ( $mode == "copyright" ) {
    showHeader($PHPMAN_TITLE, "", "", $mode);
    showCopyright();
    echo "</body></html>";
    exit;
}
// MCP (Model Context Protocol) mode: JSON-RPC over HTTP POST
if ( $mode == "mcp" ) {
    handleMcp();
    exit;
}
/**
 * option checker and get manual page content, if no parameter: get index tree
 * phpMan -- man     -- man page index: section list
 *        |          \- man page by section: command list(via search)
 *        |          \- man page: specified command
 *        \- perldoc -- command list: (by search)
 *        |          \- perldoc page: specified module
 *        \- info    -- info page index: list
 *        |          \- info page:
 *        \- search  -- apropos search results: man page entrance list
 */
switch ( $mode ) {
    case "man":
        $check['man'] = " checked=\"checked\"";
        //show man pages
        if ( $parameter != "" ) {
            // Pre-detect perldoc targets: :: prefix or 3pm/3perl
            if (strpos($parameter, "::") !== false || $section === "3pm" || $section === "3perl") {
                $content = cacheOrExecute('perldoc', $parameter, $section, $format,
                    function() use ($parameter, $format) { return getPerldocPage($parameter, $format); });
            } else {
                $content = cacheOrExecute('man', $parameter, $section, $format,
                    function() use ($parameter, $section, $format) { return getManPage($parameter, $section, $format); });
            }

            // retry lower case if content is empty
            if ( preg_match("/^[A-Z\\._]+$/",$parameter) && trim($content) == ""){
                $content = cacheOrExecute('man', strtolower($parameter), $section, $format,
                    function() use ($parameter, $section, $format) { return getManPage(strtolower($parameter), $section, $format); });
            }

            //not find command then try perldoc (for perl modules with :: or section 3pm/3perl)
            //before falling back to search
            if (trim($content) == "") {
                if (strpos($parameter, "::") !== false || $section === "3pm" || $section === "3perl") {
                    $content = cacheOrExecute('perldoc', $parameter, $section, $format,
                        function() use ($parameter, $format) { return getPerldocPage($parameter, $format); });
                }
            }

            //still not found then redirect to search sections
            if (trim($content) == "") {
                // Wrong section? Commands move between sections, and links from
                // before 78d2a11 name "mcp" in the section position — a format
                // segment that is no longer a format. When the command lives in
                // exactly one section, converge on its canonical URL instead of
                // answering 404. /man/<cmd>/<section> is the form the sitemap and
                // the JSON canonical already use. Ambiguous commands (several
                // sections) and unknown ones still fall through to the search
                // fallback and its 404.
                if ($section !== '') {
                    $realSection = resolveManSection($parameter);
                    if ($realSection !== null && $realSection !== $section) {
                        $target = baseUrl() . '/' . rawurlencode($mode) . '/' . rawurlencode($parameter)
                                . '/' . rawurlencode($realSection)
                                . ($format !== 'html' ? '/' . rawurlencode($format) : '');
                        header('Location: ' . $target, true, 301);
                        header('Cache-Control: public, max-age=86400');
                        exit;
                    }
                }
                $content = getSearchPage($parameter, $section, $format);
                $isSearchFallback = true;
                http_response_code(404);
                $cache = new PageCache();
                $cache->set('man', $parameter, $section, $format, null, 'not_found');
            }
        }
        //redirect to search sections
        else {
            $content = getManIndex($format);
        }
        break;
    case "perldoc":
        $check['perldoc'] = " checked=\"checked\"";
        if ( $parameter != "" ) {
            $content = cacheOrExecute('perldoc', $parameter, '', $format,
                function() use ($parameter, $format) { return getPerldocPage($parameter, $format); });
            if (trim($content) == "") {
                $cache = new PageCache();
                $cache->set('perldoc', $parameter, '', $format, null, 'not_found');
            }
        }
        else {
            //show all possable perl entrance by search keywords: 'perl'
            // Wrapped in cacheOrExecute like pydoc/ and ri/ indexes — FTS5
            // row-by-row fetching on NFS takes ~5s for 300 rows, caching the
            // rendered HTML makes subsequent visits instant.
            $content = cacheOrExecute('perldoc', '__index__', '', $format,
                function() use ($format) { return getPerldocIndex($format); });
            $isListContent = true;
        }
        break;
    case "info":
        $check['info'] = " checked=\"checked\"";
        if ( $parameter != "" ) {
            $content = cacheOrExecute('info', $parameter, '', $format,
                function() use ($parameter, $format) { return getInfoPage($parameter, $format); });
            if (trim($content) == "") {
                $cache = new PageCache();
                $cache->set('info', $parameter, '', $format, null, 'not_found');
            }
        }
        else {
            $content = getInfoIndex($format);
        }
        break;
    case "search":
        $check['search'] = " checked=\"checked\"";
        if ( $parameter != "" ) {
            $content = cacheOrExecute('search', $parameter, $section, $format,
                function() use ($parameter, $section, $format) {
                    $source = 'apropos';
                    $inner = getSearchPage($parameter, $section, $format, $source);
                    Profiler::mark('fts:done');

                    // Cascade to pydoc3 and ri — always check FTS5 (fast),
                    // command-line only when man search had no results.
                    $hasManResults = ($inner !== "" && $inner !== "<ul>\n</ul>\n");
                    if ($format === "html") {
                        $inner = "<h2>" . ($source === 'fts' ? 'man' : 'apropos') . "</h2>\n" . $inner . "\n";
                        $pydocResults = searchFtsBySource($parameter, 'pydoc', 'html');
                        if ($pydocResults === "" && !$hasManResults) {
                            $pydocResults = getPydocSearchPage($parameter, "html");
                        }
                        Profiler::mark('pydoc:done');
                        if ($pydocResults !== "") {
                            $inner .= "<h2>Python 3 (pydoc3)</h2>\n" . $pydocResults . "\n";
                        }
                        $riResults = searchFtsBySource($parameter, 'ri', 'html');
                        if ($riResults === "") {
                            $riResults = getRiSearchPage($parameter, "html");
                        }
                        Profiler::mark('ri:done');
                        if ($riResults !== "") {
                            $inner .= "<h2>Ruby (ri)</h2>\n" . $riResults . "\n";
                        }
                    } elseif ($format === "markdown") {
                        $inner = "## " . ($source === 'fts' ? 'man' : 'apropos') . "\n\n" . $inner . "\n";
                        $pydocResults = searchFtsBySource($parameter, 'pydoc', 'markdown');
                        if ($pydocResults === "") {
                            $pydocResults = getPydocSearchPage($parameter, "markdown");
                        }
                        Profiler::mark('pydoc:done');
                        if ($pydocResults !== "") {
                            $inner .= "\n\n## Python 3 (pydoc3)\n\n" . $pydocResults;
                        }
                        $riResults = searchFtsBySource($parameter, 'ri', 'markdown');
                        if ($riResults === "") {
                            $riResults = getRiSearchPage($parameter, "markdown");
                        }
                        Profiler::mark('ri:done');
                        if ($riResults !== "") {
                            $inner .= "\n\n## Ruby (ri)\n\n" . $riResults;
                        }
                    } elseif ($format === "json" || $format === "mcp") {
                        $current = json_decode($inner, true);
                        if ($current === null) $current = [];
                        $pydocFts = searchFtsBySource($parameter, 'pydoc', 'json');
                        Profiler::mark('pydoc:done');
                        if (!empty($pydocFts)) {
                            $current["pydoc_results"] = $pydocFts;
                        } else {
                            $pydocJson = getPydocSearchPage($parameter, "json");
                            if ($pydocJson !== "") {
                                $pydocData = json_decode($pydocJson, true);
                                if ($pydocData !== null) $current["pydoc_results"] = $pydocData["results"] ?? [];
                            }
                        }
                        $riFts = searchFtsBySource($parameter, 'ri', 'json');
                        Profiler::mark('ri:done');
                        if (!empty($riFts)) {
                            $current["ri_results"] = $riFts;
                        } else {
                            $riJson = getRiSearchPage($parameter, "json");
                            if ($riJson !== "") {
                                $riData = json_decode($riJson, true);
                                if ($riData !== null) $current["ri_results"] = $riData["results"] ?? [];
                            }
                        }
                        $inner = json_encode($current, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
                        if ($format === "mcp") {
                            $inner = formatForOutput($inner, "mcp");
                        }
                    }
                    return $inner;                });
        }
        break;
    case "pydoc":
        $check['pydoc'] = " checked=\"checked\"";
        if ( $parameter != "" ) {
            $content = cacheOrExecute('pydoc', $parameter, '', $format,
                function() use ($parameter, $format) { return getPydocPage($parameter, $format); });
            if (trim($content) == "") {
                $content = getPydocSearchPage($parameter, $format);
                $isSearchFallback = true;
                http_response_code(404);
                // Cache 404
                $cache = new PageCache();
                $cache->set('pydoc', $parameter, '', $format, null, 'not_found');
            }
        }
        else {
            $content = cacheOrExecute('pydoc', '__index__', '', $format,
                function() use ($format) { return getPydocIndex($format); });
            $isListContent = true;
        }
        break;
    case "ri":
        $check['ri'] = " checked=\"checked\"";
        if ( $parameter != "" ) {
            $content = cacheOrExecute('ri', $parameter, '', $format,
                function() use ($parameter, $format) { return getRiPage($parameter, $format); });
            if (trim($content) == "") {
                $content = getRiSearchPage($parameter, $format);
                $isSearchFallback = true;
                http_response_code(404);
                // Cache 404
                $cache = new PageCache();
                $cache->set('ri', $parameter, '', $format, null, 'not_found');
            }
        }
        else {
            $content = cacheOrExecute('ri', '__index__', '', $format,
                function() use ($format) { return getRiIndex($format); });
            $isListContent = true;
        }
        break;
}

// Profiler: content generation complete
Profiler::mark('content');

// #244: telemetry for the machine formats. Before the format branches so one
// call covers all three, and before the body is echoed — so a 5xx with no line
// from here means the process died mid-render rather than finishing and failing
// at delivery. See phpManLogMachineRender().
if ($format === "markdown" || $format === "json" || $format === "mcp") {
    phpManLogMachineRender($mode, $parameter, $section, $format, $content);
}

// Show Markdown or HTML output
if ($format === "markdown") {
    header("Content-Type: text/markdown; charset=UTF-8");
    header("X-Content-Type-Options: nosniff");
    header("X-Frame-Options: DENY");
    header("Last-Modified: " . gmdate("D, d M Y H:i:s") . " GMT");
    header("Expires: " . gmdate("D, d M Y H:i:s", time() + 3600 * 24 * 7) . " GMT");
    // Append profiling data as HTML comment
    if (Profiler::getEnabled()) {
        $report = Profiler::getReport();
        $total = $report['_total_ms'] ?? 0;
        unset($report['_total_ms'], $report['_version']);
        $lines = [];
        foreach ($report as $r) {
            $lines[] = sprintf("  %-20s %6.2fms  (+%6.2fms)", $r['label'], $r['elapsed_ms'], $r['delta_ms']);
        }
        $content .= "\n\n<!-- profile:\n" . implode("\n", $lines) . "\n  total: {$total}ms\n-->\n";
    }
    echo "# " . $PHPMAN_TITLE . "\n\n" . $content;
    exit;
}

// Show JSON or MCP output
if ($format === "json" || $format === "mcp") {
    // Append profiling data as _profiling key.
    // See appendProfilingJson() — injected into the serialised body rather than
    // decoded and re-encoded, which would double the peak of a large response.
    if (Profiler::getEnabled()) {
        $content = appendProfilingJson($content, Profiler::getReport());
    }
    header("Content-Type: application/json; charset=UTF-8");
    header("X-Content-Type-Options: nosniff");
    header("X-Frame-Options: DENY");
    // ETag based on actual content hash — ensures 304 only when body is identical
    $etag = '"' . md5($content) . '"';
    header("ETag: {$etag}");
    $ifNoneMatch = serverValue("HTTP_IF_NONE_MATCH", "");
    if ($ifNoneMatch === $etag) {
        http_response_code(304);
        exit;
    }
    header("Last-Modified: " . gmdate("D, d M Y H:i:s") . " GMT");
    header("Expires: " . gmdate("D, d M Y H:i:s", time() + 3600 * 24 * 7) . " GMT");
    // Gzip compress large JSON responses (bash=351KB → ~97KB)
    $acceptEncoding = strtolower(serverValue("HTTP_ACCEPT_ENCODING", ""));
    if (strpos($acceptEncoding, "gzip") !== false && function_exists("gzencode") && strlen($content) > PHPMAN_GZIP_MIN_BYTES) {
        $gzipped = gzencode($content, 6);
        if ($gzipped !== false) {
            header("Content-Encoding: gzip");
            header("Vary: Accept-Encoding");
            header("Content-Length: " . strlen($gzipped));
            echo $gzipped;
            exit;
        }
    }
    echo $content;
    exit;
}

// +--------------------------------------------------------------------------------+
// | show output                                                                    |
// +--------------------------------------------------------------------------------+
// Line threshold: ~80 lines ≈ two screens at 14px monospace
$lineThreshold = PHPMAN_TOC_THRESHOLD;
// Determine if this page has real content (for robots meta)
// Search results and build-index pages should be noindex
$hasRealContent = (trim($content) !== "" && !$isSearchFallback && $mode !== "search");

// Count content lines and set body class for CSS-based show/hide
$showNav = false;
if ($hasRealContent) {
    $showNav = (substr_count($content, "\n") + 1 > $lineThreshold);
}

// ETag already computed before exec() dispatch (#83)
Profiler::mark('render');

showHeader($PHPMAN_TITLE, $parameter, $section, $mode, $hasRealContent, $showNav, $etag);

// H1 breadcrumb: mode > command(section)
$modes = ["man" => ["label" => "man", "url" => "/man"], "perldoc" => ["label" => "perldoc", "url" => "/search/perl"], "info" => ["label" => "info", "url" => "/info"], "pydoc" => ["label" => "pydoc", "url" => "/pydoc"], "ri" => ["label" => "ri", "url" => "/ri"]];
if ($parameter !== "" && $mode !== "" && $mode !== "search") {
    $bc_parts = [];
    if (isset($modes[$mode])) {
        $bc_parts[] = "<a href=\"".h(scriptName() . $modes[$mode]["url"])."\">".h($modes[$mode]["label"])."</a>";
    }
    $section_label = $section !== "" ? "({$section})" : "";
    $bc_parts[] = h($parameter . $section_label);
    echo "<h1>" . implode(" &gt; ", $bc_parts) . "</h1>\n";
} elseif ($mode !== "" && $mode !== "search" && isset($modes[$mode])) {
    echo "<h1>" . h($modes[$mode]["label"]) . "</h1>\n";
} else {
    echo "<h1><a href=\"".h(scriptName())."\">".h($PHPMAN_TITLE)."</a></h1>\n";
}

// Build markdown/JSON URLs for format links (showForm + showFooter)
$markdownUrl = "";
$jsonUrl = "";
$script_name_path = baseUrl();

// Detail pages (actual man/perldoc/info/pydoc/ri content): pathinfo URLs
if ($content !== ""
    && in_array($mode, PHPMAN_CONTENT_MODES)
    && $parameter !== ""
    && $mode !== "search"
) {
    // Determine if content is real content (not index/search fallback)
    // For man mode: if parameter was given and content is not from search redirect
    $isDetailPage = false;
    if ($mode === "man" && trim($content) !== "" && !$isSearchFallback) {
        $isDetailPage = true;
    }
    if ($mode === "perldoc" && $parameter !== "") {
        $isDetailPage = true;
    }
    if ($mode === "info" && $parameter !== "") {
        $isDetailPage = true;
    }
    if ($mode === "pydoc" && trim($content) !== "" && !$isSearchFallback) {
        $isDetailPage = true;
    }
    if ($mode === "ri" && trim($content) !== "" && !$isSearchFallback) {
        $isDetailPage = true;
    }

    if ($isDetailPage) {
        $markdownUrl = $script_name_path . "/" . $mode . "/" . urlencode($parameter);
        if ($mode === "man" && $section !== "") {
            $markdownUrl .= "/" . $section;
        }
        $markdownUrl .= "/markdown";

        $jsonUrl = $script_name_path . "/" . $mode . "/" . urlencode($parameter);
        if ($mode === "man" && $section !== "") {
            $jsonUrl .= "/" . $section;
        }
        $jsonUrl .= "/json";
    }
}
// Index pages (man/perldoc/info without parameter): query param URLs
elseif ($content !== "" && in_array($mode, PHPMAN_CONTENT_MODES) && $parameter === "") {
    $markdownUrl = $script_name_path . "?mode=" . urlencode($mode) . "&format=markdown";
    $jsonUrl = $script_name_path . "?mode=" . urlencode($mode) . "&format=json";
}
// Search results pages: query param URLs
elseif ($mode === "search" && $parameter !== "") {
    $markdownUrl = $script_name_path . "?parameter=" . urlencode($parameter) . "&mode=search&format=markdown";
    $jsonUrl = $script_name_path . "?parameter=" . urlencode($parameter) . "&mode=search&format=json";
}

echo "<div id=\"content-wrap\">\n";
showForm($parameter, $check, $mode, $section, $markdownUrl, $jsonUrl);

	// v2.2: TLDR block for man section 1 detail pages
	if ($mode === "man" && $parameter !== "" && trim($content) !== "") {
	    $tldrData = fetchOfficialTldr($parameter, $mode, $section);
	    // Filter out empty commands from malformed data before checking
	    $tldrExamples = [];
	    if (!empty($tldrData) && !empty($tldrData["examples"])) {
	        $tldrExamples = array_filter($tldrData["examples"], function ($ex) {
	            return !empty(trim($ex["command"] ?? ""));
	        });
	    }
	    // Only render when we have at least one real example with a command
	    if (!empty($tldrExamples)) {
	        echo "<div class=\"tldr-block\">\n";
	        echo "<div class=\"tldr-header\">";
	        $src = $tldrData["source"] === "cheatsh" ? "cheat.sh" : "tldr-pages";
	        $tldrLink = $tldrData["source"] === "cheatsh"
	            ? "https://cheat.sh/" . urlencode(strtolower($parameter))
	            : "https://tldr.inbrowser.app/pages/common/" . urlencode(strtolower($parameter));
	        echo "&#9889; <a href=\"{$tldrLink}\" target=\"_blank\" rel=\"noopener\" style=\"color:inherit;text-decoration:none;border-bottom:1px dotted\">TLDR: " . h($parameter) . "</a> <span class=\"tldr-source\">({$src})</span></div>\n";
	        echo "<div class=\"tldr-body\">\n";
	        if (!empty($tldrData["description"])) {
	            echo "<p class=\"tldr-desc\">" . h($tldrData["description"]) . "</p>\n";
	        }
	        echo "<ul class=\"tldr-examples\">\n";
	        foreach (array_slice($tldrExamples, 0, 10) as $ex) {
	            $desc = $ex["description"] ?? "";
	            $desc = preg_replace('/\[(.)\]/', '<b>$1</b>', h($desc));
	            echo "<li>{$desc}<br /><code>" . h($ex["command"] ?? "") . "</code></li>\n";
	        }
	        echo "</ul>\n";
	        echo "</div></div>\n";
	    }
	}

	// For man page content, add section anchors and floating TOC
	// Sidebars are collected and output AFTER content for better SEO
	$tocSidebar = '';
	if ($mode !== "markdown" && $mode !== "search" && !$isSearchFallback && $parameter !== "" && trim($content) !== "") {
	    list($anchoredContent, $tocItems) = addManPageToc($content);

	    if ($showNav) {
	        $pageLabel = $parameter . ($section !== "" ? "({$section})" : "");
	        $tocSidebar = renderTocSidebar($tocItems, $pageLabel);
	    }

	    echo "<div id=\"man-content\"><pre>" . $anchoredContent . "</pre></div>\n";
	} elseif ($isSearchFallback || $mode === "search" || $isListContent) {
	    echo "<div id=\"man-content\">" . $content . "</div>\n";
	} else {
	    echo "<pre>" . $content . "</pre>\n";
	}
	echo "</div>";
	echo $tocSidebar;

showFooter($VALIDATOR, $showNav, $mode, $parameter, $section, $markdownUrl, $jsonUrl);


// +--------------------------------------------------------------------------------+
// | sub functions                                                                  |
// +--------------------------------------------------------------------------------+

//show html header