prepare 1.3.0

CHANGELOG.md

@@ -1,6 +1,17 @@
 opustags changelog
 ==================
 
+1.3.0 - TBA
+-----------
+
+- Support for non-Unicode systems. Tags are automatically converted to and from the system locale.
+- It is now possible to delete specific NAME=VALUE pairs.
+- Option `--set-all` is now stricter and aborts with an error if the input is not valid.
+- Printing tags will display a warning if the tags contain control characters.
+
+opustags is now more aware of its limitations, and will print more helpful error messages when
+trying to edit an unsupported file. It is also more cautious against corrupted streams.
+
 1.2.0 - 2018-11-25
 ------------------
 

CMakeLists.txt

@@ -2,7 +2,7 @@ cmake_minimum_required(VERSION 3.9)
 
 project(
 	opustags
-	VERSION 1.2.0
+	VERSION 1.3.0
 	LANGUAGES CXX
 )
 

README.md

@@ -1,33 +1,32 @@
 opustags
 ========
 
-View and edit Opus comments.
+View and edit Ogg Opus comments.
 
-The current code quality of this project is getting better, and is suitable for reliably editing any
-Opus file provided it does not contain other multiplexed streams. Only UTF-8 is currently supported.
+opustags is designed to be fast and as conservative as possible, to the point that if you edit tags
+then edit them again to their previous values, you should get a bit-perfect copy of the original
+file. No under-the-cover operation like writing "edited with opustags" or timestamp tagging will
+ever be performed.
 
-Until opustags becomes top-quality software, if it ever does, you might want to
-check out these more mature tag editors:
+It currently has the following limitations:
 
-- [EasyTAG](https://wiki.gnome.org/Apps/EasyTAG)
-- [Beets](http://beets.io/)
-- [Picard](https://picard.musicbrainz.org/)
-- [puddletag](http://docs.puddletag.net/)
-- [Quod Libet](https://quodlibet.readthedocs.io/en/latest/)
-- [Goggles Music Manager](https://gogglesmm.github.io/)
+- The total size of all tags cannot exceed 64 kB, the maximum size of one Ogg page.
+- Multiplexed streams are not supported.
+- Newlines inside tags are not supported by `--set-all`.
 
-See also these libraries if you need a lower-level access:
-
-- [TagLib](http://taglib.org/)
-- [mutagen](https://mutagen.readthedocs.io/en/latest/)
+If you'd like one of these limitations lifted, please do open an issue explaining your use case.
+Feel free to ask for new features too.
 
 Requirements
 ------------
 
-* a C++14 compiler,
-* CMake,
 * a POSIX-compliant system,
-* libogg.
+* a C++14 compiler,
+* CMake ≥ 3.9,
+* libogg 1.3.3.
+
+The version numbers are indicative, and it's very likely opustags will build and work fine with
+other versions too, as CMake and libogg are quite mature.
 
 Installing
 ----------

opustags.1

@@ -67,9 +67,10 @@ By default, \fBopustags\fP refuses to overwrite an already-existent file.
 Use \fB-y\fP to allow overwriting.
 Note that this option is not needed when the output is a special file like \fI/dev/null\fP.
 .TP
-.B \-d, \-\-delete \fIFIELD\fP
-Delete all the tags whose field name is \fIFIELD\fP. The field names are case-insensitive, and
-expected to be ASCII.
+.B \-d, \-\-delete \fIFIELD[=VALUE]\fP
+If value is not specified, delete all the tags whose field name is \fIFIELD\fP.
+Otherwise, delete all the comments whose field name is \fIFIELD\fP and value is \fIVALUE\fP.
+In both cases, the field names are case-insensitive, and expected to be ASCII.
 .TP
 .B \-a, \-\-add \fIFIELD=VALUE\fP
 Add a tag. Note that multiple tags with the same field name are perfectly acceptable, so you can add
@@ -91,8 +92,7 @@ Delete all the previously existing tags.
 Sets the tags from scratch.
 All the original tags are deleted and new ones are read from standard input.
 Each line must specify a \fIFIELD=VALUE\fP pair and be separated with line feeds.
-Invalid lines are skipped and cause a warning to be issued. Blank lines are ignored.
-This mode could be useful for batch processing tags through an utility like \fBsed\fP.
+Blank lines are ignored.
 .SH EXAMPLES
 .PP
 List all the tags in file foo.opus:
@@ -111,10 +111,25 @@ Remove the previously existing ARTIST tags and add the two X and Y ARTIST tags,
 tags without writing them to the Opus file:
 .PP
 	opustags in.opus --add ARTIST=X --add ARTIST=Y --delete ARTIST
-.SH SEE ALSO
-.BR vorbiscomment (1),
-.BR sed (1)
+.SH CAVEATS
+.PP
+\fBopustags\fP currently has the following limitations:
+.IP \[bu]
+The total size of all tags cannot exceed 64 kB, the maximum size of one Ogg page.
+.IP \[bu]
+Multiplexed streams are not supported.
+.IP \[bu]
+Newlines inside tags are not supported by `--set-all`.
+.IP \[bu]
+Newlines and control characters are not escaped when printing tags.
+.PP
+Internally, the OpusTags packet in an Ogg Opus file may contain extra arbitrary binary data after
+the comments.  This block of data is currently not editable, but is always preserved. The same
+applies for the vendor string.
+.PP
+If you need a feature not currently supported, feel free to open an issue or send an email with your
+use case.
 .SH AUTHOR
-Frédéric Mangano-Tarumi <fmang@mg0.fr>
+Frédéric Mangano-Tarumi <fmang+opustags@mg0.fr>
 .PP
 Report bugs at <https://github.com/fmang/opustags/issues>