From 0ad810f0de953c7d7b1f6aa2961dac73dfaef513 Mon Sep 17 00:00:00 2001 From: WebFreak001 Date: Fri, 5 Aug 2022 16:45:35 +0200 Subject: [PATCH] improve man page format --- changelog/exitcodes.dd | 11 ++++++ scripts/man/gen_man.d | 73 ++++++++++++++++++++++++++++++++++++---- source/dub/commandline.d | 10 +++--- 3 files changed, 82 insertions(+), 12 deletions(-) create mode 100644 changelog/exitcodes.dd diff --git a/changelog/exitcodes.dd b/changelog/exitcodes.dd new file mode 100644 index 0000000000..ec85b2898d --- /dev/null +++ b/changelog/exitcodes.dd @@ -0,0 +1,11 @@ +DUB command exit codes have been adjusted + +Some certain dub command conditions now return exit code 2 instead of exit code 1. Exit code 1 is now always used for usage errors, while exit code 2 is the more generic any error occured or package failed to load. + +The following commands could now return exit code 2 instead of exit code 1 when failing to load packages or other errors occur: + +- dub clean +- dub add +- dub search +- dub convert + diff --git a/scripts/man/gen_man.d b/scripts/man/gen_man.d index e1b20895b2..aff9118401 100755 --- a/scripts/man/gen_man.d +++ b/scripts/man/gen_man.d @@ -30,6 +30,7 @@ struct Config { import std.datetime; SysTime date; + string[] relatedSubCommands; static Config init(){ import std.process : environment; @@ -62,7 +63,8 @@ void writeFooter(ref File manFile, string seeAlso, const Config config) Copyright (c) 1999-%s by The D Language Foundation .SH "ONLINE DOCUMENTATION" .UR http://code.dlang.org/docs/commandline -.UE http://code.dlang.org/docs/commandline +http://code.dlang.org/docs/commandline +.UE .SH "SEE ALSO" %s`; manFile.writefln(manFooter, config.date.year, seeAlso); @@ -116,26 +118,28 @@ string highlightArguments(string args) void writeArgs(CommandArgs args, ref File manFile) { - alias write = (m) => manFile.write(m); + alias write = (m) => manFile.write(m.replace(`-`, `\-`)); foreach (arg; args.recognizedArgs) { auto names = arg.names.split("|"); assert(names.length == 1 || names.length == 2); string sarg = names[0].length == 1 ? names[0] : null; string larg = names[0].length > 1 ? names[0] : names.length > 1 ? names[1] : null; - write(".IP "); + manFile.writeln(".PP"); if (sarg !is null) { - write("-%s".format(sarg)); + write("-%s".format(sarg).bold); if (larg !is null) write(", "); } if (larg !is null) { - write("--%s".format(larg)); + write("--%s".format(larg).bold); if (!arg.defaultValue.peek!bool) write("=VALUE"); } manFile.writeln; + manFile.writeln(".RS 4"); manFile.writeln(arg.helpText.join("\n")); + manFile.writeln(".RE"); } } @@ -149,11 +153,25 @@ void writeManFile(Command command, const Config config) auto manFile = File(config.cwd.buildPath(fileName), "w"); auto manName = format("DUB-%s", command.name).toUpper; manFile.writeHeader(manName, config); - static immutable seeAlso = ["dmd(1)", "dub(1)"].map!bold.joiner(", ").to!string; + + string[] extraRelated; + foreach (arg; args.recognizedArgs) { + if (arg.names.canFind("rdmd")) + extraRelated ~= "rdmd(1)"; + } + if (command.name == "dustmite") + extraRelated ~= "dustmite(1)"; + + const seeAlso = ["dub(1)"] + .chain(config.relatedSubCommands.map!(s => s.format!"dub-%s(1)")) + .chain(extraRelated) + .map!bold + .joiner(", ") + .to!string; scope(exit) manFile.writeFooter(seeAlso, config); alias writeln = (m) => manFile.writeln(m); - writeln(`dub \- Package and build management system for D`); + manFile.writefln(`dub-%s \- %s`, command.name, command.description); writeln("SYNOPSIS".header); writeln("dub %s".format(command.name).bold); @@ -168,6 +186,25 @@ void writeManFile(Command command, const Config config) writeln(command.helpText.joiner("\n\n")); writeln("OPTIONS".header); args.writeArgs(manFile); + + static immutable exitStatus = +`.SH EXIT STATUS +.TP +.BR 0 +DUB succeeded +.TP +.BR 1 +usage errors, unknown command line flags +.TP +.BR 2 +package not found, package failed to load, miscellaneous error`; + static immutable exitStatusDustmite = +`.SH EXIT STATUS +Forwards the exit code from ` ~ `dustmite(1)`.bold; + if (command.name == "dustmite") + manFile.writeln(exitStatusDustmite); + else + manFile.writeln(exitStatus); } void main() @@ -183,8 +220,30 @@ void main() args.writeMainManFile(commands, "dub.1", config); } + string[][] relatedSubCommands = [ + ["run", "build", "test"], + ["test", "dustmite", "lint"], + ["describe", "gemerate"], + ["add", "fetch"], + ["init", "add", "convert"], + ["add-path", "remove-path"], + ["add-local", "remove-local"], + ["list", "search"], + ["add-override", "remove-override", "list-overrides"], + ["clean-caches", "clean", "remove"], + ]; + // options for each specific command foreach (cmd; commands.map!(a => a.commands).joiner) { + string[] related; + foreach (relatedList; relatedSubCommands) { + if (relatedList.canFind(cmd.name)) + related ~= relatedList; + } + related = related.sort!"a c == cmd.name); + config.relatedSubCommands = related; + cmd.writeManFile(config); } } diff --git a/source/dub/commandline.d b/source/dub/commandline.d index a21db0ecf1..3b918aaf5e 100644 --- a/source/dub/commandline.d +++ b/source/dub/commandline.d @@ -1686,7 +1686,7 @@ class CleanCommand : Command { } } - if (any_error) return 1; + if (any_error) return 2; } else { dub.cleanPackage(dub.rootPath); } @@ -1723,12 +1723,12 @@ class AddCommand : Command { enforceUsage(free_args.length != 0, "Expected one or more arguments."); enforceUsage(app_args.length == 0, "Unexpected application arguments."); - if (!loadCwdPackage(dub, true)) return 1; + if (!loadCwdPackage(dub, true)) return 2; auto recipe = dub.project.rootPackage.rawRecipe.clone; foreach (depspec; free_args) { if (!addDependency(dub, recipe, depspec)) - return 1; + return 2; } writePackageRecipe(dub.project.rootPackage.recipePath, recipe); @@ -2142,7 +2142,7 @@ class SearchCommand : Command { if (res.empty) { logError("No matches found."); - return 1; + return 2; } auto justify = res .map!((descNmatches) => descNmatches[1]) @@ -2555,7 +2555,7 @@ class ConvertCommand : Command { enforceUsage(app_args.length == 0, "Unexpected application arguments."); enforceUsage(free_args.length == 0, "Unexpected arguments: "~free_args.join(" ")); enforceUsage(m_format.length > 0, "Missing target format file extension (--format=...)."); - if (!loadCwdPackage(dub, true)) return 1; + if (!loadCwdPackage(dub, true)) return 2; dub.convertRecipe(m_format, m_stdout); return 0; }