man-pages(7) has [1]:
> For commands, this shows the syntax of the command and its arguments
> (including options); boldface is used for as-is text and italics are
> used to indicate replaceable arguments. Brackets ([]) surround
> optional arguments, vertical bars (|) separate choices, and ellipses
> (...) can be repeated.
I've adjusted our SYNOPSIS entries to match that formatting, and
generally tried to make them more consistent with the precedent set by
the man-pages project. Outside of the SYNOPSIS entry, I prefer using
backticks for literals, although in some places I've left the **
bolding to keep things visually similar to a nearby SYNOPSIS entry.
I've also simplified a few placeholders, e.g. "containerID" ->
"container", because I didn't think the additional bit was providing
much additional context. If there is ambiguity about the
representation, it should be addressed in the DESCRIPTION instead of
with an "ID" or "Name" suffix.
[1]: http://man7.org/linux/man-pages/man7/man-pages.7.html
Signed-off-by: W. Trevor King <wking@tremily.us>
Closes: #839
Approved by: rhatdan
This fixes an issue where if you did
man -k buildah-bud
buildah-bud (1) - (unknown subject)
Now you will see
man -k buildah-bud
buildah-bud (1) - Build an image using instructions from Dockerfiles.
More importantly
man -k Dockerfile
buildah-bud (1) - Build an image using instructions from Dockerfiles.
docker-build (1) - Build an image from a Dockerfile
docker-image-build (1) - Build an image from a Dockerfile
Dockerfile (5) - automate the steps of creating a Docker image
podman-build (1) - Build a container image using a Dockerfile.
Will now list buildah-d
Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
Closes: #638
Approved by: TomSweeneyRedHat
I noticed when you look at the man pages with man ./doc/buildah.1 that the
headings were not showing up. go-md2man wanted to have a primary header
in order to format them correctly. Removing the first # from the first line
fixes the issue.
Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
Closes: #521
Approved by: rhatdan
W. Trevor King
Daniel J Walsh
Nalin Dahyabhai