man: allow multi-line paragraphs for comment-based docs

Library/Homebrew/dev-cmd/man.rb

@@ -196,8 +196,11 @@ module Homebrew
     lines = [format_usage_banner(comment_lines.first).chomp]
     comment_lines.slice(1..-1)
                  .each do |line|
-      line = line.slice(4..-1)
-      next unless line
+      line = line.slice(4..-2)
+      unless line
+        lines.last << "\n"
+        next
+      end
 
       # Omit the common global_options documented separately in the man page.
       next if line =~ /--(debug|force|help|quiet|verbose) /
@@ -206,6 +209,7 @@ module Homebrew
       lines << line.gsub(/^ +(-+[a-z-]+), (-+[a-z-]+) +/, "* `\\1`, `\\2`:\n  ")
                    .gsub(/^ +(-+[a-z-]+) +/, "* `\\1`:\n  ")
     end
+    lines.last << "\n"
     lines
   end
 

docs/Manpage.md

@@ -423,11 +423,11 @@ build systems would not find otherwise.
   Use the standard `PATH` instead of superenv's when `std` is passed.
 
 ### `shellenv`
+
 Print export statements. When run in a shell, this installation of Homebrew will be added to your `PATH`, `MANPATH`, and `INFOPATH`.
 
 The variables `HOMEBREW_PREFIX`, `HOMEBREW_CELLAR` and `HOMEBREW_REPOSITORY` are also exported to avoid querying them multiple times.
-
-Consider adding evaluation of this command's output to your dotfiles (e.g. `~/.profile`) with: `eval $(brew shellenv)`
+Consider adding evaluation of this command's output to your dotfiles (e.g. `~/.profile` or `~/.zprofile`) with: `eval $(brew shellenv)`
 
 ### `style` [*`options`*] [*`file`*|*`tap`*|*`formula`*]
 
@@ -527,12 +527,14 @@ also `pin`.
 Remove a tapped formula repository.
 
 ### `update`, `up` [*`options`*]
+
 Fetch the newest version of Homebrew and all formulae from GitHub using `git`(1) and perform any necessary migrations.
 
 * `--merge`:
   Use `git merge` to apply updates (rather than `git rebase`).
 
 ### `update-reset` [*`repository`*]
+
 Fetch and reset Homebrew and all tap repositories (or any specified *`repository`*) using `git`(1) to their latest `origin/master`.
 
 *Note:* this will destroy all your uncommitted or committed changes.

manpages/brew.1

@@ -530,10 +530,7 @@ Use the standard \fBPATH\fR instead of superenv\'s when \fBstd\fR is passed\.
 Print export statements\. When run in a shell, this installation of Homebrew will be added to your \fBPATH\fR, \fBMANPATH\fR, and \fBINFOPATH\fR\.
 .
 .P
-The variables \fBHOMEBREW_PREFIX\fR, \fBHOMEBREW_CELLAR\fR and \fBHOMEBREW_REPOSITORY\fR are also exported to avoid querying them multiple times\.
-.
-.P
-Consider adding evaluation of this command\'s output to your dotfiles (e\.g\. \fB~/\.profile\fR) with: \fBeval $(brew shellenv)\fR
+The variables \fBHOMEBREW_PREFIX\fR, \fBHOMEBREW_CELLAR\fR and \fBHOMEBREW_REPOSITORY\fR are also exported to avoid querying them multiple times\. Consider adding evaluation of this command\'s output to your dotfiles (e\.g\. \fB~/\.profile\fR or \fB~/\.zprofile\fR) with: \fBeval $(brew shellenv)\fR
 .
 .SS "\fBstyle\fR [\fIoptions\fR] [\fIfile\fR|\fItap\fR|\fIformula\fR]"
 Check formulae or files for conformance to Homebrew style guidelines\.