{"id":15723966,"url":"https://github.com/leiless/manpageql","last_synced_at":"2025-03-13T00:31:23.801Z","repository":{"id":140255171,"uuid":"171493165","full_name":"leiless/ManPageQL","owner":"leiless","description":"macOS Quick Look plugin for *nix manual page","archived":false,"fork":false,"pushed_at":"2019-02-28T15:21:42.000Z","size":121,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-06T01:40:14.120Z","etag":null,"topics":["quicklook","quicklook-plugin"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leiless.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-02-19T14:57:20.000Z","updated_at":"2024-05-10T17:55:16.000Z","dependencies_parsed_at":null,"dependency_job_id":"ae20a095-ad0f-4061-886e-749135eb8894","html_url":"https://github.com/leiless/ManPageQL","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leiless%2FManPageQL","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leiless%2FManPageQL/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leiless%2FManPageQL/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leiless%2FManPageQL/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leiless","download_url":"https://codeload.github.com/leiless/ManPageQL/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243318767,"owners_count":20272136,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["quicklook","quicklook-plugin"],"created_at":"2024-10-03T22:13:58.046Z","updated_at":"2025-03-13T00:31:23.789Z","avatar_url":"https://github.com/leiless.png","language":"C","readme":"## ManPageQL\n\n### Intro\n\nManPageQL is a macOS Quick Look plugin used to preview [*nix manual page](https://en.wikipedia.org/wiki/Man_page), it uses [mandoc](https://mandoc.bsd.lv/) to render HTML format output.\n\nCurrent only support limited man page extensions: `.1`, `.2`, `.3`, `.4`, `.5`, `.6`, `.7`, `.8`, `.9`, `.n`\n\n### Compile\n\nNOTE: This repository uses [Git-LFS](https://git-lfs.github.com/) to track `dylib`, make sure `dylib` files are fetched to local before `make`.\n\nThis 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.\n\n### Install \u0026 uninstall\n\n```shell\n# Install/uninstall Quick Look plugin for current user\nmake install\nmake uninstall\n\n# Install/uninstall Quick Look plugin for all users\nPREFIX=/Library/QuickLook sudo make install\nPREFIX=/Library/QuickLook sudo make uninstall\n\n# Remove all settings\ndefaults delete cn.junkman.quicklook.ManPageQL\n```\n\n### Debugging \u0026 test\n\n```\n# for macOS \u003e= 10.13\nlog stream --style compact --predicate 'process == \"QuickLookSatellite\" AND eventMessage CONTAINS \"ManPageQL\"' --color=auto\n\n# for macOS \u003e= 10.12\nlog stream --style compact --predicate 'process == \"QuickLookSatellite\" AND eventMessage CONTAINS \"ManPageQL\"'\n\n# for macOS \u003c 10.12\nsyslog -w 0 -k Sender QuickLookSatellite -k Message S ManPageQL\n```\n\n### Settings\n\n* Read current settings\n\n\t```shell\n\tdefaults read cn.junkman.quicklook.ManPageQL\n\t```\n\n* Turn on raw text preview\n\n\t```shell\n\tdefaults write cn.junkman.quicklook.ManPageQL RawTextForPreview -bool TRUE\n\t```\n\n* Turn on raw text thumbnail\n\n\t```shell\n\tdefaults write cn.junkman.quicklook.ManPageQL RawTextForThumbnail -bool TRUE\n\t```\n\n* Specify preview width / height\n\n\t```shell\n\tdefaults write cn.junkman.quicklook.ManPageQL WidthHeightForPreview -string \u003cwidth\u003e:\u003cheight\u003e\n\t```\n\n\t`width` and `\u003cheight\u003e` are numbers in points, you can omit one of them.\n\n\t```\n\t800:600 # Specify width \u0026 height\n\t800     # Specify width only\n\t800:    # ditto.\n\t:600    # Specify height only(XXX: Quick Look daemon will ignore if you specify height solely)\n\t```\n\n\t[[sic](https://developer.apple.com/documentation/quicklook/kqlpreviewpropertywidthkey?language=objc)] Note that this(width, height) property is a hint; Quick Look might set the width automatically for some types of previews.\n\n* Use custom style sheet for preview(won't affect behaviour of manual page thumbnailing)\n\n\t```shell\n\tdefaults write cn.junkman.quicklook.ManPageQL StyleSheetForPreview -string \u003cfile\u003e\n\t```\n\n\tThe `\u003cfile\u003e` 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.\n\n\t`~`, `.`, `..` are thusly supported.\n\n\tThere're several embedded style sheets in `Resources` directory:\n\n\t* mandoc.css\n\n\t* fixed.css\n\n### Compile `libmandoc2html` shared library\n\n`libmandoc2html` use [mandoc](https://mandoc.bsd.lv/) as its core functionalities, it's merely a wrapper of [mandoc](https://mandoc.bsd.lv/), which this Quick Look plugin is link against it.\n\nHOWTO compile `libmandoc2html.dylib` from latest [mandoc](https://mandoc.bsd.lv/) source\n\n```shell\n# Clone mandoc CVS repository\n# see: https://mandoc.bsd.lv/anoncvs.html\n$ cvs -d anoncvs@mandoc.bsd.lv:/cvs co mandoc\n\n$ cd mandoc\n# Replace $MANPAGEQL_REPO_DIR to this repo path on your computer\n$ patch \u003c $MANPAGEQL_REPO_DIR/mandoc/make.patch\npatching file Makefile\npatching file Makefile.depend\npatching file configure\npatching file configure.local.example\n\n$ ./configure\n$ cp $MANPAGEQL_REPO_DIR/mandoc/mandoc2html.c .\n$ cp $MANPAGEQL_REPO_DIR/mandoc/mandoc2html.h .\n$ make mandoc2html\n```\n\nCopy generated `libmandoc2html.dylib` into `$MANPAGEQL_REPO_DIR/mandoc`\n\n\u003cbr\u003e\n\nHOWTO check `libmandoc2html.dylib`'s version\n\n```shell\n$ otool -L libmandoc2html.dylib\nlibmandoc2html.dylib:\n\t@loader_path/libmandoc2html.dylib (compatibility version 1.0.0, current version 1.14.4)\n\t/usr/lib/libz.1.dylib (compatibility version 1.0.0, current version 1.2.11)\n\t/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1252.50.4)\n```\n\n### TODO\n\n* Add user-configurable options\n\n\t* [**DONE**] Allow user to use raw text thumbnail/preview\n\n\t* [**DONE**] Allow user to specify preview width/height\n\n \t* ...\n\n* Use hash-encoded name to cache-up on-disk files\n\n* Support `.so` requests. Hint: use `chdir(2)` before generate output?\n\n* Support thumbnail/preview of `gzip`-ed man page files([mandoc](https://mandoc.bsd.lv/) supports parse `gzip`-ed man page file natively)\n\n\tHint: extensions: `.1.gz`, `.2.gz`, ...\n\n* Support universal man page file detection, instead of known extensions like `.1`, `.2`, ...\n\n\tHint: use `file --brief --mime-type \u003cfile\u003e` for detection?\n\n* Support man page symlink thumbnail/preview\n\n* Support custom `os_s` in `mparse_alloc(int, enum mandoc_os, const char *);`\n\n* [**DONE**] Support `-Ostyle=style.css` option in `mandoc2html`\n\n* Use `@rpath` instead of `@loader_path` in `libmandoc2html.dylib`?\n\n* Support `nroff(1)` + cat2html for thumbnail/preview?\n\n* Display file size, time, etc. when preview.\n\n\tHint: set `kQLPreviewPropertyDisplayNameKey` in preview properties\n\n### Contributing\n\nIf you ready to gets your hands dirty, here are the guidelines for contributing:\n\n* Fork this repository and clone to your local machine\n\n* Create a new branch and add some commits\n\n* Push your local branch to your fork\n\n* Submit a pull request upstream\n\n### License\n\nPlease regard `LICENSE` file\n\n### Screenshots\n\n![](screenshots/1.png)\n\n![](screenshots/2.png)\n\n![](screenshots/3.png)\n\n### *References*\n\n[clang, change dependent shared library install name at link time](https://stackoverflow.com/questions/27506450/clang-change-dependent-shared-library-install-name-at-link-time)\n\n[Install_name on OS X](http://log.zyxar.com/blog/2012/03/10/install-name-on-os-x/)\n\n[Xcode Build Settings Reference](https://pewpewthespells.com/blog/buildsettings.html)\n\n[Creating Dynamic Libraries](https://developer.apple.com/library/archive/documentation/DeveloperTools/Conceptual/DynamicLibraries/100-Articles/CreatingDynamicLibraries.html)\n\n[ExampleQL - Makefile for macOS Quick Look plugin](https://github.com/lynnlx/quicklook_plugin)\n\n[How to open/link external files inside a HTML-designed QuickLook plugin without using the \u003csrc\u003e attribute?](https://stackoverflow.com/questions/23758539/how-to-open-link-external-files-inside-a-html-designed-quicklook-plugin-without)\n\n[Dynamically Generating Previews#Generating Enriched HTML](https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/Quicklook_Programming_Guide/Articles/QLDynamicGeneration.html#//apple_ref/doc/uid/TP40005020-CH15-SW2)\n\n---\n\n*Created 190219+0800*","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleiless%2Fmanpageql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleiless%2Fmanpageql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleiless%2Fmanpageql/lists"}