commented awk programs, removed dangling ws

2025-09-11 22:19:30 +02:00
parent c1f8066688
commit 79df83d1b1
5 changed files with 187 additions and 4 deletions
--- a/src/awk/artists.awk
+++ b/src/awk/artists.awk
@@ -1,3 +1,30 @@
+# List artists
+#
+# parameter file_local_artists:    This is an optional parameter with the path
+#                                  to a file with a MusicBrainz artist ID per
+#                                  line.
+# parameter format_person:         This is the format string for single person
+#                                  artists, which includes the <<name>>
+#                                  placeholder.
+# parameter format_disambiguation: This is the format string for the
+#                                  disambiguation part of the artist, with a
+#                                  placeholder <<disambiguation>>.
+# parameter format_group:          This is as format_person, but for music
+#                                  groups.
+# parameter format_local:          String to indicate that there is some music
+#                                  locally available of an artist
+#
+# This awk program takes as input a sequence of lines where the first item is
+# the MusicBrainz artist ID, the second item is the type of the artist
+# ("Person" or "Group"), the third item is the name, and the forth item is a
+# disambiguation string.
+#
+# The output of this script is a sequence of tab-delimited lines where the
+# first item is the format_local string, if some music of that artist is
+# locally accessible, and the empty string otherwise, the second item is the
+# formatted artist string (formatted according to format_person or
+# format_group), the third item is the constant string "0" indicating the
+# parent MusicBrainz ID, and the last item is the MusicBrainz artist ID.
 BEGIN {
  OFS="\t"
  local_artists[0] = 0
--- a/src/awk/recordings.awk
+++ b/src/awk/recordings.awk
@@ -1,3 +1,39 @@
+# List recordings
+#
+# parameter file_local_recordings: This is an optional parameter with the path
+#                                  to a file with a MusicBrainz recording ID
+#                                  per line.
+# parameter format:                The format of a recording line including the
+#                                  placeholders <<med>> for medium number,
+#                                  <<nr> for for track number within a medium,
+#                                  <<title>> for the title, <<artist>> for the
+#                                  artist string, and <<duration>> for the
+#                                  track duration.
+# parameter format_local:          String to indicate that the track is locally
+#                                  available
+# parameter format_current:        String to indicate that the track is
+#                                  "currently playing"
+# parameter current_id:            MusicBrainz track ID of a track to be marked
+#                                  as "currently playing"
+#
+# The input to this awk program is a sequence of lines containing the following fields:
+# Field 1: The MusicBrainz ID of the release this track belongs to
+# Field 2: MusicBrainz ID of this track
+# Field 3: Medium number of this track within the release
+# Field 4: Track number of this track within the medium
+# Field 5: Duration of this track in miliseconds
+# Field 6: Title of this track
+# Field 7: Artist of this track
+# Field 8: Path to decoratoin file of this release
+#
+# The output is a sequence of tab-delimited lines containing the following fields:
+# Field 1: Sort value (to sort the track within the release)
+# Field 2: The string `format_local` if the track is locally available
+# Field 3: The string `format_current` if the track has MusicBrainz ID `current_id`
+# Field 4: The track line to be displayed according to `format`
+# Field 5: The MusicBrainz ID of the release this track belongs to
+# Field 6: The MusicBrainz ID of this track ":" separated from the path to the
+#          decoration file of this release
 BEGIN {
  OFS="\t"
  local_recordings[0] = 0
--- a/src/awk/releasegroups.awk
+++ b/src/awk/releasegroups.awk
@@ -1,3 +1,69 @@
+# List release groups
+#
+# parameter file_local_releasegroups: This is an optional parameter with the
+#                                     path to a file with a MusicBrainz
+#                                     release-group ID per line.
+# parameter format_release:           Format for the release title with a
+#                                     <<title>> placeholder.
+# parameter format_release_w_artist:  Same as `format_release` but with an
+#                                     additional <<artist>> placeholder.
+# parameter format_year:              Format string for the year part, with a
+#                                     <<year>> placeholder.
+# parameter format_local:             String to indicate that the track is
+#                                     locally available.
+# parameter artist:                   Artist name to compare release-groups
+#                                     artist names against. If the names
+#                                     differ, then the format with <<artist>>
+#                                     placeholder is used (optional)
+# parameter artistid                  MusicBrainz ID of the artist (optional).
+# Then, there are several format strings that indicate the type of a release
+# group. The types are implicit from the parameter names:
+# parameter format_album
+# parameter format_single
+# parameter format_ep
+# parameter format_broadcast
+# parameter format_other
+# Some release groups have also a secondary type. The presence of a secondary
+# type is formatted using
+# parameter format_secondary.
+# The list of all secondary types (implicit from their variable names) are
+# formatted using
+# parameter format_secondary.
+# Each of the secondary types is specified with (the type is implicit from the
+# variable names)
+# parameter format_compilation
+# parameter format_soundtrack
+# parameter format_spokenword
+# parameter format_interview
+# parameter format_audiobook
+# parameter format_audiodrama
+# parameter format_live
+# parameter format_remix
+# parameter format_djmix
+# parameter format_mixtape
+# parameter format_demo
+# parameter format_fieldrec
+#
+# The input to this awk program is a sequence of lines containing the following
+# fields:
+# Field 1: The MusicBrainz ID of the release group
+# Field 2: The primary type
+# Field 3: A ;-delimited string of secondary types
+# Field 4: The original release year
+# Field 5: Title of the release group
+# Field 6: The artist as credited
+#
+# The output is a sequence of tab-delimited lines with the fields:
+# Field 1: Sort value to sort release groups
+# Field 2: The flag `format_local` if the release group is accessible locally,
+#          and "" else.
+# Field 3: Release-group type
+# Field 4: Release-group string
+# Field 5: Release-group year
+# Field 6: Secondary types
+# Field 7: MusicBrainz artist ID of the release group artist, if there is one,
+#          else "0"
+# Field 8: MusicBrainz release-group ID
 BEGIN {
  OFS="\t"
  local_releasegroups[0] = 0
@@ -9,9 +75,9 @@ BEGIN {
  }
 }
 {
-  line_type=""
-  line_sectype=""
-  line_year=""
+  line_type = ""
+  line_sectype = ""
+  line_year = ""
  gsub("&", "\\\\&")
  id = $1
  type = $2
--- a/src/awk/releases.awk
+++ b/src/awk/releases.awk
@@ -1,3 +1,57 @@
+# List releases
+#
+# parameter file_local_releases:         This is an optional parameter with the
+#                                        path to a file with a MusicBrainz
+#                                        release ID per line.
+# parameter release_format:              Format for the release with the
+#                                        placeholders <<status>>, <<tracks>>,
+#                                        <<media>>, <<year>>, <<country>>, and
+#                                        <<label>>.
+# parameter release_format_title_artist: Format to specify title and artist,
+#                                        with the placeholders <<title>> and
+#                                        <<artist>>.
+# parameter release_format_title:        Format to specify the release title
+#                                        with a placeholder <<title>>.
+# parameter release_format_artist:       Format to specify the release artist
+#                                        with a placeholder <<artist>>.
+# parameter format_local:                String to indicate that the track is
+#                                        locally available.
+# parameter rg_artist:                   Artist name of release group
+#                                        (optional)
+# parameter rg_title:                    Title of release group (optional)
+# parameter rgid:                        MusicBrainz release-group ID
+#                                        (optional)
+# Then, there are several format strings that indicate the status of a release.
+# The status are implicit from the parameter names:
+# parameter release_official
+# parameter release_promotion
+# parameter release_bootleg
+# parameter release_pseudo
+# parameter release_withdrawn
+# parameter release_expunged
+# parameter release_cancelled
+#
+# The input to this awk program is a sequence of lines containing the following
+# fields:
+# Field  1: MusicBrainz ID of the release
+# Field  2: Release status
+# Field  3: Release date
+# Field  4: Number of cover-art images
+# Field  5: Label string (', '-delimited)
+# Field  6: Total number of tracks
+# Field  7: Format (', '-delimited)
+# Field  8: Release country
+# Field  9: Release title
+# Field 10: Artist as credited
+#
+# The output is a sequence of tab-delimited lines with the fields:
+# Field 1: Sort value to sort release groups
+# Field 2: The flag `format_local` if the release is accessible locally, and ""
+#          else.
+# Field 3: Release line
+# Field 4: MusicBrainz release-group ID if present, else "0"
+# Field 5: MusicBrainz release ID followed by ":" and then a path to the
+#          decoration file (if it exists)
 BEGIN {
  OFS="\t"
  local_releases[0] = 0