add FAQ, ChangeLog, install target

5 files changed, 120 insertions, 6 deletions

diff --git a/ChangeLog b/ChangeLog
new file mode 100644
index 0000000..922d693
--- /dev/null
+++ b/ChangeLog
@@ -0,0 +1 @@
+20200507 bkw: Initial v0.0.1 alpha.
diff --git a/FAQ b/FAQ
new file mode 100644
index 0000000..16c5dde
--- /dev/null
+++ b/FAQ
@@ -0,0 +1,64 @@
+miragextract FAQ (sort-of)
+--------------------------
+
+These are not really 'frequently asked', because nobody's asked me a
+single question about miragextract yet (it's brand new). Maybe this
+should be called the SAQ (Someday Asked Questions) or the NYAQ (Not Yet
+Asked Questions).
+
+Q1. How does miragextract work?
+A1. Basically, miragextract is a command-line wrapper for libmirage,
+plus 'glue' to connect it to libsndfile. These libraries do all the
+real work.
+
+Q2. Why did you write it?
+A1. There are a lot of little tools made to convert various CD image
+formats to something useful. Most of them just convert to ISO, meaning
+they don't handle audio tracks. Each image format has its own tool, and
+a lot of them are old and unmaintained so they don't keep up with changes
+in the proprietary formats. The libmirage developers gave us a wonderful
+library, but previously the only way to use it was to use cdemu, which
+works great but requires root privileges, uses an out-of-tree kernel
+module, and only works on Linux. I thought it'd be nice to have a simple
+tool that's at leat potentially portable, so here it is.
+
+Q3. What would I use miragextract for?
+A3. Well, I use it for extracting ISO images and audio files from old game
+CDs, for use with modern game engines (e.g. Raze or NBlood), or sometimes
+just to listen to the audio tracks. You can use it for anything you want
+(it's licensed WTFPL, so that means *anything*).
+
+Q4. Why is there no '-f mp3' option?
+A4. Because I use libsndfile to write the audio files, and its developer
+has chosen not to include mp3 support. If you really need mp3 (if ogg and/or
+flac just won't satisfy you), you can always convert to wav and use any
+mp3 converter (lame, ffmpeg, etc). Someday I may actually add lame support
+to miragextract, but don't hold your breath.
+
+Q5. Why do my extracted audio tracks sound like white noise?
+A5. Try the -s flag. If you're on a big-endian platform and you have this
+issue, I'd like to hear from you (email address found in README).
+
+Q6. This track01.iso I just extracted isn't an ISO, it's a Macintosh DMG.
+How come it's got .iso in the filename?
+A6. There's no way for miragextract to tell what type of image a data
+track actually contains. Adding support for this would be possible,
+but it's not there yet. Currently, the file will get called .iso because
+that's what most images contain. Just rename it if it's wrong.
+
+Q7. I built a static binary of miragextract, but it fails (or still requires
+shared libraries). Why?
+A7. libmirage uses a plugin system for supporting the various formats it
+knows about. This means it's basically impossible to compile libmirage
+statically, so miragextract can't really be static either. It's probably
+possible to make it work with an appropriate invocation of 'statifier'
+but I haven't tried this yet.
+
+Q8. Does it work on Windows, OSX, FreeBSD, ...?
+A8. In principle, there's nothing Linux-specific in miragextract, libmirage,
+or libsndfile. Porting to other OSes will require more knowledge of those OSes
+(and more time) than I currently have available, but I'll accept patches.
+
+Q9. Can I use it with real CDs?
+A9. No. libmirage doesn't support reading real CDs. Use regular CD-ripping
+software to get audio tracks, and 'dd' to extract an iso image.
diff --git a/Makefile b/Makefile
index 96a0566..f8c5de9 100644
--- a/Makefile
+++ b/Makefile
@@ -1,9 +1,32 @@
-PROJ=miragextract
+# Makefile for miragextract
+
+####
+# Packagers: override these the make command line as needed.
 
-# Packagers: override these on make command line as needed.
+# Intended for optimizations, but you could include other flags here.
 OPTFLAGS=-O2
+
+# -L, -l, and maybe -Wl flags here.
 LDEXTRA=
 
+# Where 'make install' puts things.
+PREFIX=/usr/local
+BINDIR=$(PREFIX)/bin
+MANDIR=$(PREFIX)/share/man
+MAN1DIR=$(MANDIR)/man1
+DOCDIR=$(PREFIX)/share/doc/$(PROJ)
+DESTDIR=
+
+# Booleans: 'y' or 'n' for these.
+STRIPBIN=y
+GZIPMAN=y
+
+#
+###
+
+PROJ=miragextract
+DOCS=README FAQ ChangeLog $(PROJ).html
+
 SNDFILE_CFLAGS:=$(shell pkg-config --cflags sndfile)
 SNDFILE_LIBS:=$(shell pkg-config --libs sndfile)
 
@@ -11,7 +34,7 @@ MIRAGE_CFLAGS:=$(shell pkg-config --cflags libmirage)
 MIRAGE_LIBS:=$(shell pkg-config --libs libmirage)
 
 CFLAGS=-Wall $(OPTFLAGS) $(MIRAGE_CFLAGS) $(SNDFILE_CFLAGS)
-LDFLAGS=$(LDEXTRA) $(MIRAGE_LIBS) $(SNDFILE_LIBS)
+LDFLAGS=$(MIRAGE_LIBS) $(SNDFILE_LIBS)$ $(LDEXTRA)
 
 all: $(PROJ)
 
@@ -33,4 +56,30 @@ $(PROJ).1: $(PROJ).rst
 $(PROJ).html: $(PROJ).rst
 	rst2html4.py $(PROJ).rst > $(PROJ).html
 
-.PHONY: all man html test push
+ifeq ($(shell whoami),root)
+CHOWN=chown
+else
+CHOWN=: chown
+endif
+
+install: all man html
+	mkdir -p $(DESTDIR)$(BINDIR) $(DESTDIR)$(MAN1DIR) $(DESTDIR)$(DOCDIR)
+	cp $(PROJ) $(DESTDIR)$(BINDIR)
+	$(CHOWN) root:root $(DESTDIR)$(BINDIR)/$(PROJ)
+	chmod 755 $(DESTDIR)$(BINDIR)/$(PROJ)
+ifeq ($(STRIPBIN),y)
+	strip $(DESTDIR)$(BINDIR)/$(PROJ)
+endif
+	cp $(PROJ).1 $(DESTDIR)$(MAN1DIR)
+ifeq ($(GZIPMAN),y)
+	gzip -9 $(DESTDIR)$(MAN1DIR)/$(PROJ).1
+endif
+	$(CHOWN) root:root $(DESTDIR)$(MAN1DIR)/$(PROJ).1
+	chmod 644 $(DESTDIR)$(MAN1DIR)/$(PROJ).1
+	for i in $(DOCS); do \
+		cp $$i $(DESTDIR)$(DOCDIR); \
+		chmod 644 $(DESTDIR)$(DOCDIR)/$$i; \
+		$(CHOWN) root:root $(DESTDIR)$(DOCDIR)/$$i; \
+	done
+
+.PHONY: all man html test push install
diff --git a/miragextract.1 b/miragextract.1
index b19d03e..7f01155 100644
--- a/miragextract.1
+++ b/miragextract.1
@@ -47,7 +47,7 @@ miragextract [\fB\-l\fP] [\fB\-s\fP] [\fB\-t\fP track] [\fB\-b\fP base] [\fB\-f\
 .sp
 Extracts data and audio tracks from any CD image supported by libmirage.
 Data tracks are written as\-is, and audio tracks can be written as\-is or
-converted to wav, flag, or ogg/vorbis (via libsndfile).
+converted to wav, flac, or ogg/vorbis (via libsndfile).
 .SH OPTIONS
 .INDENT 0.0
 .TP
diff --git a/miragextract.html b/miragextract.html
index 05b354f..0e1d91d 100644
--- a/miragextract.html
+++ b/miragextract.html
@@ -391,7 +391,7 @@ ul.auto-toc {
 <h1>DESCRIPTION</h1>
 <p>Extracts data and audio tracks from any CD image supported by libmirage.
 Data tracks are written as-is, and audio tracks can be written as-is or
-converted to wav, flag, or ogg/vorbis (via libsndfile).</p>
+converted to wav, flac, or ogg/vorbis (via libsndfile).</p>
 </div>
 <div class="section" id="options">
 <h1>OPTIONS</h1>