Skip to content

Instantly share code, notes, and snippets.

@mingsai

mingsai/macos-custom-man-page.md

Last active February 27, 2022 03:13
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save mingsai/64c22bdeb6f1f9d87413e2f24bc80030 to your computer and use it in GitHub Desktop.
Save mingsai/64c22bdeb6f1f9d87413e2f24bc80030 to your computer and use it in GitHub Desktop.
Download ZIP
How to create a new custom man page
Raw
macos-custom-man-page.md

Requires just terminal, nano, vi and sudo rights

Works on MacOS Monterrey+

Tips

  • Everything needs to be run in Terminal
  • Check your man search path using manpath
  • Type manpath to see available locations
  • Use share for pages accessible to all users
  • Some versions of man epect to see gzipped files
  • Check the folders of existing man pages to view file formats expected
  • After you save the file you can use cat man-filename.X to see the man page raw format
  • You can also use man ./your-custom-man-filename.X to verify that it displays correctly

Make the man page file using vi or nano (use extension to match man page location folder, eg. man8 = filename.8)

sudo nano filename.X

Note the format markers required at front of each line (change content as needed)

.\" Manpage for ttf2woff2..
.\" Contact fewest_lagging_0u@icloud.com to correct errors or typos.
.TH man 8 "26 February 2022" "1.0" "ttf2woff2 man page"
.SH NAME
ttf2woff2 - converts ttf font to woff2 for use on web 
.SH SYNOPSIS
cat [input-font-name].ttf | ttf2woff2 > [output-font-name].woff2
.SH DESCRIPTION
ttf2woff2 converts ttf font to woff2 font type.
.SH OPTIONS
ttf2woff2 does not take any options. However, you can supply output font name.
.SH SEE ALSO
npm (ttf2woff2) - https://github.com/nfroidure/ttf2woff2 (source)
.SH BUGS
No known bugs.
.SH AUTHOR
Author Name (youremail@wherever.com)

Saving the file

  • Ensure that your account has sudo access and create a folder for your custom man pages (eg. /usr/local/share/man/man8)
  • Note the manX folder might not exist, create it with your sudo account
  • Copy file to (/usr/local/share/man/man8) - use sudo
cp file.8 /usr/local/share/man/man8

Update man.conf which is located in /etc/private (man man.conf for more info)

sudo nano /etc/private/man.conf

Add a new line to the directory you created that will hold the manpage

MANPATH /usr/local/share/man/man8

Notes on the man.conf

  • You can use manX for whatever the actural directory number you use
  • Save the man.conf back to its directory and exit

Open a new terminal and you should be able to see the new man page --(for example)

man ttf2woff2

HowToGeek - More Format Info

Basic manpage layout from wikipedia , my sample above works on macos

NAME
The name of the command or function, followed by a one-line description of what it does.
SYNOPSIS
In the case of a command, a formal description of how to run it and what command line options it takes. For program functions, a list of the parameters the function takes and which header file contains its declaration.
DESCRIPTION
A textual description of the functioning of the command or function.
EXAMPLES
Some examples of common usage.
SEE ALSO
A list of related commands or functions.
Other sections may be present, but these are not well standardized across man pages. Common examples include: OPTIONS, EXIT STATUS, RETURN VALUE, ENVIRONMENT, BUGS, FILES, AUTHOR, REPORTING BUGS, HISTORY and COPYRIGHT.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment