ManPageQL: A C repository from leiless

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