From 04532802fd0eb0b075d3e82ff4c2249bfa711242 Mon Sep 17 00:00:00 2001 From: Martijn van Beurden Date: Thu, 2 May 2024 15:54:54 +0200 Subject: [PATCH] Escape double dashes, so they don't get converted to em dashes (#698) Fixes https://github.com/xiph/flac/issues/671 --- man/flac.md | 15 +++++++++------ man/metaflac.md | 20 ++++++++++---------- 2 files changed, 19 insertions(+), 16 deletions(-) diff --git a/man/flac.md b/man/flac.md index f303b546..0d66a151 100644 --- a/man/flac.md +++ b/man/flac.md @@ -42,7 +42,7 @@ the convention is that FLAC files have the extension ".flac" Before going into the full command-line description, a few other things help to sort it out: 1. flac encodes by default, so you must use -d to decode -2. the options -0 .. -8 (or --fast and --best) that control the +2. the options -0 .. -8 (or \--fast and \--best) that control the compression level actually are just synonyms for different groups of specific encoding options (described later) and you can get the same effect by using the same options. When specific options are specified @@ -66,7 +66,7 @@ the desired operation on each input file to similarly named output files (meaning for encoding, the extension will be replaced with ".flac", or appended with ".flac" if the input file has no extension, and for decoding, the extension will be ".wav" for WAVE output and ".raw" for raw -output). The original file is not deleted unless --delete-input-file is +output). The original file is not deleted unless \--delete-input-file is specified. If you are encoding/decoding from stdin to a file, you should use the -o @@ -85,7 +85,7 @@ RIFF WAVE header contents when necessary. Also, you can force output data to go to stdout using -c. -To encode or decode files that start with a dash, use -- to signal the +To encode or decode files that start with a dash, use \-- to signal the end of options, to keep the filenames themselves from being treated as options: @@ -154,7 +154,7 @@ Some common **encoding** tasks using flac: `flac abc.flac --force` : This one's a little tricky: notice that flac is in encode mode by default (you have to specify -d to decode) so this command actually - recompresses abc.flac back to abc.flac. --force is needed to make + recompresses abc.flac back to abc.flac. \--force is needed to make sure you really want to overwrite abc.flac with a new version. Why would you want to do this? It allows you to recompress an existing FLAC file with (usually) higher compression options or a newer @@ -167,16 +167,19 @@ Some common **decoding** tasks using flac: -d it means re-encode abc.flac to abc.flac (see above). `flac -d --force-aiff-format abc.flac` + `flac -d -o abc.aiff abc.flac` : Two different ways of decoding abc.flac to abc.aiff (AIFF format). abc.flac is not deleted. `flac -d --force-rf64-format abc.flac` + `flac -d -o abc.rf64 abc.flac` : Two different ways of decoding abc.flac to abc.rf64 (RF64 format). abc.flac is not deleted. `flac -d --force-wave64-format abc.flac` + `flac -d -o abc.w64 abc.flac` : Two different ways of decoding abc.flac to abc.w64 (Wave64 format). abc.flac is not deleted. @@ -559,14 +562,14 @@ the HTML documentation. ends with *.aif* or *.aiff*, *.rf64* and *.w64* respectively. Also, this option has no effect when encoding since input is auto-detected. When none of these options nor - --keep-foreign-metadata are given and no output filename is set, + \--keep-foreign-metadata are given and no output filename is set, the output format is WAV by default. **\--force-legacy-wave-format** **\--force-extensible-wave-format** : Instruct the decoder to output a WAVE file with WAVE_FORMAT_PCM and WAVE_FORMAT_EXTENSIBLE respectively. If none of these options nor - --keep-foreign-metadata are given, FLAC outputs WAVE_FORMAT_PCM + \--keep-foreign-metadata are given, FLAC outputs WAVE_FORMAT_PCM for mono or stereo with a bit depth of 8 or 16 bits, and WAVE_FORMAT_EXTENSIBLE for all other audio formats. diff --git a/man/metaflac.md b/man/metaflac.md index 8c049d74..0d5959ed 100644 --- a/man/metaflac.md +++ b/man/metaflac.md @@ -30,7 +30,7 @@ set of FLAC files to operate on. There are three kinds of "options": - Shorthand operations, which are convenient synonyms for major operations. For example, there is a shorthand operation - --show-sample-rate that shows just the sample rate field from the + \--show-sample-rate that shows just the sample rate field from the STREAMINFO metadata block. - Global options, which affect all the operations. @@ -45,7 +45,7 @@ files: `metaflac --show-md5sum file1.flac file2.flac file3.flac` Another example; this removes all DESCRIPTION and COMMENT tags in a set -of FLAC files, and uses the --preserve-modtime global option to keep the +of FLAC files, and uses the \--preserve-modtime global option to keep the FLAC file modification times the same (usually when files are edited the modification time is set to the current time): @@ -59,7 +59,7 @@ modification time is set to the current time): **\--with-filename** : Prefix each output line with the FLAC file name (the default if more than one FLAC file is specified). This option has no effect for - options exporting to a file, like --export-tags-to. + options exporting to a file, like \--export-tags-to. **\--no-filename** : Do not prefix each output line with the FLAC file name (the default @@ -111,7 +111,7 @@ modification time is set to the current time): : Show all tags where the field name matches 'name'. **\--show-all-tags** -: Show all tags. This is an alias for --export-tags-to=-. +: Show all tags. This is an alias for \--export-tags-to=-. **\--remove-tag=name** : Remove all tags whose field name is 'name'. @@ -263,19 +263,19 @@ modification time is set to the current time): \--application-data-format=hexdump. **\--data-format=binary\|binary-headerless\|text** -: For use with --list. By default a human-readable text +: For use with \--list. By default a human-readable text representation of the data is isplayed. You may specify - --data-format=binary to dump the raw binary form of each metadata - block. Specify --data-format=binary-headerless to omit output of + \--data-format=binary to dump the raw binary form of each metadata + block. Specify \--data-format=binary-headerless to omit output of metadata block headers, including the id of APPLICATION metadata blocks. **\--append** : Insert a metadata block from a file. This must be a binary block as - exported with --list --data-format=binary. The insertion point is - defined with --block-number=#. The new block will be added after the + exported with \--list \--data-format=binary. The insertion point is + defined with \--block-number=#. The new block will be added after the given block number. This prevents the illegal insertion of a block - before the first STREAMINFO block. You may not --append another + before the first STREAMINFO block. You may not \--append another STREAMINFO block. It is possible to copy a metadata block from one file to another with this option. For example use `metaflac --list --data-format=binary --block-number=6 file.flac > block`