diff options
| author | Soccera1 <[email protected]> | 2026-07-28 15:54:54 +1000 |
|---|---|---|
| committer | Soccera1 <[email protected]> | 2026-07-28 15:54:54 +1000 |
| commit | 6a2f098e72e71437154ec00506e8e736aa8e1026 (patch) | |
| tree | 63e9f5596be38558dbeb40bb566735759a3ccabb /scripts/import-gnu-docs.js | |
| parent | a753f669c9bedfccb9f7f400da018bb487dca5d0 (diff) | |
| download | bnu-6a2f098e72e71437154ec00506e8e736aa8e1026.tar.gz bnu-6a2f098e72e71437154ec00506e8e736aa8e1026.zip | |
Add docs
Diffstat (limited to 'scripts/import-gnu-docs.js')
| -rw-r--r-- | scripts/import-gnu-docs.js | 348 |
1 files changed, 348 insertions, 0 deletions
diff --git a/scripts/import-gnu-docs.js b/scripts/import-gnu-docs.js new file mode 100644 index 0000000..9c5a80c --- /dev/null +++ b/scripts/import-gnu-docs.js @@ -0,0 +1,348 @@ +#!/usr/bin/env bun + +import { + copyFile, + mkdir, + mkdtemp, + readFile, + readdir, + rm, + writeFile, +} from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { basename, dirname, join, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; +import { commandNames } from "../src/coreutils.js"; + +const projectRoot = resolve(dirname(fileURLToPath(import.meta.url)), ".."); +const archive = resolve(process.argv[2] ?? join(projectRoot, "coreutils-9.11.tar.xz")); +const manDir = join(projectRoot, "man"); +const docDir = join(projectRoot, "doc"); +const temporaryDir = await mkdtemp(join(tmpdir(), "bnu-doc-import-")); + +try { + const listing = run("tar", ["-tf", archive]).trim().split("\n"); + const archiveRoot = listing[0]?.split("/", 1)[0]; + if (!archiveRoot || !listing.includes(`${archiveRoot}/man/`) || !listing.includes(`${archiveRoot}/doc/`)) { + throw new Error(`${basename(archive)} does not look like a GNU Coreutils source archive`); + } + + run("tar", [ + "-xf", + archive, + "-C", + temporaryDir, + `${archiveRoot}/man`, + `${archiveRoot}/doc`, + ]); + + await mkdir(manDir, { recursive: true }); + await mkdir(docDir, { recursive: true }); + + const upstreamManDir = join(temporaryDir, archiveRoot, "man"); + const manPages = (await readdir(upstreamManDir)).filter((name) => name.endsWith(".1")).sort(); + for (const name of manPages) { + const source = await readFile(join(upstreamManDir, name), "utf8"); + await writeFile(join(manDir, name), adaptManPage(source, name)); + } + + const sha256sum = await readFile(join(upstreamManDir, "sha256sum.1"), "utf8"); + await writeFile(join(manDir, "sm3sum.1"), adaptSm3ManPage(sha256sum)); + await writeFile(join(manDir, "[.1"), bracketAliasManPage()); + await writeFile(join(manDir, "ginstall.1"), ginstallAliasManPage()); + const documentedCommands = new Set([ + ...manPages.map((name) => name.slice(0, -2)), + "[", + "ginstall", + "sm3sum", + ]); + const undocumentedCommands = commandNames.filter((name) => !documentedCommands.has(name)); + if (undocumentedCommands.length) { + throw new Error(`Missing manual pages for: ${undocumentedCommands.join(", ")}`); + } + + const texinfoSources = [ + "constants.texi", + "fdl.texi", + "parse-datetime.texi", + "perm.texi", + "sort-version.texi", + ]; + for (const name of texinfoSources) { + await copyFile(join(temporaryDir, archiveRoot, "doc", name), join(docDir, name)); + } + + const upstreamTexinfo = await readFile(join(temporaryDir, archiveRoot, "doc", "coreutils.texi"), "utf8"); + await writeFile(join(docDir, "bnu.texi"), adaptTexinfo(upstreamTexinfo)); + await writeFile( + join(docDir, "version.texi"), + "@set UPDATED 28 July 2026\n@set UPDATED-MONTH July 2026\n@set EDITION 9.11\n@set VERSION 9.11\n", + ); + + run("makeinfo", [ + "--no-split", + "-c", + "CHECK_NORMAL_MENU_STRUCTURE=1", + "-I", + docDir, + "-o", + join(docDir, "bnu.info"), + join(docDir, "bnu.texi"), + ]); + + console.log(`Imported ${manPages.length} GNU manual pages; covered all ${commandNames.length} BNU commands.`); + console.log(`Wrote ${join(docDir, "bnu.info")} from the adapted Texinfo source.`); +} finally { + await rm(temporaryDir, { recursive: true, force: true }); +} + +function run(command, args) { + const result = Bun.spawnSync([command, ...args], { + cwd: projectRoot, + stdout: "pipe", + stderr: "pipe", + }); + if (!result.success) { + const detail = result.stderr.toString().trim(); + throw new Error(`${command} failed${detail ? `: ${detail}` : ""}`); + } + return result.stdout.toString(); +} + +function replaceRequired(text, search, replacement, description) { + const next = text.replace(search, replacement); + if (next === text) throw new Error(`Could not adapt ${description}; the upstream documentation changed`); + return next; +} + +function adaptManPage(source, name) { + source = source.replaceAll("documents the GNU version of", "describes the BNU implementation of"); + let text = replaceRequired( + source, + /^\.\\" DO NOT MODIFY THIS FILE!.*$/m, + '.\\" Adapted for BNU from the GNU Coreutils 9.11 manual page; see doc/README.md.', + `${name} generation notice`, + ); + text = replaceRequired( + text, + /^(\.TH [^\n]+ "1") "[^"]+" "GNU coreutils 9\.11" "User Commands"$/m, + '$1 "2026-07-28" "BNU 9.11" "BNU Commands"', + `${name} title`, + ); + text = replaceRequired( + text, + /\.SH DESCRIPTION\n(?:\.\\" Add any additional description here\n)?/, + '.SH DESCRIPTION\n.\\" This page is derived from GNU Coreutils documentation.\nThis page documents BNU, an independent Bun implementation compatible with\nGNU Coreutils 9.11.\n', + `${name} description`, + ); + text = replaceRequired( + text, + /\.SH AUTHOR\n([\s\S]*?)\n\.SH "REPORTING BUGS"/, + '.SH AUTHORS\nUpstream GNU Coreutils documentation authors:\n$1\n.br\nAdapted for BNU; the BNU implementation is independent.\n.SH "REPORTING BUGS"', + `${name} authors`, + ); + text = replaceRequired( + text, + /Report bugs to: bug\\-coreutils@gnu\.org\n\.br\nGNU coreutils home page: <https:\/\/www\.gnu\.org\/software\/coreutils\/>\n\.br\nGeneral help using GNU software: <https:\/\/www\.gnu\.org\/gethelp\/>\n\.br\nReport any translation bugs to <https:\/\/translationproject\.org\/team\/>/, + 'Report BNU bugs at <https://github.com/Soccera1/bnu/issues>.\n.br\nFor upstream GNU Coreutils, see <https://www.gnu.org/software/coreutils/>.', + `${name} bug reporting`, + ); + text = replaceRequired( + text, + "Copyright \\(co 2026 Free Software Foundation, Inc.", + "Copyright \\(co 2026 Free Software Foundation, Inc.\n.br\nThis manual page was adapted for BNU in 2026.", + `${name} modification notice`, + ); + text = replaceRequired( + text, + /Full documentation (<https:\/\/www\.gnu\.org\/software\/coreutils\/[^>]+>)\n\.br\nor available locally via: info \\\(aq\(coreutils\) ([^\n]+)/, + 'Upstream documentation $1\n.br\nBNU documentation is available locally via: info \\(aq(bnu) $2', + `${name} Info reference`, + ); + return text; +} + +function adaptSm3ManPage(source) { + let text = source + .replaceAll("SHA256SUM", "SM3SUM") + .replaceAll("sha256sum", "sm3sum") + .replaceAll("SHA256", "SM3"); + text = replaceRequired( + text, + "The sums are computed as described in FIPS\\-180\\-2.", + "The sums are computed with the 256\\-bit SM3 cryptographic hash algorithm.", + "sm3sum algorithm description", + ); + text = text.replace("info \\(aq(coreutils) sha2 utilities\\(aq", "info \\(aq(coreutils) sm3sum invocation\\(aq"); + return adaptManPage(text, "sm3sum.1"); +} + +function bracketAliasManPage() { + return String.raw`.TH "[" "1" "2026-07-28" "BNU 9.11" "BNU Commands" +.SH NAME +[ \- evaluate a conditional expression +.SH SYNOPSIS +.B [ +\fI\,EXPRESSION \/\fR] +.br +.B [ ] +.br +.B [ +\fI\,OPTION\/\fR +.SH DESCRIPTION +.B [ +is BNU's alternate form of +.BR test (1). +The closing bracket must be a separate final operand. To request help or +version information, omit the closing bracket and use +.B [ --help +or +.BR "[ --version" . +.SH "REPORTING BUGS" +Report BNU bugs at <https://github.com/Soccera1/bnu/issues>. +.SH "SEE ALSO" +.BR test (1) +.PP +BNU documentation is available locally via: info \(aq(bnu) test invocation\(aq +`; +} + +function ginstallAliasManPage() { + return String.raw`.TH GINSTALL "1" "2026-07-28" "BNU 9.11" "BNU Commands" +.SH NAME +ginstall \- copy files and set attributes +.SH SYNOPSIS +.B ginstall +[\fI\,OPTION\/\fR]... [\fI\,OPERAND\/\fR]... +.SH DESCRIPTION +.B ginstall +is a BNU alias for +.BR install (1). +It accepts the same invocation forms and options. The alias is provided for +environments where the unprefixed name is occupied by another program. +.SH "REPORTING BUGS" +Report BNU bugs at <https://github.com/Soccera1/bnu/issues>. +.SH "SEE ALSO" +.BR install (1) +.PP +BNU documentation is available locally via: info \(aq(bnu) install invocation\(aq +`; +} + +function adaptTexinfo(source) { + let text = replaceRequired(source, "@setfilename coreutils.info", "@setfilename bnu.info", "Info file name"); + text = replaceRequired(text, "@settitle GNU Coreutils @value{VERSION}", "@settitle BNU Core Utilities @value{VERSION}", "Info title"); + text = text.replaceAll("(coreutils)", "(bnu)"); + text = replaceRequired( + text, + "* Coreutils: (bnu). Core GNU (file, text, shell) utilities.", + "* BNU: (bnu). Core file, text, and shell utilities for Bun.\n* BNU invocation: (bnu)Multi-call invocation. Invoke BNU and its command wrappers.", + "Info directory entry", + ); + text = replaceRequired( + text, + "* install: (bnu)install invocation. Copy files and set attributes.", + "* install: (bnu)install invocation. Copy files and set attributes.\n* ginstall: (bnu)install invocation. Alias for install.", + "ginstall directory entry", + ); + text = replaceRequired( + text, + "* sha2: (bnu)sha2 utilities. Print or check SHA-2 digests.", + "* sha2: (bnu)sha2 utilities. Print or check SHA-2 digests.\n* sm3sum: (bnu)sm3sum invocation. Print or check SM3 digests.", + "sm3sum directory entry", + ); + text = replaceRequired( + text, + "This manual documents version @value{VERSION} of the GNU core\nutilities, including the standard programs for text and file manipulation.", + "This manual documents BNU @value{VERSION}, an independent Bun implementation\nof the GNU Coreutils command-line interface. It is adapted from the GNU\nCoreutils @value{VERSION} manual for the corresponding commands.", + "copying summary", + ); + text = replaceRequired( + text, + "Copyright @copyright{} 1994--2026 Free Software Foundation, Inc.", + "Copyright @copyright{} 1994--2026 Free Software Foundation, Inc.\nCopyright @copyright{} 2026 BNU contributors (adaptations).\n\nThis modified version was adapted for BNU on 28 July 2026. The original\nauthorship and copyright are retained below.", + "Texinfo modification notice", + ); + text = replaceRequired(text, "@title GNU @code{Coreutils}", "@title BNU Core Utilities", "title page"); + text = replaceRequired(text, "@subtitle Core GNU utilities", "@subtitle Core utilities for Bun", "title subtitle"); + text = replaceRequired( + text, + "@author David MacKenzie et al.", + "@author GNU manual: David MacKenzie, Jim Meyering, François Pinard,\n@author Karl Berry, Brian Youmans, and Richard Stallman\n@author BNU modifications: BNU contributors\n@subtitle Published by the BNU project", + "title authors", + ); + text = replaceRequired(text, "@top GNU Coreutils", "@top BNU Core Utilities", "top node"); + + const introductionStart = text.indexOf("This manual is a work in progress:"); + const introductionEnd = text.indexOf("@cindex Berry, K.", introductionStart); + if (introductionStart < 0 || introductionEnd < 0) throw new Error("Could not adapt the Texinfo introduction"); + text = `${text.slice(0, introductionStart)}This is the BNU edition of the GNU Coreutils manual. BNU is an independent\nimplementation for the Bun runtime; it is not built from GNU Coreutils source\nand does not provide GNU Coreutils' internal C interfaces. The command-line\nbehavior described here is BNU's compatibility target. Platform-dependent\nbehavior can vary with the operating system, file system, locale, and available\nsecurity facilities.\n\nWhere this manual and BNU disagree, the installed BNU command's\n@option{--help} output and actual behavior take precedence.\n\n@cindex POSIX\nBNU's utilities aim to be compatible with GNU Coreutils 9.11 and the applicable\nPOSIX interfaces.\n@cindex bugs, reporting\n\nPlease report BNU bugs at\n@uref{https://github.com/Soccera1/bnu/issues}. Include the version number,\nmachine architecture, input files, and the information needed to reproduce the\nproblem: your input, what you expected, what you got, and why it is wrong.\n\nIf you have a problem with @command{sort} or @command{date}, try using the\n@option{--debug} option when available, as its output can help diagnose the\nproblem.\n\nThis edition was adapted from the GNU Coreutils 9.11 manual. The upstream\nmanual's authorship follows.\n\n${text.slice(introductionEnd)}`; + text = replaceRequired( + text, + "What you are reading now is the authoritative documentation\nfor these utilities; the man pages are no longer being maintained.", + "The upstream manual is the authoritative GNU Coreutils documentation.\nThis BNU edition retains and adapts it for BNU's compatible command surface.", + "manual authority statement", + ); + + const multiCallStart = text.indexOf("@c This node is named \"Multi-call invocation\""); + const multiCallEnd = text.indexOf("@node Output of entire files", multiCallStart); + if (multiCallStart < 0 || multiCallEnd < 0) throw new Error("Could not adapt the multi-call section"); + const multiCall = `@c This node keeps the upstream name so command nodes remain easy to find.\n@node Multi-call invocation\n@section @command{bnu}: Multi-call program\n\n@pindex bnu\n@pindex coreutils\n@cindex combined\n@cindex calling combined multi-call program\n\nBNU is normally invoked through its top-level dispatcher. Synopsis:\n\n@example\nbnu @var{command} [@var{argument}]@dots{}\n@end example\n\nRun @samp{bnu --help} to list available commands. A command can also be\nselected by invoking a generated command-name wrapper, for example\n@samp{cat @var{file}} after adding the wrapper directory to @env{PATH}.\n\nFor compatibility with the GNU Coreutils multi-call interface, BNU also\nprovides:\n\n@example\ncoreutils @option{--coreutils-prog=@var{program}} [@var{argument}]@dots{}\n@end example\n\nThe repository command @samp{bun run link-commands -- @var{directory}} creates\nthe wrappers. Running from a source checkout requires the Bun runtime.\n\n`; + text = `${text.slice(0, multiCallStart)}${multiCall}${text.slice(multiCallEnd)}`; + + text = replaceRequired( + text, + "* sha2 utilities:: Print or check SHA-2 digests\n", + "* sha2 utilities:: Print or check SHA-2 digests\n* sm3sum invocation:: Print or check SM3 digests\n", + "sm3sum detail menu entry", + ); + text = replaceRequired( + text, + "* sha2 utilities:: Print or check SHA-2 digests.\n@end menu", + "* sha2 utilities:: Print or check SHA-2 digests.\n* sm3sum invocation:: Print or check SM3 digests.\n@end menu", + "sm3sum chapter menu entry", + ); + text = replaceRequired( + text, + "@samp{sm3} only available through @command{cksum}", + "@samp{sm3} equivalent to @command{sm3sum} in BNU", + "sm3sum algorithm entry", + ); + text = replaceRequired( + text, + "@checksumUsage{sha???sum}\n\n\n@node Operating on sorted files", + "@checksumUsage{sha???sum}\n\n\n@node sm3sum invocation\n@section @command{sm3sum}: Print or check SM3 digests\n\n@pindex sm3sum\n@cindex SM3\n@cindex 256-bit checksum\n@command{sm3sum} computes a 256-bit SM3 checksum for each specified\n@var{file}. It is a BNU extension provided as a standalone interface to the\nSM3 algorithm accepted by @command{cksum}.\n\n@legacyDigest\n\n@checksumUsage{sm3sum}\n\n\n@node Operating on sorted files", + "sm3sum section", + ); + text = replaceRequired( + text, + "This version of @command{false} is implemented as a C program, and is thus\nmore secure and faster than a shell script implementation, and may safely\nbe used as a dummy shell for the purpose of disabling accounts.", + "BNU implements @command{false} in its Bun multi-call program. Do not use\nthe source-checkout launcher as a login shell.", + "false implementation note", + ); + text = replaceRequired( + text, + "This version of @command{true} is implemented as a C program, and is thus\nmore secure and faster than a shell script implementation, and may safely\nbe used as a dummy shell for the purpose of disabling accounts.", + "BNU implements @command{true} in its Bun multi-call program. Do not use\nthe source-checkout launcher as a login shell.", + "true implementation note", + ); + text = replaceRequired( + text, + "* GNU Free Documentation License:: Copying and sharing this manual\n* Concept index::", + "* History:: History of this modified manual\n* GNU Free Documentation License:: Copying and sharing this manual\n* Concept index::", + "History top-level menu entry", + ); + text = replaceRequired( + text, + "Copying This Manual\n\n* GNU Free Documentation License:: Copying and sharing this manual", + "Manual History\n\n* History:: Original and modified editions\n\nCopying This Manual\n\n* GNU Free Documentation License:: Copying and sharing this manual", + "History detail menu entry", + ); + text = replaceRequired( + text, + "@node GNU Free Documentation License\n@appendix GNU Free Documentation License", + "@node History\n@appendix History\n\n@table @asis\n@item GNU @code{Coreutils} 9.11 (2026)\nThe original manual was authored by David MacKenzie et al. and published by\nthe Free Software Foundation. Its transparent Texinfo source is distributed\nin the GNU Coreutils 9.11 source release at\n@uref{https://ftp.gnu.org/gnu/coreutils/coreutils-9.11.tar.xz}.\n\n@item BNU Core Utilities 9.11 (2026)\nThis modified edition was adapted by BNU contributors and published by the BNU\nproject. It documents BNU's independent Bun implementation, adds BNU-specific\ninvocation and extension material, and identifies the original GNU material.\nIts transparent source is available at\n@uref{https://github.com/Soccera1/bnu}.\n@end table\n\n@node GNU Free Documentation License\n@appendix GNU Free Documentation License", + "History appendix", + ); + return text; +} |
