ManPageQL

Intro

ManPageQL is a macOS Quick Look plugin used to preview *nix manual page, it uses mandoc to render HTML format output.

Current only support limited man page extensions: .1, .2, .3, .4, .5, .6, .7, .8, .9, .n

Compile

NOTE: This repository uses Git-LFS to track dylib, make sure dylib files are fetched to local before make.

This project is managed by Makefile and Makefile.inc, thus you can simply run make in terminal for a debug build, append release for a release build.

Install & uninstall

# Install/uninstall Quick Look plugin for current user
make install
make uninstall

# Install/uninstall Quick Look plugin for all users
PREFIX=/Library/QuickLook sudo make install
PREFIX=/Library/QuickLook sudo make uninstall

# Remove all settings
defaults delete cn.junkman.quicklook.ManPageQL

Debugging & test

# for macOS >= 10.13
log stream --style compact --predicate 'process == "QuickLookSatellite" AND eventMessage CONTAINS "ManPageQL"' --color=auto

# for macOS >= 10.12
log stream --style compact --predicate 'process == "QuickLookSatellite" AND eventMessage CONTAINS "ManPageQL"'

# for macOS < 10.12
syslog -w 0 -k Sender QuickLookSatellite -k Message S ManPageQL

Settings

• Read current settings

   defaults read cn.junkman.quicklook.ManPageQL

• Turn on raw text preview

   defaults write cn.junkman.quicklook.ManPageQL RawTextForPreview -bool TRUE

• Turn on raw text thumbnail

   defaults write cn.junkman.quicklook.ManPageQL RawTextForThumbnail -bool TRUE

• Specify preview width / height

   defaults write cn.junkman.quicklook.ManPageQL WidthHeightForPreview -string <width>:<height>

  width and <height> are numbers in points, you can omit one of them.

   800:600 # Specify width & height
   800     # Specify width only
   800:    # ditto.
   :600    # Specify height only(XXX: Quick Look daemon will ignore if you specify height solely)
  

  [sic] Note that this(width, height) property is a hint; Quick Look might set the width automatically for some types of previews.

• Use custom style sheet for preview(won't affect behaviour of manual page thumbnailing)

   defaults write cn.junkman.quicklook.ManPageQL StyleSheetForPreview -string <file>

  The <file> is a path to the custom style sheet file, it can either be a absolute path, or a relative path, when specify a relative path, the file will search from plugin bundle's Resources directory.

  ~, ., .. are thusly supported.

  There're several embedded style sheets in Resources directory:

  • mandoc.css

  • fixed.css

Compile libmandoc2html shared library

libmandoc2html use mandoc as its core functionalities, it's merely a wrapper of mandoc, which this Quick Look plugin is link against it.

HOWTO compile libmandoc2html.dylib from latest mandoc source

# Clone mandoc CVS repository
# see: https://mandoc.bsd.lv/anoncvs.html
$ cvs -d anoncvs@mandoc.bsd.lv:/cvs co mandoc

$ cd mandoc
# Replace $MANPAGEQL_REPO_DIR to this repo path on your computer
$ patch < $MANPAGEQL_REPO_DIR/mandoc/make.patch
patching file Makefile
patching file Makefile.depend
patching file configure
patching file configure.local.example

$ ./configure
$ cp $MANPAGEQL_REPO_DIR/mandoc/mandoc2html.c .
$ cp $MANPAGEQL_REPO_DIR/mandoc/mandoc2html.h .
$ make mandoc2html

Copy generated libmandoc2html.dylib into $MANPAGEQL_REPO_DIR/mandoc

HOWTO check libmandoc2html.dylib's version

$ otool -L libmandoc2html.dylib
libmandoc2html.dylib:
	@loader_path/libmandoc2html.dylib (compatibility version 1.0.0, current version 1.14.4)
	/usr/lib/libz.1.dylib (compatibility version 1.0.0, current version 1.2.11)
	/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1252.50.4)

TODO

• Add user-configurable options

  • [DONE] Allow user to use raw text thumbnail/preview

  • [DONE] Allow user to specify preview width/height

  • ...

• Use hash-encoded name to cache-up on-disk files

• Support .so requests. Hint: use chdir(2) before generate output?

• Support thumbnail/preview of gzip-ed man page files(mandoc supports parse gzip-ed man page file natively)

  Hint: extensions: .1.gz, .2.gz, ...

• Support universal man page file detection, instead of known extensions like .1, .2, ...

  Hint: use file --brief --mime-type <file> for detection?

• Support man page symlink thumbnail/preview

• Support custom os_s in mparse_alloc(int, enum mandoc_os, const char *);

• [DONE] Support -Ostyle=style.css option in mandoc2html

• Use @rpath instead of @loader_path in libmandoc2html.dylib?

• Support nroff(1) + cat2html for thumbnail/preview?

• Display file size, time, etc. when preview.

  Hint: set kQLPreviewPropertyDisplayNameKey in preview properties

Contributing

If you ready to gets your hands dirty, here are the guidelines for contributing:

• Fork this repository and clone to your local machine

• Create a new branch and add some commits

• Push your local branch to your fork

• Submit a pull request upstream

License

Please regard LICENSE file

Screenshots

References

clang, change dependent shared library install name at link time

Install_name on OS X

Xcode Build Settings Reference

Creating Dynamic Libraries

ExampleQL - Makefile for macOS Quick Look plugin

How to open/link external files inside a HTML-designed QuickLook plugin without using the attribute?

Dynamically Generating Previews#Generating Enriched HTML

---

Created 190219+0800