cmd/shfmt: provide a manpage

[jsamr]

I am interested in packaging shfmt for Debian, but they require a manual page. See the Debian Policy Manual, chapter 12, section 1 (emphasis added):

Each program, utility, and function should have an associated manual page included in the same package. It is suggested that all configuration files also have a manual page included as well. Manual pages for protocols and other auxiliary things are optional.

If no manual page is available, this is considered as a bug and should be reported to the Debian Bug Tracking System (the maintainer of the package is allowed to write this bug report themselves, if they so desire). Do not close the bug report until a proper man page is available.

You may forward a complaint about a missing man page to the upstream authors, and mark the bug as forwarded in the Debian bug tracking system. Even though the GNU Project do not in general consider the lack of a man page to be a bug, we do; if they tell you that they don’t consider it a bug you should leave the bug in our bug tracking system open anyway.

[mvdan]

That's unfortunate. I'm surprised that the tool's own help text is not enough:

$ shfmt -h
usage: shfmt [flags] [path ...]

If the only argument is a dash ('-') or no arguments are given, standard input
will be used. If a given path is a directory, it will be recursively searched
for shell files - both by filename extension and by shebang.

  -version  show version and exit

  -l        list files whose formatting differs from shfmt's
  -w        write result to file instead of stdout
  -d        error with a diff when the formatting differs
  -s        simplify the code
  -mn       minify the code to reduce its size (implies -s)

Parser options:

  -ln str   language variant to parse (bash/posix/mksh, default "bash")
  -p        shorthand for -ln=posix

Printer options:

  -i uint   indent: 0 for tabs (default), >0 for number of spaces
  -bn       binary ops like && and | may start a line
  -ci       switch cases will be indented
  -sr       redirect operators will be followed by a space
  -kp       keep column alignment paddings
  -fn       function opening braces are placed on a separate line

Utilities:

  -f        recursively find all shell files and print the paths
  -tojson   print syntax tree to stdout as a typed JSON

Am I meant to maintain a separate document in manpage format?

[jsamr]

@mvdan I think that would be really great!
Also, Fedora guidelines requirement is a SHOULD. Cf Fedora Packaging Guidelines, section “Manpages”.

As man pages are the traditional method of getting help on a Unix system, packages SHOULD contain them for all executables. If some man pages are absent, packagers SHOULD work with upstream to add them. It is also occasionally possible to find pages created by other distributions, or to use the output of the help2man program; those are often useful as a starting point.

If you don't want to write pure nroff files, you could use reStructuredText, perlpod, Docbook or other markups that can be easily compiled to nroff.

[mvdan]

Thanks. I'll have to think about it. I assume the manpage should contain more than -h, since -h is meant to be short. But also less than README.md, since that covers the entire project and not just shfmt.

I can see why it's useful for users, but it's also a significant amount of extra work for me. The overlap between the three documents would mean that any future change would probably need to update all three documents with care. I wonder how other projects deal with this.

[jsamr]

I see several workflows in which you would avoid duplicating information. The advantage of reStructuredText is that it is supported by github, and thus you could just write individual manuals for each utility, referenced in the readme.rst, and add compilation to groff in your build logic. I personally have a workflow for my own utility where I convert groff to html with mandoc [1], deploy it to github pages and reference sections in my readme [2]. And a third workflow involving groff with mandoc consists in converting to markdown for a builtin rendering in github. There are a lot of options, but I reckon there is some hassle in the process of setting up all the glue code, and I wish there where a more generic, universal way to “write once, read everywhere” for utility documentation.

[1] https://mandoc.bsd.lv/
[2] https://github.com/jsamr/bootiso#reference-manual

[grylem]

you can use this manpage if you want
shfmt.1.gz

[mvdan]

@jsamr this took me a while to flesh out, but it's done. Please take a look and let me know if you spot any issues. I plan to release 3.2.0 in a day or two, so you could use that tag as the first version for Debian.

Also, when it comes to packaging for Debian, please remember that many of the module dependencies in go.mod like go-internal and creack/pty are just test dependencies, not build dependencies.

[mvdan]

v3.2.0 is released with the manpage.