Read the Friendly Manual — Open Unix Manual Pages

[vitor]

Usage

Search installed manual pages via the man keyword.

• ↩ Open in primary viewer.
• ⌥↩ Open in secondary viewer.
  

The viewer app set in the Workflow’s Configuration determines the generated format:

• Alfred Text View: ASCII text.
• Alfred PDF View: PDF.
• PDF App: PDF.
• Quick Look: HTML.
• Web Browser: HTML.
• Terminal: Standard view.
  

When viewing in Alfred, ⌥↩ opens the alternative viewer.

⤓ Install on the Alfred Gallery | Source

[vitor]

When reporting issues, please include your exact installed versions of:

• The Workflow.
• Alfred.
• macOS.

In addition to:

• The debugger output. Perform the failing action, click “Copy” on the top right and paste it here.
• Details on what you did, what happened, and what you expected to happen. A short video of the steps with the debugger open may help to find the problem faster.

Thank you. Accurate and thorough information is crucial for a proper diagnosis which allows me to help you better.

[vitor]

Updated to 2024.2.

macOS 14.4 stable broke searching of manual pages with man (FB13690576), so they are now retrieved by location. This alters the results list slightly, as retrieving descriptions one by one takes too long. But by showing the path in the subtitle, it’s now possible to differentiate between different manuals with the same name (e.g. for a tool which ships with the system but you have installed a more recent version with Homebrew).

[Gary Ash]

I'm really liking the workflow!. Thank you for it.

 

Is there a way to make the view window bigger and/or save the text size.  As it is now I have to zoom in each time

[Stephen_C]

2 hours ago, Gary Ash said:

 

Is there a way to make the view window bigger

You should be able to use cmd + zero to toggle the window size.

 

Stephen

[Hans-Pe]

The workflow does not find all man-files. It seems all commands installed with macports (tmux, 7z, ...) or others are missing. I assume the cause is, that the workflow runs `manpath` not with my shell's $PATH but with the initial path from `/etc/paths`.

 

 % manpath
/Users/mb/miniconda3/share/man:/Users/mb/miniconda3/man:/opt/local/share/man:/opt/local/man:/usr/local/share/man:/System/Cryptexes/App/usr/share/man:/usr/share/man:/Library/Apple/usr/share/man:/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/share/man:/Applications/Xcode.app/Contents/Developer/usr/share/man:/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/share/man

 

macOS Ventura 13.6.7

Alfred 5.5

WF v2024.3

 

Any simple workarounds available?

 

Hans-Peter

 

 

[vitor]

On 6/9/2024 at 3:25 PM, Hans-Pe said:

I assume the cause is, that the workflow runs `manpath` not with my shell's $PATH but with the initial path from `/etc/paths`.

 

Close. Alfred doesn’t use your shell’s PATH, but it’s not /etc/paths either. See Understanding the Scripting Environment.

 

On 6/9/2024 at 3:25 PM, Hans-Pe said:

Any simple workarounds available?

 

Go to the Workflow Environment Variables in the workflow and add a PATH variable with the PATH in your shell. The full expanded one, do echo $PATH to get the correct one.

 

Might need to do it again after a workflow update, but this is has been quite stable from the start. Well, except for the brief period where Apple broke searching for manual pages in 14.5 which forced a rewrite of the logic, but no way I could’ve controlled for that.

[Hans-Pe]

The linked article "Understanding the Scripting Environment" is really useful, thank you. Setting $PATH as suggested does the trick with /bin/zsh --no-rcs.

 

But in this workflow setting $PATH yields:

 

ERROR: Read the Friendly Manual[Script Filter] Code 1: /Users/mb/Library/Caches/com.runningwithcrayons.Alfred/Workflow Scripts/4AD6A2DE-0DE7-4F60-8504-01FE2424457F: execution error: Error: TypeError: undefined is not an object (evaluating '$.NSFileManager.defaultManager
    .contentsOfDirectoryAtURLIncludingPropertiesForKeysOptionsError(...arguments)
    .js.map') (-2700)

 

 

[vitor]

2 hours ago, Hans-Pe said:

But in this workflow setting $PATH yields:

I need to see exactly what you did. I am only able to debug if you’re specific.

[Hans-Pe]

1. I copied $PATH to clipboard: ~ echo -n $PATH | pbcopy
2. Went to Alfred's work flow, added PATH to Environment Variables of Read the Friendly Manual
3. Pasted PATH from clipboard into Value
4. Saved it
5. Toggled Debug on
6. Run keyword man in Alfred 
7. The Workflow Icon appeared in the menu for .5s second and disappeared

 

My $PATH:

/Users/mb/miniconda3/bin:/Users/mb/miniconda3/condabin:/opt/local/bin:/opt/local/sbin:/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Applications/Little Snitch.app/Contents/Components:/Library/Apple/usr/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/local/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/appleinternal/bin:/Applications/iTerm.app/Contents/Resources/utilities

 

Edited June 12 by Hans-Pe
Content of $PATH added

[vitor]

Start by removing everything from there which isn’t absolutely necessary for the goal, such as Little Snitch and iTerm2. Then try with this version.

[Hans-Pe]

With the reduced $PATH:

 

/opt/local/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

 

This time:

[16:05:11.678] ERROR: Read the Friendly Manual[Script Filter] Code 1: /Users/mb/Library/Caches/com.runningwithcrayons.Alfred/Workflow Scripts/D27CA9EE-8012-4374-8E50-DEC4629879A6: execution error: Error: TypeError: undefined is not an object (evaluating 'dir.slice') (-2700)

 

Looking at Caches: File D27CA9EE-8012-4374-8E50-DEC4629879A6 does not exist:

 

ls -1 /Users/mb/Library/Caches/com.runningwithcrayons.Alfred/Workflow\ Scripts
16E4BB12-E3B3-4548-A8D7-CC74C32773CF
B5428421-97E2-469D-BEA8-327DA4289CAC
E51FED03-C0B8-4F5E-9120-A4B170CD86E8
EF979E76-087D-4742-B37C-690209E6CAE4

 

[vitor]

Try this one.

[Hans-Pe]

This time no error. As you can see from the debug output, the man file for python3.12.1 is found in opt/local/share/man.

The real problem seems to be that the number of man files is too large, regardless of the additional directories in PATH. Look at the screenshot, where I search for git: The main module is not offered, but git-log is shown!

 

% ls -1 =git
/usr/bin/git

 

% man -d git-log 2>&1 | grep Found
--     Found manpage /Applications/Xcode.app/Contents/Developer/usr/share/man/man1/git-log.1
~  % man -d git 2>&1 | grep Found
--     Found manpage /Applications/Xcode.app/Contents/Developer/usr/share/man/man1/git.1

 

 

[vitor]

git is still there, just way further down. Alfred learns from your usage, so if you go down and ↩ on that one, it’ll bubble to the top in the future.

[Hans-Pe]

I see, git is there. In this case it is better to do without Alfred's  knowledge of previous usage and display the list sorted by name. There are more then 100 manfiles names starting with git.

 

tmux and 7z are still missing:

% man -d tmux 7z 2>&1 | grep Found
--     Found manpage /opt/local/share/man/man1/tmux.1.gz
--     Found manpage /opt/local/share/man/man1/7z.1.gz

because they are compressed?

[gingerbeardman]

I have this alias in my zsh:

 

alias fixman="echo 'MANPATH /opt/homebrew/share/man' | sudo -A tee -a /etc/man.conf"

 

I run it after each macOS system update so that man pages installed through brew are found. Maybe there's a better way?

 

I'm also using Zach Schulze's man page workflow, which presents them in Terminal. The benefit of this method is that you get hyperlinks to any related man pages with no extra effort.

[Hans-Pe]

Thank you @gingerbeardman, for the interesting hints. A little bit off topic:

 

man uses manpath to find man-files and manpath uses $PATH to build the pathes of man-files.

So for me it is only necessary to add more directories to /etc/man.conf (or /usr/local/etc/man.d/)
for commands which are not located in $PATH while man or manpath is used. This is usually not the case in interactive shells.

From man manpath:

IMPLEMENTATION NOTES
     The manpath utility constructs the manual path from two sources:
     1.   From each component of the user's PATH for the first of:
          -   pathname/man
          -   pathname/MAN
          -   If pathname ends with /bin: pathname/../share/man and
              pathname/../man
     2.   The configuration files listed in the FILES section for MANPATH
          entries.

I use vim as man pager and added into vimrc:

runtime ftplugin/man.vim  " defines vim-command :Man

In my zshrc:

manvi () {
    local pagervim="/bin/sh -c \"unset PAGER;col -b -x |     vim -R -c 'set ft=man nomod nolist' -c 'map q :q<CR>'     -c 'map <SPACE> <C-D>' -c 'map b <C-U>'     -c 'nmap K :Man <C-R>=expand(\\\"<cword>\\\")<CR><CR>' -\""
    PAGER=$pagervim man $1
}

In this way vim also supports hyperlinks in man pages (with ⌃] and K).

 

I will probably not use Vitor's workflow in the future, but I find its implementation very instructive. 

[vitor]

On 6/13/2024 at 8:14 AM, Hans-Pe said:

In this case it is better to do without Alfred's  knowledge of previous usage and display the list sorted by name.

 

Rather than previous knowledge, that is no knowledge (yet). It learns from the selections. There are no current plans to alphabetise because that bubbles less used locations to the top. It was not an oversight; git is just an outlier case.

 

On 6/13/2024 at 8:14 AM, Hans-Pe said:

because they are compressed?

 

Yes. More specifically due to the extension.

 

5 minutes ago, Hans-Pe said:

I will probably not use Vitor's workflow in the future, but I find its implementation very instructive. 

 

That is fine. And thank you for the feedback, I’m glad you can take something out of it even if you don’t use it. Ultimately, the workflow works for the use case it was designed. While I’m amenable to making tweaks to support other setups, like I did in the previous versions I gave you, the line has to be drawn somewhere. The code is open and editable in the workflow so you’re welcome to adapt it further to your needs.

 

You may also prefer the initial version of the workflow. Initially I moved away from that because Apple broke searching for manual pages in the infamous Sonoma 14.5. I reported the issue and they fixed it, but by then I liked the new approach better, because knowing the location gives you a better idea of which version of the manual you’re looking at.

 

3 minutes ago, gingerbeardman said:

I run it after each macOS system update so that man pages installed through brew are found. Maybe there's a better way?

 

Found by what? The workflow should see Homebrew manuals fine. You mean in the Terminal? Do you eval "$(/opt/homebrew/bin/brew shellenv)" in your shell’s startup file? That is specifically recommended.

 

Note for people finding this in the future: that recommendation is for Apple Silicon, on Intel you’d replace /opt/homebrew/ with /usr/local.

 

6 minutes ago, gingerbeardman said:

I'm also using Zach Schulze's man page workflow, which presents them in Terminal.

 

I’m not familiar with that one. But this workflow can open pages in Terminal too. Check the configuration, there are six different viewers.

 

[gingerbeardman]

1 hour ago, vitor said:

Found by what? The workflow should see Homebrew manuals fine. You mean in the Terminal? Do you eval "$(/opt/homebrew/bin/brew shellenv)" in your shell’s startup file? That is specifically recommended.

Found by man on my system using the workflow I posted earlier.

 

I just thought my tip might be of interest based on the earlier discussion.

 

Your workflow works without issue.

 

1 hour ago, vitor said:

I’m not familiar with that one. But this workflow can open pages in Terminal too. Check the configuration, there are six different viewers.

Nice! It would be cool if it could use the man page terminal colour scheme profile.

 

 

Edited June 14 by gingerbeardman

[vitor]

Initially I was going to use the “yellow pages” scheme but that’s a Terminal.app thing and it’s more general if it uses whatever terminal is configured in Alfred’s Preferences. A lot of people use iTerm2.

[gingerbeardman]

Do you mean I can set the yellow colour scheme through Alfred Prefs? Or am I misunderstanding?

[vitor]

No, I mean that yellow style is a specific thing, it happens when you use the x-man-page:// URL scheme. But that always opens in Terminal.app, which is annoying for those who use another terminal. Rather I explicitly tell Alfred to open it with whatever the user has in Alfred Preferences → Features → Terminal so it happens in whatever you use.

[gingerbeardman]

Ah, OK, in that case would you be open to adding x-man-page:// to the list of viewers in this workflow config?

 

 

Edited June 14 by gingerbeardman

[gingerbeardman]

I added it quite easily like so:

 

script is

fullpath="{query}"

echo -n ${fullpath:t:r}

but it could all be in a single script node that does: open "x-man-page://${fullpath:t:r}"

 

Interestingly, this way of calling requires my earlier MANPATH workaround to find the man pages from brew packages. 😕

So it seems x-man-page:// opens Terminal in a way that it is not seeing PATH or env

 

Edited June 14 by gingerbeardman