Add 'bikeshed outline' command, for generating a document outline.

bikeshed/cli.py

@@ -373,15 +373,12 @@ def main() -> None:
         action="store_true",
         help="Finds HTML comments containing 'Big Text: foo' and turns them into comments containing 'foo' in big text.",
     )
-    sourceParser.add_argument(
-        "--outline",
-        dest="outline",
-        action="store_true",
-        help="Generates a document outline and prints to stdout.",
-    )
     sourceParser.add_argument("infile", nargs="?", default=None, help="Path to the source file.")
     sourceParser.add_argument("outfile", nargs="?", default=None, help="Path to the output file.")
 
+    outlineParser = subparsers.add_parser("outline", help="Generates an outline for the spec.")
+    outlineParser.add_argument("infile", nargs="?", default=None, help="Path to the source file.")
+
     testParser = subparsers.add_parser("test", help="Tools for running Bikeshed's testsuite.")
     testParser.add_argument(
         "--rebase",
@@ -495,6 +492,8 @@ def main() -> None:
         handleIssuesList(options)
     elif options.subparserName == "source":
         handleSource(options)
+    elif options.subparserName == "outline":
+        handleOutline(options)
     elif options.subparserName == "test":
         handleTest(options, extras)
     elif options.subparserName == "profile":
@@ -683,23 +682,27 @@ def handleIssuesList(options: argparse.Namespace) -> None:
 
 
 def handleSource(options: argparse.Namespace) -> None:
-    if options.outline:
-        from . import outline
-        from .Spec import Spec
+    from . import fonts
 
-        with m.messagesSilent() as _:
-            doc = Spec(inputFilename=options.infile).preprocess()
-        m.say(outline.printOutline(doc))
-    else:
-        from . import fonts
-
-        try:
-            fontPath = config.scriptPath("fonts", "smallblocks.bsfont")
-            font = fonts.Font.fromPath(fontPath)
-            fonts.replaceComments(font=font, inputFilename=options.infile, outputFilename=options.outfile)
-        except Exception as e:
-            m.die(f"Error trying to embiggen text:\n{e}")
-            return
+    try:
+        fontPath = config.scriptPath("fonts", "smallblocks.bsfont")
+        font = fonts.Font.fromPath(fontPath)
+        fonts.replaceComments(font=font, inputFilename=options.infile, outputFilename=options.outfile)
+    except Exception as e:
+        m.die(f"Error trying to embiggen text:\n{e}")
+        return
+
+
+def handleOutline(options: argparse.Namespace) -> None:
+    from . import outline
+    from .Spec import Spec
+
+    doc = Spec(inputFilename=options.infile)
+    if not doc.valid:
+        return
+    with m.messagesSilent() as _:
+        doc.preprocess()
+    m.say(outline.printOutline(doc))
 
 
 def handleTest(options: argparse.Namespace, extras: list[str]) -> None:

bikeshed/outline.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import dataclasses
+import os
 
 from . import h, t
 from . import unsortedJunk as u  # noqa: N813
@@ -18,13 +19,17 @@ def printOutline(doc: t.Spec) -> str:
     entries = generateOutline(doc)
     lineNumWidth = max(len(str(e.lineNum)) for e in entries)
     idWidth = max(len(str(e.id or "")) for e in entries)
+    consoleWidth = os.get_terminal_size().columns
     lines = []
     for entry in entries:
         if entry.level == 2:
             prefix = ""
         else:
             prefix = " " * (entry.level - 2)
-        lines.append(f"{entry.lineNum:{lineNumWidth}} | #{entry.id:{idWidth}} | {prefix}{entry.text}")
+        line = f"{entry.lineNum:{lineNumWidth}} | #{entry.id:{idWidth}} | {prefix}{entry.text}"
+        if len(line) > consoleWidth:
+            line = line[: consoleWidth - 2] + "…"
+        lines.append(line)
     return "\n".join(lines)
 
 
@@ -35,11 +40,14 @@ def generateOutline(doc: t.Spec) -> list[OutlineEntry]:
         id = el.get("id", None)
         level = int((h.tagName(el) or "h0")[1])
         try:
-            num,_,rest = el.get("bs-line-number").partition(":")
-            lineNum = int(num)
-            int(rest)
+            lineNum = int(el.get("bs-line-number", ""))
         except:
-            continue
+            try:
+                num, _, rest = el.get("bs-line-number", "").partition(":")
+                lineNum = int(num)
+                int(rest)
+            except:  # noqa: S112
+                continue
         entries.append(OutlineEntry(text, id, level, lineNum))
     return entries
 

docs/index.bs

@@ -989,6 +989,14 @@ The `source` command applies various transformations to the source document itse
 rather than producing a separate output document.
 Its options are described in [[#source]].
 
+`bikeshed outline` {#cli-outline}
+---------------------------------
+
+The `outline` command processes your document,
+then outputs an outline to stdout,
+listing the text of each heading
+along with its source line number and ID.
+
 
 `bikeshed issues-list` {#cli-issues-list}
 -----------------------------------------