Subject: [alpine-devel] [apkbuild] mdocml - man page tool

From: Paul Onyschuk <[email-masked]>
Date: Wed, 1 Jun 2011 12:24:35 +0200

Mdocml[1] is sane groff replacment for processing man/mdoc pages. It
can be used like this:

$ mandoc /usr/share/man/man1/some-man.1 | less

It has also support for html output, so it can be piped to webrowser:

$ mandoc -Thtml /usr/share/man/man1/some-man.1 | lynx -stdin

I checked some manuals (python, openssl) and they works just fine.
APKBUILD[2] is straightforward - please point out my mistakes ;) I
don't know if it works under x86_64.

Busybox man(1) command can be easy modified to use mdocml isteed of
groff. After building Busybox with patch[3], simple commands can be
used:

$ man some-man

This patch is optional, just to show how it can be done.

Mdocml tool makewhatis(1) can be build also (subpackage?) to create
apropos/whereis database.

[1] http://mdocml.bsd.lv/
[2] import-mdocml-1.11.3.patch
[3] add-support-for-mdocml-in-busybox-man-1.patch

-- 
Paul Onyschuk <[email-masked]>

---

From: Paul Onyschuk <[email-masked]>
Date: Wed, 1 Jun 2011 12:42:22 +0200

I forgot to mention that with Busybox man(1) patch you need also
specify man pages path e.g.:

$ echo "MANDATORY_MANPATH /usr/share/man" > /etc/man_db.conf

Alternatively you can set $MANPATH:

$ export MANPATH=/usr/share/man

or just put this in your .profile.

---
Unsubscribe:  [email-masked]
Help:         [email-masked]
---

---

From: Paul Onyschuk <[email-masked]>
Date: Thu, 2 Jun 2011 14:45:23 +0200

I founded man(1)/apropos(1)/whatis(1) commands written in pure shell
script. They were created by Gordon Tetlow, and can by obtained from
FreeBSD -HEAD repository[1].

They're bigger than Busybox man(1), but with them mdocml package could
be stanalone man toolset. File mk.sh could be copied to /usr/libexec
and symlinked to /usr/bin/man, /usr/bin/apropos and /usr/bin/whatis.

This way conflicts with groff man toolset could be avioded to some
degree and user has choice of using groff or mdocml.

Script requires some works, because it's groff oriented and using groff
is all about pipes (if anyone wondered why it's so slow), example:

$ /usr/bin/zcat -f /usr/share/man/man1/some-man.1 | tbl \
| groff -S -P-c -Wall -mtty-char -man -Tascii | /usr/bin/col | less

And mdocml (tbl and eqn are build-in) example:

$ mandoc -Tascii /usr/share/man/man1/some-man.1 | less

This modification can be applied pretty easy (I've working copy). Some
other features of mk.sh can be removed:

- Support for so called cat pages (preformated man pages)
- Support for localized man pages / AFAIK uclibc doesn't support locales
- Some other minor things like platform specific lookups (searching for
x86/x86_64 in section(4))

What is the point of all of this:

- groff binaries are ~8.5MB (I don't count man(1) implementation, which
isn't small either), where Apline Linux base system can be under 10MB
- mdocml binary is ~230KB and mk.sh is ~20KB
- mdocml is good enough replacment - some man pages can misbehave, but
mdocml is geting better every day and there is also problem with badly
formated man pages
- mdocml is much much faster, to get more groff-like feeling use:
	$ sleep 0.7 && mandoc /usr/share/man/man1/some-man.1 | less

I'm going into wilderness for few days, so this work will be postponed.

[1] http://svnweb.freebsd.org/base/head/usr.bin/man/

---

---

From: Natanael Copa <[email-masked]>
Date: Thu, 2 Jun 2011 15:25:38 +0200

On Thu, 2 Jun 2011 14:45:23 +0200

> and symlinked to /usr/bin/man, /usr/bin/apropos and /usr/bin/whatis.

It makes sense to use a separate toolset since we have separate -doc
packages.

...

> - groff binaries are ~8.5MB (I don't count man(1) implementation,
> which isn't small either), where Apline Linux base system can be
> under 10MB

The above reasons are more than enough. I've wanted mdocml for some
time but never had time to follow it up properly.
 
> I'm going into wilderness for few days, so this work will be

Thanks! I look forward to the continuation of this!

> [1] http://svnweb.freebsd.org/base/head/usr.bin/man/

-nc

---