improved readability of help messages (#10304)

This PR aims to improve the readability of help messages.

Concretely it addresses 2 weaknesses of the current behavior:

1. In the presence of a very long option name, e.g. `-scalajs-genStaticForwardersForNonTopLevelObjects`, all descriptions of the selected option subset are currently displayed with a large empty space on their left.

   **NB.** Alternative (and cheap) solution: define a maximum length for option names.

2. If the text length of the description is greater than the terminal width minus the largest option width (which not exceeds 30 chars), the rear part of the text flows to the next line, starting at **column 0**.

   **NB.** `javac` mixes two ways to display descriptions in help messages (see e.g. `javac -X`): descriptions are either programmatically split into several lines or their rear part simply flows to the next line, starting at **column 0**.

Author: michelou

compiler/src/dotty/tools/dotc/config/CliCommand.scala

@@ -66,26 +66,48 @@ trait CliCommand:
 
   /** Creates a help message for a subset of options based on cond */
   protected def availableOptionsMsg(cond: Setting[?] => Boolean)(using settings: ConcreteSettings)(using SettingsState): String =
-    val ss                  = (settings.allSettings filter cond).toList sortBy (_.name)
-    val width               = (ss map (_.name.length)).max
-    def format(s: String)   = ("%-" + width + "s") format s
+    val ss = (settings.allSettings filter cond).toList sortBy (_.name)
+    val maxNameWidth = 30
+    val nameWidths = ss.map(_.name.length).partition(_ < maxNameWidth)._1
+    val width = if nameWidths.nonEmpty then nameWidths.max else maxNameWidth
+    val terminalWidth = settings.pageWidth.value
+    val (nameWidth, descriptionWidth) = {
+      val w1 =
+        if width < maxNameWidth then width
+        else maxNameWidth
+      val w2 =
+        if terminalWidth < w1 + maxNameWidth then 0
+        else terminalWidth - w1 - 1
+      (w1, w2)
+    }
+    def formatName(name: String) =
+      if name.length <= nameWidth then ("%-" + nameWidth + "s") format name
+      else (name + "\n%-" + nameWidth + "s") format ""
+    def formatDescription(text: String): String =
+      if descriptionWidth == 0 then text
+      else if text.length < descriptionWidth then text
+      else {
+        val inx = text.substring(0, descriptionWidth).lastIndexOf(" ")
+        if inx < 0 then text
+        else
+          val str = text.substring(0, inx)
+          s"${str}\n${formatName("")} ${formatDescription(text.substring(inx + 1))}"
+      }
+    def formatSetting(name: String, value: String) =
+      if (value.nonEmpty)
+        // the format here is helping to make empty padding and put the additional information exactly under the description.
+        s"\n${formatName("")} $name: $value."
+      else
+        ""
     def helpStr(s: Setting[?]) =
       def defaultValue = s.default match
         case _: Int | _: String => s.default.toString
         case _ =>
           // For now, skip the default values that do not make sense for the end user.
           // For example 'false' for the version command.
           ""
-
-      def formatSetting(name: String, value: String) =
-        if (value.nonEmpty)
-        // the format here is helping to make empty padding and put the additional information exactly under the description.
-          s"\n${format("")} $name: $value."
-        else
-          ""
-      s"${format(s.name)} ${s.description}${formatSetting("Default", defaultValue)}${formatSetting("Choices", s.legalChoices)}"
-
-    ss.map(helpStr).mkString("", "\n", s"\n${format("@<file>")} A text file containing compiler arguments (options and source files).\n")
+      s"${formatName(s.name)} ${formatDescription(s.description)}${formatSetting("Default", defaultValue)}${formatSetting("Choices", s.legalChoices)}"
+    ss.map(helpStr).mkString("", "\n", s"\n${formatName("@<file>")} ${formatDescription("A text file containing compiler arguments (options and source files).")}\n")
 
   protected def shortUsage: String = s"Usage: $cmdName <options> <source files>"
 

compiler/src/dotty/tools/dotc/config/ScalaSettings.scala

@@ -11,6 +11,18 @@ import Settings.Setting
 trait CommonScalaSettings { self: Settings.SettingGroup =>
   protected def defaultClasspath: String = sys.env.getOrElse("CLASSPATH", ".")
 
+  protected def defaultPageWidth: Int = {
+    val defaultWidth = 80
+    val columnsVar = System.getenv("COLUMNS")
+    if columnsVar != null then columnsVar.toInt
+    else if Properties.isWin then
+      val ansiconVar = System.getenv("ANSICON") // eg. "142x32766 (142x26)"
+      if ansiconVar != null && ansiconVar.matches("[0-9]+x.*") then
+        ansiconVar.substring(0, ansiconVar.indexOf("x")).toInt
+      else defaultWidth
+    else defaultWidth
+  }
+
   /** Path related settings */
   val bootclasspath: Setting[String] = PathSetting("-bootclasspath", "Override location of bootstrap class files.", Defaults.scalaBootClassPath, aliases = List("--boot-class-path"))
   val extdirs: Setting[String] = PathSetting("-extdirs", "Override location of installed extensions.", Defaults.scalaExtDirs, aliases = List("--extension-directories"))
@@ -26,7 +38,7 @@ trait CommonScalaSettings { self: Settings.SettingGroup =>
   val verbose: Setting[Boolean] = BooleanSetting("-verbose", "Output messages about what the compiler is doing.", aliases = List("--verbose"))
   val version: Setting[Boolean] = BooleanSetting("-version", "Print product version and exit.", aliases = List("--version"))
   val help: Setting[Boolean] = BooleanSetting("-help", "Print a synopsis of standard options.", aliases = List("--help"))
-  val pageWidth: Setting[Int] = IntSetting("-pagewidth", "Set page width", 80, aliases = List("--page-width"))
+  val pageWidth: Setting[Int] = IntSetting("-pagewidth", "Set page width", defaultPageWidth, aliases = List("--page-width"))
   val silentWarnings: Setting[Boolean] = BooleanSetting("-nowarn", "Silence all warnings.", aliases = List("--no-warnings"))
 
   /** Other settings */

dist/bin/common

@@ -27,6 +27,12 @@ function onExit() {
 trap onExit INT TERM EXIT
 
 unset cygwin mingw msys darwin conemu
+
+# COLUMNS is used together with command line option '-pageWidth'.
+if command -v tput >/dev/null 2>&1; then
+  export COLUMNS="$(tput -Tdumb cols)"
+fi
+
 case "`uname`" in
   CYGWIN*) cygwin=true
           ;;