d2.1: Document partial renders

ci/release/template/man/d2.1

@@ -9,14 +9,7 @@
 .Op Fl -watch Ar false
 .Op Fl -theme Em 0
 .Ar file.d2
-.Op Ar file.svg
+.Op Ar file.svg | file.png
-|
-.Op Ar file.png
-.Nm d2
-.Op Fl -watch Ar false
-.Op Fl -theme Em 0
-.Ar file.d2
-.Op Ar ...
 .Nm d2
 .Ar layout Op Ar name
 .Sh DESCRIPTION
@@ -29,10 +22,21 @@ to
 .Ar file.png
 .Ns .
 .Pp
+It defaults to
+.Ar file.svg
+if no output path is passed.
+.Pp
 Pass - to have
 .Nm
 read from stdin or write to stdout.
 .Pp
+Never use the presence of the output file to check for success.
+Always use the exit status of
+.Nm d2
+.Ns .
+This is because sometimes when errors occur while rendering, d2 still write out a partial
+render anyway to enable iteration on a broken diagram.
+.Pp
 See more docs, the source code and license at
 .Lk https://oss.terrastruct.com/d2
 .Sh OPTIONS

cmd/d2/help.go

@@ -15,11 +15,15 @@ import (
 
 func help(ms *xmain.State) {
 	fmt.Fprintf(ms.Stdout, `Usage:
-  %s [--watch=false] [--theme=0] file.d2 [file.svg|file.png]
+  %s [--watch=false] [--theme=0] file.d2 [file.svg | file.png]
+
+%[1]s compiles and renders file.d2 to file.svg | file.png
+It defaults to file.svg if an output path is not provided.
 
-%[1]s compiles and renders file.d2 to file.svg|file.png.
 Use - to have d2 read from stdin or write to stdout.
 
+See man %[1]s for more detailed docs.
+
 Flags:
 %s