For discussion of Alpine Linux development and developer support

3 2

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

Paul Onyschuk
Details
Message ID
<20110601122435.20658e79.blink@bojary.koba.pl>
Sender timestamp
1306923875
DKIM signature
missing
Download raw message
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 <blink@bojary.koba.pl>
Paul Onyschuk
Details
Message ID
<20110601124222.ee2575ed.blink@bojary.koba.pl>
In-Reply-To
<20110601122435.20658e79.blink@bojary.koba.pl> (view parent)
Sender timestamp
1306924942
DKIM signature
missing
Download raw message
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.

-- 
Paul Onyschuk <blink@bojary.koba.pl>


---
Unsubscribe:  alpine-devel+unsubscribe@lists.alpinelinux.org
Help:         alpine-devel+help@lists.alpinelinux.org
---
Paul Onyschuk
Details
Message ID
<20110602144523.bfe3a323.blink@bojary.koba.pl>
In-Reply-To
<20110601124222.ee2575ed.blink@bojary.koba.pl> (view parent)
Sender timestamp
1307018723
DKIM signature
missing
Download raw message
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/

-- 
Paul Onyschuk <blink@bojary.koba.pl>


---
Unsubscribe:  alpine-devel+unsubscribe@lists.alpinelinux.org
Help:         alpine-devel+help@lists.alpinelinux.org
---
Natanael Copa
Details
Message ID
<20110602152538.066ee77d@ncopa-desktop.nor.wtbts.net>
In-Reply-To
<20110602144523.bfe3a323.blink@bojary.koba.pl> (view parent)
Sender timestamp
1307021138
DKIM signature
missing
Download raw message
On Thu, 2 Jun 2011 14:45:23 +0200
Paul Onyschuk <blink@bojary.koba.pl> wrote:

> 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.

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

...

> 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

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
> postponed.

Thanks! I look forward to the continuation of this!

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

-nc


---
Unsubscribe:  alpine-devel+unsubscribe@lists.alpinelinux.org
Help:         alpine-devel+help@lists.alpinelinux.org
---