From a043e74e14256ef504b0fcd4a53f829bd1b953a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Mangano-Tarumi?= Date: Wed, 21 Nov 2018 21:40:08 -0500 Subject: [PATCH] review the user doc --- CHANGELOG.md | 10 +++--- CONTRIBUTING.md | 25 ++++++++------ README.md | 6 ++-- opustags.1 | 86 +++++++++++++++++++++---------------------------- 4 files changed, 61 insertions(+), 66 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8e0648a..b1f10fc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,11 +4,13 @@ opustags changelog 1.2.0 - TBA ----------- -This is the biggest release for opustags. The whole code base was reviewed for robustness and -clarity. It doesn't offer new features, but fixes a few bugs and improves error reporting. +- Preserve extra data in OpusTags past the comments. +- Improve error reporting. +- Fix various bugs. -The program is now built as C++14, and the code refactored without sacrificing the original -simplicity. It is shipped with a new test suite for preventing regressions. +This is the biggest release for opustags. The whole code base was reviewed for robustness and +clarity. The program is now built as C++14, and the code refactored without sacrificing the +original simplicity. It is shipped with a new test suite for preventing regressions. 1.1.1 - 2018-10-24 ------------------ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0cdc358..8d324c8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing to opustags -opustags is not quite active nor mature, but contributions are welcome. +opustags is slowing getting more mature, and contributions are welcome. Before you open a pull request, you might want to talk about the change you'd like to make to make sure it's relevant. In that case, feel free to open an @@ -41,12 +41,19 @@ questioned, and it was thus abandoned for a few years. Judging by the inquiries and contributions, albeit few, on GitHub, it looks like it remains relevant, so let's dust it off a bit. -The current low-expectation plan to improve this project comprises the -following directions, in whatever order: +Today, opustags is written in C++14 and features a unit test suite in C++, and +an integration test suite in Perl. The code was refactored, organized into +modules, and reviewed for safety. -- Write a complete test suite in Perl, calling opustags as a subprocess. -- Build opustags in C++14. The code will remain mostly C. -- Build the project with CMake, or maybe autotools. -- Refactor the code to improve the readability. -- Integrate code from the `next` branch. -- Fuzz it. Memcheck it. +The next release will focus on correctness, with the following technical +objectives: + +1. Validate the comments: field name in ASCII and value in UTF-8. +2. Allow selecting the stream to edit, instead of assuming the Ogg contains only + one Opus stream. +3. Provide an --escape option for escaping the newlines inside comment strings. +4. Take into account the system's encoding: the tags must always be stored as + UTF-8, and converted from and to the console encoding when reading input or + printing. +5. Maybe provide a --binary option to dump the raw OpusTags packet, that can be + combined to --set-all to read it back. diff --git a/README.md b/README.md index fb37aee..bab19d9 100644 --- a/README.md +++ b/README.md @@ -3,10 +3,8 @@ opustags View and edit Opus comments. -The current code quality of this project is in a sorry state, but that might -change in the near future. It is expected to work well though, so please do -open an issue if something doesn't work. New contributions are welcome but make -sure you read CONTRIBUTING.md first. +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. Until opustags becomes top-quality software, if it ever does, you might want to check out these more mature tag editors: diff --git a/opustags.1 b/opustags.1 index a4fddd7..dd5db30 100644 --- a/opustags.1 +++ b/opustags.1 @@ -1,4 +1,4 @@ -.TH opustags 1 "January 2013" +.TH opustags 1 "November 2018" "@PROJECT_NAME@ @PROJECT_VERSION" .SH NAME opustags \- Opus comment editor .SH SYNOPSIS @@ -15,34 +15,28 @@ opustags \- Opus comment editor .SH DESCRIPTION .PP \fBopustags\fP can read and edit the comment header of an Opus file. -It basically has two modes: read-only and read-write (for tag edition). +It basically has two modes: read-only, and read-write for tag edition. .PP In read-only mode, only the beginning of \fIINPUT\fP is read, and the tags are -printed on \fBstdout\fP. -\fIINPUT\fP can either be the name of a file or \fB-\fP to read from \fBstdin\fP. +printed on standard output. +\fIINPUT\fP can either be the name of a file or \fB-\fP to read from standard input. You can use the options below to edit the tags before printing them. This could be useful to preview some changes before writing them. .PP -As for the edition mode, you need to specify an output file (or \fB-\fP for -\fBstdout\fP). It must be different from the input file. -You may want to use \fB--overwrite\fP if you know what you’re doing. -To overwrite the input file, use \fB--in-place\fP. +In edition mode, you need to specify an output file (or \fB-\fP for standard output). It must be +different from the input file. To overwrite the input file, use \fB--in-place\fP. .PP -Tag edition can be made with the \fB--add\fP, \fB--delete\fP and \fB--set\fP -options. They can be written in any order and don’t conflict with each other. -However, they aren’t executed in any order: first the specified tags are -deleted, then the new tags are added. “Set” operations are mere convenience -for delete/add. +Tag edition can be performed with the \fB--add\fP, \fB--delete\fP and \fB--set\fP +options. Options can be specified in any order and don’t conflict with each other. +First the specified tags are deleted, then the new tags are added. .PP -You can delete all the tags with \fB--delete-all\fP. This operation can be -combined with \fB--add\fP to set new tags without being bothered by the old -ones. Another way to do this is to use \fB--set-all\fP as explained below. +You can delete all the tags with \fB--delete-all\fP. This operation can be combined with \fB--add\fP +to set new tags without being bothered by the old ones. .PP -If you want to process tags yourself, you can use the \fB--set-all\fP option -which will cause \fBopustags\fP to read tags from \fBstdin\fP. -The format is the same as the one used for output; that is to say, -newline-separated \fIFIELD=Value\fP assignment. Note that this implies -\fB--delete-all\fP. +If you want to replace all the tags, you can use the \fB--set-all\fP option which will cause +\fBopustags\fP to read tags from standard input. +The format is the same as the one used for output: newline-separated \fIFIELD=Value\fP assignment. +All the previously existing tags as deleted. .PP \fBWarning:\fP the Opus format specifications requires tags to be encoded in \fBUTF-8\fP. This tool ignores the system locale, assuming the encoding is @@ -53,34 +47,30 @@ set to UTF-8, and assume that tags are already encoded in UTF-8. Display a brief description of the options. .TP .B \-o, \-\-output \fIFILE\fI -Edition mode. The input file will be read, its tags edited, then written to the -specified output file. If \fIFILE\fP is \fB-\fP then the resulting Opus file -will be written to \fBstdout\fP. As the input file is read incrementally, the -output file can’t be the same as the input file. +Specify the output file. +The input file will be read, its tags edited, then written to the specified output file. If +\fIFILE\fP is \fB-\fP then the resulting Opus file will be written to standard output. +The output file can’t be the same as the input file. .TP .B \-i, \-\-in-place \fR[\fP\fISUFFIX\fP\fR]\fP -Use this when you want to modify the input file in-place. This creates a -temporary file with the specified suffix (.otmp by default). This implies -\fB--overwrite\fP in that if a file with the same temporary name already -exists, it will be overwritten without warning. Of course, this overwrites -the input file too. You cannot use this option when the input file is actually -\fBstdin\fP. +Use this when you want to modify the input file in-place. opustags will create a temporary output +file with the specified suffix (.otmp by default), and move it to the location of the input file on +success. If a file with the same name as the temporary file already exists, it will be overwritten +without warning. +This option conflicts with \fB--output\fP. .TP .B \-y, \-\-overwrite By default, \fBopustags\fP refuses to overwrite an already existent file. Use -this option to allow that. Note that this doesn’t allow in-place edition, the -output file needs to be different from the input file. +this option to allow that. .TP .B \-d, \-\-delete \fIFIELD\fP -Delete all the tags whose field name is \fIFIELD\fP (they may be several, though -usually there is only one of each type). You can use this option as many times -as you want. +Delete all the tags whose field name is \fIFIELD\fP. They may be several one of them, though usually +there is only one of each type. .TP .B \-a, \-\-add \fIFIELD=VALUE\fP -Add a tag. It doesn’t matter if a tag of the same type already exist (think -the case where there are several artists). You can use this option as many -times as needed, with the same field names or not. When the \fB--delete\fP -is used with the same \fIFIELD\fP, only the older tags are deleted. +Add a tag. Note that multiple tags with the same field name are perfectly acceptable, so you can add +multiple fields with the same name, and previously existing tags will also be preserved. +When the \fB--delete\fP is used with the same \fIFIELD\fP, only the older tags are deleted. .TP .B \-s, \-\-set \fIFIELD=VALUE\fP This option is provided for convenience. It delete all the fields of the same @@ -91,18 +81,16 @@ type. As deletion occurs before adding, \fB--set\fP won’t erase the tags added with \fB--add\fP. .TP .B \-D, \-\-delete-all -Delete all the tags before adding any. When this option is specified, the -\fB--delete\fP options are ignored. Tags then can be added using \fB--add\fP -or \fB--set\fP, which, in that case, are equivalent. +Delete all the previously existing tags. .TP .B \-S, \-\-set-all -Sets the tags from scratch. All the original tags are deleted and new ones are -read from \fBstdin\fP. Each line must specify a \fIFIELD=VALUE\fP pair and be -LF-terminated (except for the last line). 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. +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. .SH SEE ALSO .BR vorbiscomment (1), .BR sed (1) .SH AUTHOR -Frédéric Mangano +Frédéric Mangano-Tarumi