audio/mac: Man page, other enhancements.

Signed-off-by: B. Watson <yalhcru@gmail.com>

Signed-off-by: Willy Sudiarto Raharjo <willysr@slackbuilds.org>

5 files changed, 363 insertions, 14 deletions

diff --git a/audio/mac/README b/audio/mac/README
index d013f5dbfced..87df89945242 100644
--- a/audio/mac/README
+++ b/audio/mac/README
@@ -1,7 +1,14 @@
 mac (Monkey's Audio Linux port)
 
-mac is a console frontend to Monkey's Audio, able to encode and 
-decode APE audio files.
+Monkey's Audio (aka APE) is a lossless audio compression format,
+similar to FLAC. mac is a console frontend to Monkey's Audio, able to
+encode and decode APE audio files.
+
+Note: if you just want to listen to APE files, Slackware's mplayer
+and audacious can already play them. If you just want to convert them
+to some other format (wav, mp3, etc), Slackware's ffmpeg can already
+decode them. The only real reason to install this package is for
+converting files *to* APE format.
 
 If you're building this for an old x86 CPU that doesn't support MMX,
 set ASM=no in the script's environment.
@@ -10,3 +17,9 @@ The package is built using upstream's default optimization level,
 which is -O3. If you suspect this is causing problems, rebuild with
 FORCE_SLACK_CFLAGS=yes in the environment (this will force -O2). If this
 actually fixes anything, please email the maintainer with the details.
+
+Note: if you get "invalid input file" trying to encode a wav file, it
+probably means the wav file uses floating point rather than 16-bit
+integer samples. You can convert with sox:
+
+  sox -G input.wav -b16 output.wav
diff --git a/audio/mac/mac.1 b/audio/mac/mac.1
new file mode 100644
index 000000000000..baaf4b0c58bb
--- /dev/null
+++ b/audio/mac/mac.1
@@ -0,0 +1,169 @@
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "MAC" 1 "2021-11-25" "3.99_u4_b5_s7" "SlackBuilds.org"
+.SH NAME
+mac \- decode/encode Monkey's Audio codec files
+.\" RST source for mac(1) man page. Convert with:
+.
+.\" rst2man.py mac.rst > mac.1
+.
+.\" rst2man.py comes from the SBo development/docutils package.
+.
+.SH SYNOPSIS
+.sp
+\fBmac\fP [\fIinput\-file\fP] [\fIoutput\-file\fP] [ [\fB\-c\fP | \fB\-n\fP ] \fIlevel\fP ]
+.sp
+\fBmac\fP [\fIinput\-file\fP] [ \fB\-d\fP | \fB\-v\fP | \fB\-q\fP ]
+.SH DESCRIPTION
+.sp
+Monkey\(aqs Audio (aka APE) is a lossless audio compression format,
+similar to FLAC. mac is a console frontend to Monkey\(aqs Audio, able to
+encode and decode APE audio files.
+.sp
+If you encode a WAV file to APE, then decode it back to WAV, the
+audio in the decoded WAV file will be byte\-for\-byte identical to the
+original (although any extra data such as tags/comments in the RIFF
+header will not be preserved).
+.SH OPTIONS
+.sp
+Note: Only one of the options below can be given, and it must occur
+last on the command line (after the filename(s)). Spaces are not
+allowed between the \fB\-c\fP or \fB\-n\fP option and its \fIlevel\fP argument.
+.INDENT 0.0
+.TP
+.B \fB\-c[level]\fP
+Compress (encode). \fIinput\-file\fP must be a WAV file with 16\-bit samples.
+\fIoutput\-file\fP will be an APE audio file. Higher \fIlevel\fPs result
+in better compression, at the expense of longer encoding time. The
+supported levels are:
+.INDENT 7.0
+.INDENT 3.5
+.INDENT 0.0
+.TP
+.B 1000
+\fI(fast)\fP, usually around 45%\-50% compression ratio.
+.TP
+.B 2000
+\fI(normal)\fP, usually around 40%\-45% compression ratio.
+.TP
+.B 3000
+\fI(high)\fP, only slightly better than 2000 (usually by 1% or so).
+.TP
+.B 4000
+\fI(very high)\fP, probably the point of diminishing returns.
+.TP
+.B 5000
+\fI(insane)\fP, takes around 3x as long as 4000, may not compress any better.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.TP
+.B \fB\-n[level]\fP
+Convert (recompress). As \fB\-c\fP, but \fBinput\-file\fP must be an APE audio
+file.
+.TP
+.B \fB\-d\fP
+Decompress (decode). \fIinput\-file\fP must be an APE audio file.
+\fIoutput\-file\fP will be a WAV file.
+.TP
+.B \fB\-v\fP
+Verify. \fIinput\-file\fP must be an APE audio file. It will be decoded, and
+any errors will be displayed, but the decoded audio won\(aqt be saved.
+.TP
+.B \fB\-q\fP
+Quick verify. Just checks that \fIinput\-file\fP has a valid APE header.
+.TP
+.B \fB\-\-help\fP
+Show built\-in usage message (same as running \fBmac\fP with no arguments).
+.UNINDENT
+.SH EXAMPLES
+.INDENT 0.0
+.TP
+.B Compress
+mac "Metallica \- One.wav" "Metallica \- One.ape" \-c2000
+.TP
+.B Decompress
+mac "Metallica \- One.ape" "Metallica \- One.wav" \-d
+.TP
+.B Verify
+mac "Metallica \- One.ape" \-v
+.TP
+.B Quick verify
+mac "Metallica \- One.ape" \-q
+.UNINDENT
+.sp
+Note that filenames with spaces and punctuation should be put inside
+quote, as usual.
+.SH NOTES
+.sp
+\fBmac\fP can only handle WAV files with 8\- or 16\-bit samples, not
+e.g. 24\-bit or floating point. If needed, you can convert to 16\-bit
+with a command like:
+.INDENT 0.0
+.INDENT 3.5
+$ sox \-G input.wav \-b16 output.wav
+.UNINDENT
+.UNINDENT
+.sp
+WAV files must have 1 or 2 channels (mono or stereo;
+quad/surround/5.1/etc are not supported). Any sampling rate is
+supported.
+.sp
+\fBffmpeg\fP(1) can decode and convert APE files, though it cannot encode
+to APE.
+.sp
+\fBmplayer\fP(1) and \fBaudacious\fP(1) can play APE files.
+.sp
+\fBfile\fP(1) knows about APE files. Example:
+.INDENT 0.0
+.INDENT 3.5
+$ file test.ape
+.sp
+test.ape: Monkey\(aqs Audio compressed format version 3990 with normal compression, stereo, sample rate 48000
+.UNINDENT
+.UNINDENT
+.SH COPYRIGHT
+.sp
+See the file /usr/doc/mac\-3.99_u4_b5_s7/License.htm for license information.
+.SH AUTHORS
+.sp
+The original Monkey\(aqs Audio Codec was written by Matthew
+T. Ashland. It was ported to Linux by Frank Klemm and SuperMMX, then
+enhanced and bugfixed by Jason Jordan.
+.sp
+This man page written for the SlackBuilds.org project
+by B. Watson, and is licensed under the WTFPL.
+.SH SEE ALSO
+.sp
+\fBffmpeg\fP(1), \fBmplayer\fP(1), \fBaudacious\fP(1), \fBflac\fP(1), \fBshorten\fP(1), \fBsox\fP(1)
+.sp
+The Monkey\(aqs Audio Codec homepage: \fI\%http://www.monkeysaudio.com/\fP
+.\" Generated by docutils manpage writer.
+.
diff --git a/audio/mac/mac.SlackBuild b/audio/mac/mac.SlackBuild
index 969d3a9ba96d..8d9b5b11cbdc 100644
--- a/audio/mac/mac.SlackBuild
+++ b/audio/mac/mac.SlackBuild
@@ -10,6 +10,13 @@
 # licensed under the WTFPL. See http://www.wtfpl.net/txt/copying/
 # for details.
 
+# 20211125 bkw: BUILD=2
+# - add -DSHNTOOL to CXXFLAGS, which enables human-readable
+#   error messages (but not shn support).
+# - add README note about 'invalid input file' error.
+# - update README and slack-desc.
+# - add man page.
+
 # 20190107 bkw:
 # - download URL went away, use netbsd pkgsrc
 # - add FORCE_SLACK_CFLAGS option (probably nobody needs it)
@@ -26,7 +33,7 @@ cd $(dirname $0) ; CWD=$(pwd)
 
 PRGNAM=mac
 VERSION=${VERSION:-3.99_u4_b5_s7}
-BUILD=${BUILD:-1}
+BUILD=${BUILD:-2}
 TAG=${TAG:-_SBo}
 PKGTYPE=${PKGTYPE:-tgz}
 
@@ -38,9 +45,6 @@ if [ -z "$ARCH" ]; then
   esac
 fi
 
-# If the variable PRINT_PACKAGE_NAME is set, then this script will report what
-# the name of the created package would be, and then exit. This information
-# could be useful to other scripts.
 if [ ! -z "${PRINT_PACKAGE_NAME}" ]; then
   echo "$PRGNAM-$VERSION-$ARCH-$BUILD$TAG.$PKGTYPE"
   exit 0
@@ -85,11 +89,24 @@ find -L .  -perm /111 -a \! -perm 755 -a -exec chmod 755 {} \+ -o \
         \! -perm /111 -a \! -perm 644 -a -exec chmod 644 {} \+
 
 if [ "${FORCE_SLACK_CFLAGS:-no}" = "yes" ]; then
-   sed -i 's,-O3\>,,' configure
+  sed -i 's,-O3\>,,' configure
 fi
 
 patch -p1 < $CWD/gcc6.patch
 
+# This option isn't well explained... it turns on human-readable error
+# messages (without it, you get "Error: 1002", no idea WTF it means),
+# and the -q (quick verify) option. It does *not* make mac able to
+# read/write .shn files... I would never have known any of this from
+# reading the docs, had to read the source.
+SLKCFLAGS+=" -DSHNTOOL"
+
+# Clean up the usage output a little.
+sed -i -e 's,\[EXE\],mac,' \
+       -e 's,mac\.exe,mac,' \
+       -e 's,int filenames,filenames w/spaces,' \
+       src/Console/Console.cpp
+
 LDFLAGS="-Wl,-s" \
 CFLAGS="$SLKCFLAGS" \
 CXXFLAGS="$SLKCFLAGS" \
@@ -104,12 +121,17 @@ CXXFLAGS="$SLKCFLAGS" \
 make all
 make install DESTDIR=$PKG
 
-# pretty sure we don't need this:
+# We don't need this:
 rm -f $PKG/usr/lib$LIBDIRSUFFIX/*.la
 
-mkdir -p $PKG/usr/doc/$PRGNAM-$VERSION
-cp -a AUTHORS COPYING ChangeLog NEWS README TODO $PKG/usr/doc/$PRGNAM-$VERSION
-cat $CWD/$PRGNAM.SlackBuild > $PKG/usr/doc/$PRGNAM-$VERSION/$PRGNAM.SlackBuild
+# 20211125 bkw: man page by SlackBuild author. I got bored, sorry.
+mkdir -p $PKG/usr/man/man1
+gzip -9c < $CWD/$PRGNAM.1 > $PKG/usr/man/man1/$PRGNAM.1.gz
+
+PKGDOC=$PKG/usr/doc/$PRGNAM-$VERSION
+mkdir -p $PKGDOC
+cp -a AUTHORS src/License.htm ChangeLog* NEWS README TODO $PKGDOC
+cat $CWD/$PRGNAM.SlackBuild > $PKGDOC/$PRGNAM.SlackBuild
 
 mkdir -p $PKG/install
 cat $CWD/slack-desc > $PKG/install/slack-desc
diff --git a/audio/mac/mac.rst b/audio/mac/mac.rst
new file mode 100644
index 000000000000..7b664cf47771
--- /dev/null
+++ b/audio/mac/mac.rst
@@ -0,0 +1,145 @@
+.. RST source for mac(1) man page. Convert with:
+..   rst2man.py mac.rst > mac.1
+.. rst2man.py comes from the SBo development/docutils package.
+
+.. |version| replace:: 3.99_u4_b5_s7
+.. |date| date::
+
+===
+mac
+===
+
+----------------------------------------
+decode/encode Monkey's Audio codec files
+----------------------------------------
+
+:Manual section: 1
+:Manual group: SlackBuilds.org
+:Date: |date|
+:Version: |version|
+
+SYNOPSIS
+========
+
+**mac** [*input-file*] [*output-file*] [ [**-c** | **-n** ] *level* ]
+
+**mac** [*input-file*] [ **-d** | **-v** | **-q** ]
+
+DESCRIPTION
+===========
+
+Monkey's Audio (aka APE) is a lossless audio compression format,
+similar to FLAC. mac is a console frontend to Monkey's Audio, able to
+encode and decode APE audio files.
+
+If you encode a WAV file to APE, then decode it back to WAV, the
+audio in the decoded WAV file will be byte-for-byte identical to the
+original (although any extra data such as tags/comments in the RIFF
+header will not be preserved).
+
+OPTIONS
+=======
+
+Note: Only one of the options below can be given, and it must occur
+last on the command line (after the filename(s)). Spaces are not
+allowed between the **-c** or **-n** option and its *level* argument.
+
+**-c[level]**
+  Compress (encode). *input-file* must be a WAV file with 16-bit samples.
+  *output-file* will be an APE audio file. Higher *level*\s result
+  in better compression, at the expense of longer encoding time. The
+  supported levels are:
+
+    1000
+      *(fast)*, usually around 45%-50% compression ratio.
+    2000
+      *(normal)*, usually around 40%-45% compression ratio.
+    3000
+      *(high)*, only slightly better than 2000 (usually by 1% or so).
+    4000
+      *(very high)*, probably the point of diminishing returns.
+    5000
+      *(insane)*, takes around 3x as long as 4000, may not compress any better.
+
+**-n[level]**
+  Convert (recompress). As **-c**, but **input-file** must be an APE audio
+  file.
+
+**-d**
+  Decompress (decode). *input-file* must be an APE audio file.
+  *output-file* will be a WAV file.
+
+**-v**
+  Verify. *input-file* must be an APE audio file. It will be decoded, and
+  any errors will be displayed, but the decoded audio won't be saved.
+
+**-q**
+  Quick verify. Just checks that *input-file* has a valid APE header.
+
+**--help**
+  Show built-in usage message (same as running **mac** with no arguments).
+
+EXAMPLES
+========
+
+Compress
+  mac "Metallica - One.wav" "Metallica - One.ape" -c2000
+
+Decompress
+  mac "Metallica - One.ape" "Metallica - One.wav" -d
+
+Verify
+  mac "Metallica - One.ape" -v
+
+Quick verify
+  mac "Metallica - One.ape" -q
+
+Note that filenames with spaces and punctuation should be put inside
+quote, as usual.
+
+NOTES
+=====
+
+**mac** can only handle WAV files with 8- or 16-bit samples, not
+e.g. 24-bit or floating point. If needed, you can convert to 16-bit
+with a command like:
+
+  $ sox -G input.wav -b16 output.wav
+
+WAV files must have 1 or 2 channels (mono or stereo;
+quad/surround/5.1/etc are not supported). Any sampling rate is
+supported.
+
+**ffmpeg**\(1) can decode and convert APE files, though it cannot encode
+to APE.
+
+**mplayer**\(1) and **audacious**\(1) can play APE files.
+
+**file**\(1) knows about APE files. Example:
+
+  $ file test.ape
+
+  test.ape: Monkey's Audio compressed format version 3990 with normal compression, stereo, sample rate 48000
+
+COPYRIGHT
+=========
+
+See the file /usr/doc/mac-|version|/License.htm for license information.
+
+AUTHORS
+=======
+
+The original Monkey's Audio Codec was written by Matthew
+T. Ashland. It was ported to Linux by Frank Klemm and SuperMMX, then
+enhanced and bugfixed by Jason Jordan.
+
+This man page written for the SlackBuilds.org project
+by B. Watson, and is licensed under the WTFPL.
+
+SEE ALSO
+========
+
+**ffmpeg**\(1), **mplayer**\(1), **audacious**\(1), **flac**\(1), **shorten**\(1), **sox**\(1)
+
+The Monkey's Audio Codec homepage: http://www.monkeysaudio.com/
+
diff --git a/audio/mac/slack-desc b/audio/mac/slack-desc
index af6506062ff7..cecbf1546d0a 100644
--- a/audio/mac/slack-desc
+++ b/audio/mac/slack-desc
@@ -8,9 +8,9 @@
    |-----handy-ruler------------------------------------------------------|
 mac: mac (Monkey's Audio Linux port)
 mac:
-mac: mac is a console frontend to Monkey's Audio, able to encode and
-mac: decode ape audio files.
-mac:
+mac: Monkey's Audio (aka APE) is a lossless audio compression format,
+mac: similar to FLAC. mac is a console frontend to Monkey's Audio, able to
+mac: encode and decode APE audio files.
 mac:
 mac:
 mac: