- Refactor mandoc template to use x_mandoc_footer and x_mandoc_authors

Author: DannyBen

lib/bashly/libraries/render/mandoc/README.md

@@ -5,24 +5,52 @@ Render man pages for your script.
 Note that this renderer will render specially formatted markdown documents and
 will then use [pandoc](https://command-not-found.com/pandoc) to convert them.
 
-Setting the environment variable `PREVIEW` to the full command you wish to
-preview, will prompt the renderer to show the output using the `man` command
-after rendering.
-
 ## Usage
 
 ```bash
 # Generate all man pages to the ./docs directory
 $ bashly render :mandoc docs
+```
+
+## Special template features
+
+### Preview
 
-# .. and also preview the page for the "cli download" command
+Setting the environment variable `PREVIEW` to the full command you wish
+to preview, will prompt the renderer to show the output using the `man`
+command after rendering.
+
+```bash
+# Preview the page for the "cli download" command
 $ PREVIEW="cli download" bashly render :mandoc docs
 
-# .. and also watch for changes
+# .. and also watch for changes (after existing the man preview)
 $ PREVIEW="cli download" bashly render :mandoc docs --watch
 ```
 
-## Appending a footer
+### Footer
+
+You can add additional sections to any of the generated man pages, by
+adding a property named `x_mandoc_footer` to any of your commands in
+your `bashly.yml`.
+
+This field should contain a markdown string, for example:
 
-In case you wish to append additional sections to your generated man pages,
-you can place a file named `_footer.md` in your target directory.
+```yaml
+x_mandoc_footer: |-
+  # ISSUE TRACKER
+
+  Report issues at <https://github.com/lanalang/smallville>
+```
+
+### Authors
+
+You can specify an authors string that will be added to the man page,
+by adding a property named `x_mandoc_authors` to any of your commands
+in your `bashly.yml`.
+
+For example:
+
+```yaml
+x_mandoc_authors: Lana Lang
+```

lib/bashly/libraries/render/mandoc/mandoc.gtx

@@ -5,7 +5,7 @@ if version
 else
 > % {{ full_name.to_hyphen }}(1) | {{ summary }}
 end
-> % {{ ENV['AUTHORS'] }}
+> % {{ x_mandoc_authors }}
 > % {{ Date.today.strftime "%B %Y" }}
 >
 
@@ -177,4 +177,5 @@ if public_commands.any?
   >
 end
 
+= x_mandoc_footer
 >

lib/bashly/libraries/render/mandoc/render.rb

@@ -11,12 +11,6 @@
   manfile = "#{target}/#{command.full_name.tr(' ', '-')}.1"
   save mdfile, gtx.parse(command)
 
-  # Append the footer file if it exists
-  footer_file = "#{target}/_footer.md"
-  if File.exist? footer_file
-    File.append mdfile, File.read(footer_file)
-  end
-
   # The pandoc command that creates a manpage from markdown
   cmd = %[pandoc -f markdown-smart -s --to man "#{mdfile}" > "#{manfile}"]
   success = system cmd

spec/approvals/rendering/mandoc/catch-all-advanced/cli-download.md

@@ -52,3 +52,4 @@ cli download example.com ./output -f
 
 ~~~
 
+

spec/approvals/rendering/mandoc/catch-all-advanced/cli-upload.md

@@ -19,3 +19,4 @@ Upload a file
 
 - Alias: **u**
 
+

spec/approvals/rendering/mandoc/catch-all-advanced/cli.md

@@ -33,3 +33,4 @@ SEE ALSO
 
 **cli-download**(1), **cli-upload**(1)
 
+

spec/approvals/rendering/mandoc/dependencies-alt/cli-download.md

@@ -31,3 +31,4 @@ DEPENDENCIES
 :    install with $(green sudo apt install curl)
 
 
+

spec/approvals/rendering/mandoc/dependencies-alt/cli.md

@@ -30,3 +30,4 @@ SEE ALSO
 
 **cli-download**(1)
 
+

spec/approvals/rendering/mandoc/docker-like/docker-container-run.md

@@ -26,3 +26,4 @@ ARGUMENTS
 
      - *Required*
 
+

spec/approvals/rendering/mandoc/docker-like/docker-container-stop.md

@@ -26,3 +26,4 @@ ARGUMENTS
 
      - *Required*
 
+