rewrite docs in markdown for github integration

6 files changed, 169 insertions, 122 deletions

diff --git a/HACKING b/HACKING
deleted file mode 100644
index 67dbbaf..0000000
--- a/HACKING
+++ /dev/null
@@ -1,32 +0,0 @@
-- Adding applets is easy using the q framework.
-  Note: Please try to keep applet names under 8 chars.
-	* cp template.c qmyapplet.c (all applets use the prefix of the letter 'q') 
-	* applets.h: add your prototype (see DECLARE_APPLET macro)
-	* applets.h: add a new line to applets[] following the existing syntax
-	* run `make depend` to auto regenerate dependent files
-
-When and where you can please try to use an existing applet and extend 
-on its functionality by adding more options vs adding a bunch of new 
-little applets.
-
-- Keep behavior consistent
-	* matching:
-		default is sloppy match
-		-e exact match
-		-r regex match
-
-## Examples:
-	* find elf files linking to old openssl
-	qlist -ao | scanelf -BqgN libssl.so.0.9.6 -f -
-
-	* print a package.use
-	qlist -UCq | grep ' ' > package.use
-
-	* find orphan files not owned by any package in /lib and /usr/lib
-	qfile -o {,/usr}/lib/*
-	
-	# get PORTDIR
-	DEBUG=: ./q -Ch 2>&1 | grep ^PORTDIR | awk '{print $3}
-
-	# Verify all packages
-	qcheck -a
diff --git a/HACKING.md b/HACKING.md
new file mode 100644
index 0000000..e0536fa
--- /dev/null
+++ b/HACKING.md
@@ -0,0 +1,20 @@
+# New applets
+
+Adding applets is easy using the q framework.
+
+Note: Please try to keep applet names under 8 chars.
+
+- cp template.c qmyapplet.c (all applets use the prefix of the letter 'q') 
+- applets.h: add your prototype (see DECLARE_APPLET macro)
+- applets.h: add a new line to applets[] following the existing syntax
+- run `make depend` to auto regenerate dependent files
+
+When and where you can please try to use an existing applet and extend 
+on its functionality by adding more options vs adding a bunch of new 
+little applets.
+
+- Keep behavior consistent
+	- matching:
+		- default is sloppy match
+		- -e exact match
+		- -r regex match
diff --git a/README b/README
deleted file mode 100644
index 1a8dc3d..0000000
--- a/README
+++ /dev/null
@@ -1,31 +0,0 @@
-# Copyright 2005-2014 Gentoo Foundation
-# Distributed under the terms of the GNU General Public License v2
-
-Contact:
-  Please file bugs at:
-	https://bugs.gentoo.org/enter_bug.cgi?product=Portage%20Development&format=guided
-  Use Component of "Third-Party Tools".
-
-Current developer list:
-	solar@gentoo.org
-	vapier@gentoo.org
-
-
-- Speed is everything.
-  Having your PORTDIR and VDB on the right file system helps dramatically
-
-  IDE raid with PORTDIR on reiserfs:
-    q -r
-    q: Finished 20655 entries in 1.990951 seconds
-
-  IDE raid with PORTDIR on ext3:
-    q -r
-    q: Finished 20655 entries in 203.664252 seconds
-
-
-- Fetching via anon git:
-
-  git clone git://anongit.gentoo.org/proj/portage-utils.git
-
-You can view it online via gitweb:
-	https://gitweb.gentoo.org/proj/portage-utils.git/
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3889ee2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,72 @@
+# Gentoo Portage Utilities
+
+| What     | How                                                       |
+| -------- | --------------------------------------------------------- |
+| HOMEPAGE | https://wiki.gentoo.org/wiki/Portage-utils                |
+| GIT      | git clone git://anongit.gentoo.org/proj/portage-utils.git |
+| VIEWVCS  | https://gitweb.gentoo.org/proj/portage-utils.git/         |
+| STATUS   | [![Build Status](https://travis-ci.org/gentoo/portage-utils.svg?branch=master)](https://travis-ci.org/gentoo/portage-utils) [![Coverity Status](https://scan.coverity.com/projects/9213/badge.svg)](https://scan.coverity.com/projects/gentoo-portage-utils) |
+
+portage-utils is a small set of utilities for working with Portage, Gentoo
+ebuilds, Gentoo ebuild overlays, installed packages (vdb), and similar sources
+of information.  The focus is on size and speed, so everything is in C.
+
+## Building
+
+Just run `make`.  This should work on any recent POSIX compliant system.
+
+## Helping out
+
+There's a large [TODO](./TODO.md) list with various ideas for improvements.
+
+There's also a [HACKING](./HACKING.md) doc to help you get started.
+
+## Examples
+
+* find elf files linking to old openssl<br>
+  `qlist -ao | scanelf -BqgN libssl.so.0.9.6 -f -`
+
+* print a package.use<br>
+  `qlist -UCq | grep ' ' > package.use`
+
+* find orphan files not owned by any package in /lib and /usr/lib<br>
+  `qfile -o {,/usr}/lib/*`
+	
+* get PORTDIR<br>
+  `DEBUG=: ./q -Ch 2>&1 | grep ^PORTDIR | awk '{print $3}`
+
+* Verify all packages<br>
+  `qcheck -a`
+
+## Contact
+
+### Bugs
+
+Please file bugs at:
+	https://bugs.gentoo.org/enter_bug.cgi?product=Portage%20Development&format=guided
+
+Use Component of "Third-Party Tools".
+
+### Developers
+
+* solar@gentoo.org
+* vapier@gentoo.org
+
+## Notes
+
+### Speed is everything.
+
+Having your PORTDIR and VDB on the right file system helps dramatically
+
+IDE raid with PORTDIR on reiserfs:
+
+```
+$ q -r
+q: Finished 20655 entries in 1.990951 seconds
+
+IDE raid with PORTDIR on ext3:
+
+```
+$ q -r
+q: Finished 20655 entries in 203.664252 seconds
+```
diff --git a/TODO b/TODO
deleted file mode 100644
index 08e8bc3..0000000
--- a/TODO
+++ /dev/null
@@ -1,59 +0,0 @@
-- unify match behavior:
- default *foo*
- -e foo
- -r (-R ?) regexp foo.*
-
-- disable color when tty = NULL; may break less?
-
-- multiline reads don't yet work for quse/qsearch
-
-- standardize/unify/clean up misc handling of colors
-
-- speed up queue structure ... append walks the whole list
-
-- qmerge
-	- dep resolver needs spanktastic love.
-	- needs safe deleting (merge in place rather than unmerge;merge)
-	- multiple binary repos (talk to zmedico)
-	- handle compressed Packages file (talk to zmedico)
-	- handle binary Packages file (talk to zmedico)
-	- gpg sign the packages file (before compression)
-	- binary vdb (sqlite) ... talk to zmedico
-	- remote vdb
-	- don't bother emitting any "DIR" entries to CONTENTS ?
-		- auto rmdir any empty dirs
-	- avoid Packages fetching all the damned time
-	- parallel fetch tbz2s
-	- check order of pkg_{pre,post}{inst,rm} during install, unmerge, and upgrade
-	- env is not saved/restored between pkg_{pre,post}inst (see portage and REPO_LAYOUT_CONF_WARN)
-	- support installing via path to tbz2 package
-	- support TTL field in binpkgs file
-
-- atoms:
-	- only 32bit values are supported for revision (-r#)
-	- only 64bit values are supported in any individual version component
-		foo-(1234)_alpha(56789)
-	- these limits should not be an issue for all practical purposes
-	- need to handle USE deps like: cat/pkg-123[foo(+)]
-	- show support slots like: qmerge -U automake:1.12
-
-- qcache:
-	- need to convert it to new metadata/md5 style
-
-- qdepends:
-	- support querying uninstalled packages (via metadata/md5 cache)
-
-- env vars only get expanded once, so this fails:
-	ACCEPT_LICENSE="foo"
-	ACCEPT_LICENSE="${ACCEPT_LICENSE} bar"
-  we end up getting just:
-	ACCEPT_LICENSE=" bar"
-
-- qpkg:
-	- fix "would be freed" message when --pretend is *not* active
-	- add a verbose output that describes why a package is cleaned
-		- newer binpkgs available
-		- newer installed version available
-
-- qsync:
-	- rewrite to use new repos.conf standard
diff --git a/TODO.md b/TODO.md
new file mode 100644
index 0000000..86ebbd7
--- /dev/null
+++ b/TODO.md
@@ -0,0 +1,77 @@
+# Common
+
+- unify match behavior:
+	- default *foo*
+	- -e foo
+	- -r (-R ?) regexp foo.*
+
+- disable color when tty = NULL; may break less?
+
+- multiline reads don't yet work for quse/qsearch
+
+- standardize/unify/clean up misc handling of colors
+
+- speed up queue structure ... append walks the whole list
+
+- equiv of `equery m` (metadata)
+
+- env vars only get expanded once, so this fails:<br>
+  `ACCEPT_LICENSE="foo"`<br>
+  `ACCEPT_LICENSE="${ACCEPT_LICENSE} bar"`<br>
+  we end up getting just:<br>
+  `ACCEPT_LICENSE=" bar"`
+
+# Atoms
+
+- only 32bit values are supported for revision (-r#)
+- only 64bit values are supported in any individual version component
+  foo-(1234)_alpha(56789)
+- these limits should not be an issue for all practical purposes
+- need to handle USE deps like: cat/pkg-123[foo(+)]
+- show support slots like: qmerge -U automake:1.12
+
+# qmerge
+
+- dep resolver needs spanktastic love.
+- needs safe deleting (merge in place rather than unmerge;merge)
+- multiple binary repos (talk to zmedico)
+- handle compressed Packages file (talk to zmedico)
+- handle binary Packages file (talk to zmedico)
+- gpg sign the packages file (before compression)
+- binary vdb (sqlite) ... talk to zmedico
+- remote vdb
+- don't bother emitting any "DIR" entries to CONTENTS ?
+	- auto rmdir any empty dirs
+- avoid Packages fetching all the damned time
+- parallel fetch tbz2s
+- check order of pkg_{pre,post}{inst,rm} during install, unmerge, and upgrade
+- env is not saved/restored between pkg_{pre,post}inst (see portage and REPO_LAYOUT_CONF_WARN)
+- support installing via path to tbz2 package
+- support TTL field in binpkgs file
+- merge duplicate atoms on the CLI (`qmerge -Uq nano nano nano`)
+- unmerging should clean out @world set
+
+# qcache
+
+- need to convert it to new metadata/md5 style
+
+# qdepends
+
+- support querying uninstalled packages (via metadata/md5 cache)
+- support atoms like `qdepends -rQ qtsql:4` (should match unslotted deps)
+- add -S/-v/-R behavior like qlist #574934
+
+# qpkg
+
+- fix "would be freed" message when --pretend is *not* active
+- add a verbose output that describes why a package is cleaned
+	- newer binpkgs available
+	- newer installed version available
+
+# qsync
+
+- rewrite to use new repos.conf standard
+
+# qlist
+
+- support atoms instead of exact matches