Merge branch 'wader_master' into postgres

2024-12-27 15:42:07 +03:00 · 2022-09-16 17:18:30 +03:00 · 2022-09-16 17:18:30 +03:00 · f122f72373
commit f122f72373
parent d7bcca0a4a ee7b9f4186
76 changed files with 2293 additions and 937 deletions
--- a/.gitattributes
+++ b/.gitattributes
@ -3,3 +3,4 @@
 *.json eol=lf
 *.jq eol=lf
 *.xml eol=lf
+*.md eol=lf
--- a/README.md
+++ b/README.md
@ -48,7 +48,7 @@ avc_sps,
 [avro_ocf](doc/formats.md#avro_ocf),
 [bencode](doc/formats.md#bencode),
 bitcoin_blkdat,
-bitcoin_block,
+[bitcoin_block](doc/formats.md#bitcoin_block),
 bitcoin_script,
 bitcoin_transaction,
 bsd_loopback_frame,
@ -91,6 +91,7 @@ json,
 jsonl,
 [macho](doc/formats.md#macho),
 macho_fat,
+markdown,
 [matroska](doc/formats.md#matroska),
 [mp3](doc/formats.md#mp3),
 mp3_frame,
@ -127,7 +128,7 @@ vp8_frame,
 vp9_cfm,
 vp9_frame,
 vpx_ccr,
-wasm,
+[wasm](doc/formats.md#wasm),
 wav,
 webp,
 xing,
--- a/doc/formats.jq
+++ b/doc/formats.jq
@ -2,14 +2,13 @@

 def code: "`\(.)`";
 def nbsp: gsub(" "; "&nbsp;");
-def has_section($f; $fhelp): $fhelp.notes or $fhelp.examples or $fhelp.links or $f.decode_in_arg;
+def has_section($f; $fhelp): $fhelp.notes or $fhelp.examples or $f.decode_in_arg or ((_registry.files[][] | select(.name=="\($f.name).md").data) // false);

 def formats_list:
-  [ formats
-  | to_entries[] as {$key, $value}
-  | (_format_func($key; "_help")? // {}) as $fhelp
-  | if has_section($value; $fhelp) then "[\($key)](doc/formats.md#\($key))"
-    else $key
+  [ formats[] as $f
+  | ({} | _help_format_enrich("fq"; $f; false)) as $fhelp
+  | if has_section($f; $fhelp) then "[\($f.name)](doc/formats.md#\($f.name))"
+    else $f.name
    end
  ] | join(",\n");

@ -71,13 +70,14 @@ def formats_table:

 def formats_sections:
  ( formats[] as $f
-  | (_format_func($f.name; "_help")? // {} | _help_format_enrich("fq"; $f; false)) as $fhelp
+  | ((_registry.files[][] | select(.name=="\($f.name).md").data) // false) as $doc
+  | ({} | _help_format_enrich("fq"; $f; false)) as $fhelp
  | select(has_section($f; $fhelp))
-  | "### \($f.name)"
+  | "## \($f.name)"
  , ""
  , ($fhelp.notes | if . then ., "" else empty end)
  , if $f.decode_in_arg then
-      ( "#### Options"
+      ( "### Options"
      , ""
      , ( [ { name: "Name"
            , default: "Default"
@ -113,7 +113,7 @@ def formats_sections:
    else empty
    end
  , if $fhelp.examples then
-      ( "#### Examples"
+      ( "### Examples"
      , ""
      , ( $fhelp.examples[]
        | "\(.comment)"
@ -134,16 +134,5 @@ def formats_sections:
    )
    else empty
    end
-  , if $fhelp.links then
-      ( "#### References and links"
-      , ""
-      , ( $fhelp.links[]
-        | if .title then "- [\(.title)](\(.url))"
-          else "- \(.url)"
-          end
-        )
-      , ""
-      )
-    else empty
-    end
+  , ($doc // empty)
  );
--- a/doc/formats.md
+++ b/doc/formats.md
@ -2,121 +2,122 @@

 [fq -rn -L . 'include "formats"; formats_table']: sh-start

-|Name                        |Description                                                                              |Dependencies|
-|-                           |-                                                                                        |-|
-|[`aac_frame`](#aac_frame)   |Advanced&nbsp;Audio&nbsp;Coding&nbsp;frame                                               |<sub></sub>|
-|`adts`                      |Audio&nbsp;Data&nbsp;Transport&nbsp;Stream                                               |<sub>`adts_frame`</sub>|
-|`adts_frame`                |Audio&nbsp;Data&nbsp;Transport&nbsp;Stream&nbsp;frame                                    |<sub>`aac_frame`</sub>|
-|`amf0`                      |Action&nbsp;Message&nbsp;Format&nbsp;0                                                   |<sub></sub>|
-|`apev2`                     |APEv2&nbsp;metadata&nbsp;tag                                                             |<sub>`image`</sub>|
-|`ar`                        |Unix&nbsp;archive                                                                        |<sub>`probe`</sub>|
-|[`asn1_ber`](#asn1_ber)     |ASN1&nbsp;BER&nbsp;(basic&nbsp;encoding&nbsp;rules,&nbsp;also&nbsp;CER&nbsp;and&nbsp;DER)|<sub></sub>|
-|`av1_ccr`                   |AV1&nbsp;Codec&nbsp;Configuration&nbsp;Record                                            |<sub></sub>|
-|`av1_frame`                 |AV1&nbsp;frame                                                                           |<sub>`av1_obu`</sub>|
-|`av1_obu`                   |AV1&nbsp;Open&nbsp;Bitstream&nbsp;Unit                                                   |<sub></sub>|
-|`avc_annexb`                |H.264/AVC&nbsp;Annex&nbsp;B                                                              |<sub>`avc_nalu`</sub>|
-|[`avc_au`](#avc_au)         |H.264/AVC&nbsp;Access&nbsp;Unit                                                          |<sub>`avc_nalu`</sub>|
-|`avc_dcr`                   |H.264/AVC&nbsp;Decoder&nbsp;Configuration&nbsp;Record                                    |<sub>`avc_nalu`</sub>|
-|`avc_nalu`                  |H.264/AVC&nbsp;Network&nbsp;Access&nbsp;Layer&nbsp;Unit                                  |<sub>`avc_sps` `avc_pps` `avc_sei`</sub>|
-|`avc_pps`                   |H.264/AVC&nbsp;Picture&nbsp;Parameter&nbsp;Set                                           |<sub></sub>|
-|`avc_sei`                   |H.264/AVC&nbsp;Supplemental&nbsp;Enhancement&nbsp;Information                            |<sub></sub>|
-|`avc_sps`                   |H.264/AVC&nbsp;Sequence&nbsp;Parameter&nbsp;Set                                          |<sub></sub>|
-|[`avro_ocf`](#avro_ocf)     |Avro&nbsp;object&nbsp;container&nbsp;file                                                |<sub></sub>|
-|[`bencode`](#bencode)       |BitTorrent&nbsp;bencoding                                                                |<sub></sub>|
-|`bitcoin_blkdat`            |Bitcoin&nbsp;blk.dat                                                                     |<sub>`bitcoin_block`</sub>|
-|`bitcoin_block`             |Bitcoin&nbsp;block                                                                       |<sub>`bitcoin_transaction`</sub>|
-|`bitcoin_script`            |Bitcoin&nbsp;script                                                                      |<sub></sub>|
-|`bitcoin_transaction`       |Bitcoin&nbsp;transaction                                                                 |<sub>`bitcoin_script`</sub>|
-|`bsd_loopback_frame`        |BSD&nbsp;loopback&nbsp;frame                                                             |<sub>`inet_packet`</sub>|
-|[`bson`](#bson)             |Binary&nbsp;JSON                                                                         |<sub></sub>|
-|`bzip2`                     |bzip2&nbsp;compression                                                                   |<sub>`probe`</sub>|
-|[`cbor`](#cbor)             |Concise&nbsp;Binary&nbsp;Object&nbsp;Representation                                      |<sub></sub>|
-|[`csv`](#csv)               |Comma&nbsp;separated&nbsp;values                                                         |<sub></sub>|
-|`dns`                       |DNS&nbsp;packet                                                                          |<sub></sub>|
-|`dns_tcp`                   |DNS&nbsp;packet&nbsp;(TCP)                                                               |<sub></sub>|
-|`elf`                       |Executable&nbsp;and&nbsp;Linkable&nbsp;Format                                            |<sub></sub>|
-|`ether8023_frame`           |Ethernet&nbsp;802.3&nbsp;frame                                                           |<sub>`inet_packet`</sub>|
-|`exif`                      |Exchangeable&nbsp;Image&nbsp;File&nbsp;Format                                            |<sub></sub>|
-|`fairplay_spc`              |FairPlay&nbsp;Server&nbsp;Playback&nbsp;Context                                          |<sub></sub>|
-|`flac`                      |Free&nbsp;Lossless&nbsp;Audio&nbsp;Codec&nbsp;file                                       |<sub>`flac_metadatablocks` `flac_frame`</sub>|
-|[`flac_frame`](#flac_frame) |FLAC&nbsp;frame                                                                          |<sub></sub>|
-|`flac_metadatablock`        |FLAC&nbsp;metadatablock                                                                  |<sub>`flac_streaminfo` `flac_picture` `vorbis_comment`</sub>|
-|`flac_metadatablocks`       |FLAC&nbsp;metadatablocks                                                                 |<sub>`flac_metadatablock`</sub>|
-|`flac_picture`              |FLAC&nbsp;metadatablock&nbsp;picture                                                     |<sub>`image`</sub>|
-|`flac_streaminfo`           |FLAC&nbsp;streaminfo                                                                     |<sub></sub>|
-|`gif`                       |Graphics&nbsp;Interchange&nbsp;Format                                                    |<sub></sub>|
-|`gzip`                      |gzip&nbsp;compression                                                                    |<sub>`probe`</sub>|
-|`hevc_annexb`               |H.265/HEVC&nbsp;Annex&nbsp;B                                                             |<sub>`hevc_nalu`</sub>|
-|[`hevc_au`](#hevc_au)       |H.265/HEVC&nbsp;Access&nbsp;Unit                                                         |<sub>`hevc_nalu`</sub>|
-|`hevc_dcr`                  |H.265/HEVC&nbsp;Decoder&nbsp;Configuration&nbsp;Record                                   |<sub>`hevc_nalu`</sub>|
-|`hevc_nalu`                 |H.265/HEVC&nbsp;Network&nbsp;Access&nbsp;Layer&nbsp;Unit                                 |<sub>`hevc_vps` `hevc_pps` `hevc_sps`</sub>|
-|`hevc_pps`                  |H.265/HEVC&nbsp;Picture&nbsp;Parameter&nbsp;Set                                          |<sub></sub>|
-|`hevc_sps`                  |H.265/HEVC&nbsp;Sequence&nbsp;Parameter&nbsp;Set                                         |<sub></sub>|
-|`hevc_vps`                  |H.265/HEVC&nbsp;Video&nbsp;Parameter&nbsp;Set                                            |<sub></sub>|
-|[`html`](#html)             |HyperText&nbsp;Markup&nbsp;Language                                                      |<sub></sub>|
-|`icc_profile`               |International&nbsp;Color&nbsp;Consortium&nbsp;profile                                    |<sub></sub>|
-|`icmp`                      |Internet&nbsp;Control&nbsp;Message&nbsp;Protocol                                         |<sub></sub>|
-|`icmpv6`                    |Internet&nbsp;Control&nbsp;Message&nbsp;Protocol&nbsp;v6                                 |<sub></sub>|
-|`id3v1`                     |ID3v1&nbsp;metadata                                                                      |<sub></sub>|
-|`id3v11`                    |ID3v1.1&nbsp;metadata                                                                    |<sub></sub>|
-|`id3v2`                     |ID3v2&nbsp;metadata                                                                      |<sub>`image`</sub>|
-|`ipv4_packet`               |Internet&nbsp;protocol&nbsp;v4&nbsp;packet                                               |<sub>`ip_packet`</sub>|
-|`ipv6_packet`               |Internet&nbsp;protocol&nbsp;v6&nbsp;packet                                               |<sub>`ip_packet`</sub>|
-|`jpeg`                      |Joint&nbsp;Photographic&nbsp;Experts&nbsp;Group&nbsp;file                                |<sub>`exif` `icc_profile`</sub>|
-|`json`                      |JavaScript&nbsp;Object&nbsp;Notation                                                     |<sub></sub>|
-|`jsonl`                     |JavaScript&nbsp;Object&nbsp;Notation&nbsp;Lines                                          |<sub></sub>|
-|[`macho`](#macho)           |Mach-O&nbsp;macOS&nbsp;executable                                                        |<sub></sub>|
-|`macho_fat`                 |Fat&nbsp;Mach-O&nbsp;macOS&nbsp;executable&nbsp;(multi-architecture)                     |<sub>`macho`</sub>|
-|[`matroska`](#matroska)     |Matroska&nbsp;file                                                                       |<sub>`aac_frame` `av1_ccr` `av1_frame` `avc_au` `avc_dcr` `flac_frame` `flac_metadatablocks` `hevc_au` `hevc_dcr` `image` `mp3_frame` `mpeg_asc` `mpeg_pes_packet` `mpeg_spu` `opus_packet` `vorbis_packet` `vp8_frame` `vp9_cfm` `vp9_frame`</sub>|
-|[`mp3`](#mp3)               |MP3&nbsp;file                                                                            |<sub>`id3v2` `id3v1` `id3v11` `apev2` `mp3_frame`</sub>|
-|`mp3_frame`                 |MPEG&nbsp;audio&nbsp;layer&nbsp;3&nbsp;frame                                             |<sub>`xing`</sub>|
-|[`mp4`](#mp4)               |ISOBMFF&nbsp;MPEG-4&nbsp;part&nbsp;12&nbsp;and&nbsp;similar                              |<sub>`aac_frame` `av1_ccr` `av1_frame` `avc_au` `avc_dcr` `flac_frame` `flac_metadatablocks` `hevc_au` `hevc_dcr` `icc_profile` `id3v2` `image` `jpeg` `mp3_frame` `mpeg_es` `mpeg_pes_packet` `opus_packet` `prores_frame` `protobuf_widevine` `pssh_playready` `vorbis_packet` `vp9_frame` `vpx_ccr`</sub>|
-|`mpeg_asc`                  |MPEG-4&nbsp;Audio&nbsp;Specific&nbsp;Config                                              |<sub></sub>|
-|`mpeg_es`                   |MPEG&nbsp;Elementary&nbsp;Stream                                                         |<sub>`mpeg_asc` `vorbis_packet`</sub>|
-|`mpeg_pes`                  |MPEG&nbsp;Packetized&nbsp;elementary&nbsp;stream                                         |<sub>`mpeg_pes_packet` `mpeg_spu`</sub>|
-|`mpeg_pes_packet`           |MPEG&nbsp;Packetized&nbsp;elementary&nbsp;stream&nbsp;packet                             |<sub></sub>|
-|`mpeg_spu`                  |Sub&nbsp;Picture&nbsp;Unit&nbsp;(DVD&nbsp;subtitle)                                      |<sub></sub>|
-|`mpeg_ts`                   |MPEG&nbsp;Transport&nbsp;Stream                                                          |<sub></sub>|
-|[`msgpack`](#msgpack)       |MessagePack                                                                              |<sub></sub>|
-|`ogg`                       |OGG&nbsp;file                                                                            |<sub>`ogg_page` `vorbis_packet` `opus_packet` `flac_metadatablock` `flac_frame`</sub>|
-|`ogg_page`                  |OGG&nbsp;page                                                                            |<sub></sub>|
-|`opus_packet`               |Opus&nbsp;packet                                                                         |<sub>`vorbis_comment`</sub>|
-|`pcap`                      |PCAP&nbsp;packet&nbsp;capture                                                            |<sub>`link_frame` `tcp_stream` `ipv4_packet`</sub>|
-|`pcapng`                    |PCAPNG&nbsp;packet&nbsp;capture                                                          |<sub>`link_frame` `tcp_stream` `ipv4_packet`</sub>|
-|`png`                       |Portable&nbsp;Network&nbsp;Graphics&nbsp;file                                            |<sub>`icc_profile` `exif`</sub>|
-|`prores_frame`              |Apple&nbsp;ProRes&nbsp;frame                                                             |<sub></sub>|
-|[`protobuf`](#protobuf)     |Protobuf                                                                                 |<sub></sub>|
-|`protobuf_widevine`         |Widevine&nbsp;protobuf                                                                   |<sub>`protobuf`</sub>|
-|`pssh_playready`            |PlayReady&nbsp;PSSH                                                                      |<sub></sub>|
-|`raw`                       |Raw&nbsp;bits                                                                            |<sub></sub>|
-|[`rtmp`](#rtmp)             |Real-Time&nbsp;Messaging&nbsp;Protocol                                                   |<sub>`amf0` `mpeg_asc`</sub>|
-|`sll2_packet`               |Linux&nbsp;cooked&nbsp;capture&nbsp;encapsulation&nbsp;v2                                |<sub>`inet_packet`</sub>|
-|`sll_packet`                |Linux&nbsp;cooked&nbsp;capture&nbsp;encapsulation                                        |<sub>`inet_packet`</sub>|
-|`tar`                       |Tar&nbsp;archive                                                                         |<sub>`probe`</sub>|
-|`tcp_segment`               |Transmission&nbsp;control&nbsp;protocol&nbsp;segment                                     |<sub></sub>|
-|`tiff`                      |Tag&nbsp;Image&nbsp;File&nbsp;Format                                                     |<sub>`icc_profile`</sub>|
-|`toml`                      |Tom's&nbsp;Obvious,&nbsp;Minimal&nbsp;Language                                           |<sub></sub>|
-|`udp_datagram`              |User&nbsp;datagram&nbsp;protocol                                                         |<sub>`udp_payload`</sub>|
-|`vorbis_comment`            |Vorbis&nbsp;comment                                                                      |<sub>`flac_picture`</sub>|
-|`vorbis_packet`             |Vorbis&nbsp;packet                                                                       |<sub>`vorbis_comment`</sub>|
-|`vp8_frame`                 |VP8&nbsp;frame                                                                           |<sub></sub>|
-|`vp9_cfm`                   |VP9&nbsp;Codec&nbsp;Feature&nbsp;Metadata                                                |<sub></sub>|
-|`vp9_frame`                 |VP9&nbsp;frame                                                                           |<sub></sub>|
-|`vpx_ccr`                   |VPX&nbsp;Codec&nbsp;Configuration&nbsp;Record                                            |<sub></sub>|
-|`wasm`                      |WebAssembly&nbsp;Binary&nbsp;Format                                                      |<sub></sub>|
-|`wav`                       |WAV&nbsp;file                                                                            |<sub>`id3v2` `id3v1` `id3v11`</sub>|
-|`webp`                      |WebP&nbsp;image                                                                          |<sub>`vp8_frame`</sub>|
-|`xing`                      |Xing&nbsp;header                                                                         |<sub></sub>|
-|[`xml`](#xml)               |Extensible&nbsp;Markup&nbsp;Language                                                     |<sub></sub>|
-|`yaml`                      |YAML&nbsp;Ain't&nbsp;Markup&nbsp;Language                                                |<sub></sub>|
-|[`zip`](#zip)               |ZIP&nbsp;archive                                                                         |<sub>`probe`</sub>|
-|`image`                     |Group                                                                                    |<sub>`gif` `jpeg` `mp4` `png` `tiff` `webp`</sub>|
-|`inet_packet`               |Group                                                                                    |<sub>`ipv4_packet` `ipv6_packet`</sub>|
-|`ip_packet`                 |Group                                                                                    |<sub>`icmp` `icmpv6` `tcp_segment` `udp_datagram`</sub>|
-|`link_frame`                |Group                                                                                    |<sub>`bsd_loopback_frame` `ether8023_frame` `sll2_packet` `sll_packet`</sub>|
-|`probe`                     |Group                                                                                    |<sub>`adts` `ar` `avro_ocf` `bitcoin_blkdat` `bzip2` `elf` `flac` `gif` `gzip` `jpeg` `json` `jsonl` `macho` `macho_fat` `matroska` `mp3` `mp4` `mpeg_ts` `ogg` `pcap` `pcapng` `png` `tar` `tiff` `toml` `wasm` `wav` `webp` `xml` `yaml` `zip`</sub>|
-|`tcp_stream`                |Group                                                                                    |<sub>`dns_tcp` `rtmp`</sub>|
-|`udp_payload`               |Group                                                                                    |<sub>`dns`</sub>|
+|Name                              |Description                                                                              |Dependencies|
+|-                                 |-                                                                                        |-|
+|[`aac_frame`](#aac_frame)         |Advanced&nbsp;Audio&nbsp;Coding&nbsp;frame                                               |<sub></sub>|
+|`adts`                            |Audio&nbsp;Data&nbsp;Transport&nbsp;Stream                                               |<sub>`adts_frame`</sub>|
+|`adts_frame`                      |Audio&nbsp;Data&nbsp;Transport&nbsp;Stream&nbsp;frame                                    |<sub>`aac_frame`</sub>|
+|`amf0`                            |Action&nbsp;Message&nbsp;Format&nbsp;0                                                   |<sub></sub>|
+|`apev2`                           |APEv2&nbsp;metadata&nbsp;tag                                                             |<sub>`image`</sub>|
+|`ar`                              |Unix&nbsp;archive                                                                        |<sub>`probe`</sub>|
+|[`asn1_ber`](#asn1_ber)           |ASN1&nbsp;BER&nbsp;(basic&nbsp;encoding&nbsp;rules,&nbsp;also&nbsp;CER&nbsp;and&nbsp;DER)|<sub></sub>|
+|`av1_ccr`                         |AV1&nbsp;Codec&nbsp;Configuration&nbsp;Record                                            |<sub></sub>|
+|`av1_frame`                       |AV1&nbsp;frame                                                                           |<sub>`av1_obu`</sub>|
+|`av1_obu`                         |AV1&nbsp;Open&nbsp;Bitstream&nbsp;Unit                                                   |<sub></sub>|
+|`avc_annexb`                      |H.264/AVC&nbsp;Annex&nbsp;B                                                              |<sub>`avc_nalu`</sub>|
+|[`avc_au`](#avc_au)               |H.264/AVC&nbsp;Access&nbsp;Unit                                                          |<sub>`avc_nalu`</sub>|
+|`avc_dcr`                         |H.264/AVC&nbsp;Decoder&nbsp;Configuration&nbsp;Record                                    |<sub>`avc_nalu`</sub>|
+|`avc_nalu`                        |H.264/AVC&nbsp;Network&nbsp;Access&nbsp;Layer&nbsp;Unit                                  |<sub>`avc_sps` `avc_pps` `avc_sei`</sub>|
+|`avc_pps`                         |H.264/AVC&nbsp;Picture&nbsp;Parameter&nbsp;Set                                           |<sub></sub>|
+|`avc_sei`                         |H.264/AVC&nbsp;Supplemental&nbsp;Enhancement&nbsp;Information                            |<sub></sub>|
+|`avc_sps`                         |H.264/AVC&nbsp;Sequence&nbsp;Parameter&nbsp;Set                                          |<sub></sub>|
+|[`avro_ocf`](#avro_ocf)           |Avro&nbsp;object&nbsp;container&nbsp;file                                                |<sub></sub>|
+|[`bencode`](#bencode)             |BitTorrent&nbsp;bencoding                                                                |<sub></sub>|
+|`bitcoin_blkdat`                  |Bitcoin&nbsp;blk.dat                                                                     |<sub>`bitcoin_block`</sub>|
+|[`bitcoin_block`](#bitcoin_block) |Bitcoin&nbsp;block                                                                       |<sub>`bitcoin_transaction`</sub>|
+|`bitcoin_script`                  |Bitcoin&nbsp;script                                                                      |<sub></sub>|
+|`bitcoin_transaction`             |Bitcoin&nbsp;transaction                                                                 |<sub>`bitcoin_script`</sub>|
+|`bsd_loopback_frame`              |BSD&nbsp;loopback&nbsp;frame                                                             |<sub>`inet_packet`</sub>|
+|[`bson`](#bson)                   |Binary&nbsp;JSON                                                                         |<sub></sub>|
+|`bzip2`                           |bzip2&nbsp;compression                                                                   |<sub>`probe`</sub>|
+|[`cbor`](#cbor)                   |Concise&nbsp;Binary&nbsp;Object&nbsp;Representation                                      |<sub></sub>|
+|[`csv`](#csv)                     |Comma&nbsp;separated&nbsp;values                                                         |<sub></sub>|
+|`dns`                             |DNS&nbsp;packet                                                                          |<sub></sub>|
+|`dns_tcp`                         |DNS&nbsp;packet&nbsp;(TCP)                                                               |<sub></sub>|
+|`elf`                             |Executable&nbsp;and&nbsp;Linkable&nbsp;Format                                            |<sub></sub>|
+|`ether8023_frame`                 |Ethernet&nbsp;802.3&nbsp;frame                                                           |<sub>`inet_packet`</sub>|
+|`exif`                            |Exchangeable&nbsp;Image&nbsp;File&nbsp;Format                                            |<sub></sub>|
+|`fairplay_spc`                    |FairPlay&nbsp;Server&nbsp;Playback&nbsp;Context                                          |<sub></sub>|
+|`flac`                            |Free&nbsp;Lossless&nbsp;Audio&nbsp;Codec&nbsp;file                                       |<sub>`flac_metadatablocks` `flac_frame`</sub>|
+|[`flac_frame`](#flac_frame)       |FLAC&nbsp;frame                                                                          |<sub></sub>|
+|`flac_metadatablock`              |FLAC&nbsp;metadatablock                                                                  |<sub>`flac_streaminfo` `flac_picture` `vorbis_comment`</sub>|
+|`flac_metadatablocks`             |FLAC&nbsp;metadatablocks                                                                 |<sub>`flac_metadatablock`</sub>|
+|`flac_picture`                    |FLAC&nbsp;metadatablock&nbsp;picture                                                     |<sub>`image`</sub>|
+|`flac_streaminfo`                 |FLAC&nbsp;streaminfo                                                                     |<sub></sub>|
+|`gif`                             |Graphics&nbsp;Interchange&nbsp;Format                                                    |<sub></sub>|
+|`gzip`                            |gzip&nbsp;compression                                                                    |<sub>`probe`</sub>|
+|`hevc_annexb`                     |H.265/HEVC&nbsp;Annex&nbsp;B                                                             |<sub>`hevc_nalu`</sub>|
+|[`hevc_au`](#hevc_au)             |H.265/HEVC&nbsp;Access&nbsp;Unit                                                         |<sub>`hevc_nalu`</sub>|
+|`hevc_dcr`                        |H.265/HEVC&nbsp;Decoder&nbsp;Configuration&nbsp;Record                                   |<sub>`hevc_nalu`</sub>|
+|`hevc_nalu`                       |H.265/HEVC&nbsp;Network&nbsp;Access&nbsp;Layer&nbsp;Unit                                 |<sub>`hevc_vps` `hevc_pps` `hevc_sps`</sub>|
+|`hevc_pps`                        |H.265/HEVC&nbsp;Picture&nbsp;Parameter&nbsp;Set                                          |<sub></sub>|
+|`hevc_sps`                        |H.265/HEVC&nbsp;Sequence&nbsp;Parameter&nbsp;Set                                         |<sub></sub>|
+|`hevc_vps`                        |H.265/HEVC&nbsp;Video&nbsp;Parameter&nbsp;Set                                            |<sub></sub>|
+|[`html`](#html)                   |HyperText&nbsp;Markup&nbsp;Language                                                      |<sub></sub>|
+|`icc_profile`                     |International&nbsp;Color&nbsp;Consortium&nbsp;profile                                    |<sub></sub>|
+|`icmp`                            |Internet&nbsp;Control&nbsp;Message&nbsp;Protocol                                         |<sub></sub>|
+|`icmpv6`                          |Internet&nbsp;Control&nbsp;Message&nbsp;Protocol&nbsp;v6                                 |<sub></sub>|
+|`id3v1`                           |ID3v1&nbsp;metadata                                                                      |<sub></sub>|
+|`id3v11`                          |ID3v1.1&nbsp;metadata                                                                    |<sub></sub>|
+|`id3v2`                           |ID3v2&nbsp;metadata                                                                      |<sub>`image`</sub>|
+|`ipv4_packet`                     |Internet&nbsp;protocol&nbsp;v4&nbsp;packet                                               |<sub>`ip_packet`</sub>|
+|`ipv6_packet`                     |Internet&nbsp;protocol&nbsp;v6&nbsp;packet                                               |<sub>`ip_packet`</sub>|
+|`jpeg`                            |Joint&nbsp;Photographic&nbsp;Experts&nbsp;Group&nbsp;file                                |<sub>`exif` `icc_profile`</sub>|
+|`json`                            |JavaScript&nbsp;Object&nbsp;Notation                                                     |<sub></sub>|
+|`jsonl`                           |JavaScript&nbsp;Object&nbsp;Notation&nbsp;Lines                                          |<sub></sub>|
+|[`macho`](#macho)                 |Mach-O&nbsp;macOS&nbsp;executable                                                        |<sub></sub>|
+|`macho_fat`                       |Fat&nbsp;Mach-O&nbsp;macOS&nbsp;executable&nbsp;(multi-architecture)                     |<sub>`macho`</sub>|
+|`markdown`                        |Markdown                                                                                 |<sub></sub>|
+|[`matroska`](#matroska)           |Matroska&nbsp;file                                                                       |<sub>`aac_frame` `av1_ccr` `av1_frame` `avc_au` `avc_dcr` `flac_frame` `flac_metadatablocks` `hevc_au` `hevc_dcr` `image` `mp3_frame` `mpeg_asc` `mpeg_pes_packet` `mpeg_spu` `opus_packet` `vorbis_packet` `vp8_frame` `vp9_cfm` `vp9_frame`</sub>|
+|[`mp3`](#mp3)                     |MP3&nbsp;file                                                                            |<sub>`id3v2` `id3v1` `id3v11` `apev2` `mp3_frame`</sub>|
+|`mp3_frame`                       |MPEG&nbsp;audio&nbsp;layer&nbsp;3&nbsp;frame                                             |<sub>`xing`</sub>|
+|[`mp4`](#mp4)                     |ISOBMFF,&nbsp;QuickTime&nbsp;and&nbsp;similar                                            |<sub>`aac_frame` `av1_ccr` `av1_frame` `avc_au` `avc_dcr` `flac_frame` `flac_metadatablocks` `hevc_au` `hevc_dcr` `icc_profile` `id3v2` `image` `jpeg` `mp3_frame` `mpeg_es` `mpeg_pes_packet` `opus_packet` `prores_frame` `protobuf_widevine` `pssh_playready` `vorbis_packet` `vp9_frame` `vpx_ccr`</sub>|
+|`mpeg_asc`                        |MPEG-4&nbsp;Audio&nbsp;Specific&nbsp;Config                                              |<sub></sub>|
+|`mpeg_es`                         |MPEG&nbsp;Elementary&nbsp;Stream                                                         |<sub>`mpeg_asc` `vorbis_packet`</sub>|
+|`mpeg_pes`                        |MPEG&nbsp;Packetized&nbsp;elementary&nbsp;stream                                         |<sub>`mpeg_pes_packet` `mpeg_spu`</sub>|
+|`mpeg_pes_packet`                 |MPEG&nbsp;Packetized&nbsp;elementary&nbsp;stream&nbsp;packet                             |<sub></sub>|
+|`mpeg_spu`                        |Sub&nbsp;Picture&nbsp;Unit&nbsp;(DVD&nbsp;subtitle)                                      |<sub></sub>|
+|`mpeg_ts`                         |MPEG&nbsp;Transport&nbsp;Stream                                                          |<sub></sub>|
+|[`msgpack`](#msgpack)             |MessagePack                                                                              |<sub></sub>|
+|`ogg`                             |OGG&nbsp;file                                                                            |<sub>`ogg_page` `vorbis_packet` `opus_packet` `flac_metadatablock` `flac_frame`</sub>|
+|`ogg_page`                        |OGG&nbsp;page                                                                            |<sub></sub>|
+|`opus_packet`                     |Opus&nbsp;packet                                                                         |<sub>`vorbis_comment`</sub>|
+|`pcap`                            |PCAP&nbsp;packet&nbsp;capture                                                            |<sub>`link_frame` `tcp_stream` `ipv4_packet`</sub>|
+|`pcapng`                          |PCAPNG&nbsp;packet&nbsp;capture                                                          |<sub>`link_frame` `tcp_stream` `ipv4_packet`</sub>|
+|`png`                             |Portable&nbsp;Network&nbsp;Graphics&nbsp;file                                            |<sub>`icc_profile` `exif`</sub>|
+|`prores_frame`                    |Apple&nbsp;ProRes&nbsp;frame                                                             |<sub></sub>|
+|[`protobuf`](#protobuf)           |Protobuf                                                                                 |<sub></sub>|
+|`protobuf_widevine`               |Widevine&nbsp;protobuf                                                                   |<sub>`protobuf`</sub>|
+|`pssh_playready`                  |PlayReady&nbsp;PSSH                                                                      |<sub></sub>|
+|`raw`                             |Raw&nbsp;bits                                                                            |<sub></sub>|
+|[`rtmp`](#rtmp)                   |Real-Time&nbsp;Messaging&nbsp;Protocol                                                   |<sub>`amf0` `mpeg_asc`</sub>|
+|`sll2_packet`                     |Linux&nbsp;cooked&nbsp;capture&nbsp;encapsulation&nbsp;v2                                |<sub>`inet_packet`</sub>|
+|`sll_packet`                      |Linux&nbsp;cooked&nbsp;capture&nbsp;encapsulation                                        |<sub>`inet_packet`</sub>|
+|`tar`                             |Tar&nbsp;archive                                                                         |<sub>`probe`</sub>|
+|`tcp_segment`                     |Transmission&nbsp;control&nbsp;protocol&nbsp;segment                                     |<sub></sub>|
+|`tiff`                            |Tag&nbsp;Image&nbsp;File&nbsp;Format                                                     |<sub>`icc_profile`</sub>|
+|`toml`                            |Tom's&nbsp;Obvious,&nbsp;Minimal&nbsp;Language                                           |<sub></sub>|
+|`udp_datagram`                    |User&nbsp;datagram&nbsp;protocol                                                         |<sub>`udp_payload`</sub>|
+|`vorbis_comment`                  |Vorbis&nbsp;comment                                                                      |<sub>`flac_picture`</sub>|
+|`vorbis_packet`                   |Vorbis&nbsp;packet                                                                       |<sub>`vorbis_comment`</sub>|
+|`vp8_frame`                       |VP8&nbsp;frame                                                                           |<sub></sub>|
+|`vp9_cfm`                         |VP9&nbsp;Codec&nbsp;Feature&nbsp;Metadata                                                |<sub></sub>|
+|`vp9_frame`                       |VP9&nbsp;frame                                                                           |<sub></sub>|
+|`vpx_ccr`                         |VPX&nbsp;Codec&nbsp;Configuration&nbsp;Record                                            |<sub></sub>|
+|[`wasm`](#wasm)                   |WebAssembly&nbsp;Binary&nbsp;Format                                                      |<sub></sub>|
+|`wav`                             |WAV&nbsp;file                                                                            |<sub>`id3v2` `id3v1` `id3v11`</sub>|
+|`webp`                            |WebP&nbsp;image                                                                          |<sub>`vp8_frame`</sub>|
+|`xing`                            |Xing&nbsp;header                                                                         |<sub></sub>|
+|[`xml`](#xml)                     |Extensible&nbsp;Markup&nbsp;Language                                                     |<sub></sub>|
+|`yaml`                            |YAML&nbsp;Ain't&nbsp;Markup&nbsp;Language                                                |<sub></sub>|
+|[`zip`](#zip)                     |ZIP&nbsp;archive                                                                         |<sub>`probe`</sub>|
+|`image`                           |Group                                                                                    |<sub>`gif` `jpeg` `mp4` `png` `tiff` `webp`</sub>|
+|`inet_packet`                     |Group                                                                                    |<sub>`ipv4_packet` `ipv6_packet`</sub>|
+|`ip_packet`                       |Group                                                                                    |<sub>`icmp` `icmpv6` `tcp_segment` `udp_datagram`</sub>|
+|`link_frame`                      |Group                                                                                    |<sub>`bsd_loopback_frame` `ether8023_frame` `sll2_packet` `sll_packet`</sub>|
+|`probe`                           |Group                                                                                    |<sub>`adts` `ar` `avro_ocf` `bitcoin_blkdat` `bzip2` `elf` `flac` `gif` `gzip` `jpeg` `json` `jsonl` `macho` `macho_fat` `matroska` `mp3` `mp4` `mpeg_ts` `ogg` `pcap` `pcapng` `png` `tar` `tiff` `toml` `wasm` `wav` `webp` `xml` `yaml` `zip`</sub>|
+|`tcp_stream`                      |Group                                                                                    |<sub>`dns_tcp` `rtmp`</sub>|
+|`udp_payload`                     |Group                                                                                    |<sub>`dns`</sub>|

 [#]: sh-end

@ -133,15 +134,15 @@ fq -d raw 'mp4({force: true})' file.mp4

 [fq -rn -L . 'include "formats"; formats_sections']: sh-start

-### aac_frame
+## aac_frame

-#### Options
+### Options

 |Name         |Default|Description|
 |-            |-      |-|
 |`object_type`|1      |Audio object type|

-#### Examples
+### Examples

 Decode file using aac_frame options
 ```
@ -153,7 +154,7 @@ Decode value as aac_frame
 ... | aac_frame({object_type:1})
 ```

-### asn1_ber
+## asn1_ber

 Supports decoding BER, CER and DER (X.690).

@ -161,49 +162,39 @@ Supports decoding BER, CER and DER (X.690).
 - Does not support specifying a schema.
 - Supports `torepr` but without schema all sequences and sets will be arrays.

-#### Examples
+### `frompem` can be used to decode certificates etc

-`frompem` and `topem` can be used to work with PEM format
-```
+```sh
 $ fq -d raw 'frompem | asn1_ber | d' cert.pem
 ```

-Can be used to decode nested parts
-```
+### Can decode nested values
+
+```sh
 $ fq -d asn1_ber '.constructed[1].value | asn1_ber' file.ber
 ```

-If schema is known and not complicated it can be reproduced
-```
+### Manual schema
+
+```sh
 $ fq -d asn1_ber 'torepr as $r | ["version", "modulus", "private_exponent", "private_exponen", "prime1", "prime2", "exponent1", "exponent2", "coefficient"] | with_entries({key: .value, value: $r[.key]})' pkcs1.der
 ```

-Supports `torepr`
-```
-$ fq -d asn1_ber torepr file
-```
-
-Supports `torepr`
-```
-... | asn1_ber | torepr
-```
-
-#### References and links
-
+### References
 - https://www.itu.int/ITU-T/studygroups/com10/languages/X.690_1297.pdf
 - https://en.wikipedia.org/wiki/X.690
 - https://letsencrypt.org/docs/a-warm-welcome-to-asn1-and-der/
 - https://lapo.it/asn1js/

-### avc_au
+## avc_au

-#### Options
+### Options

 |Name         |Default|Description|
 |-            |-      |-|
 |`length_size`|4      |Length value size|

-#### Examples
+### Examples

 Decode file using avc_au options
 ```
@ -215,90 +206,90 @@ Decode value as avc_au
 ... | avc_au({length_size:4})
 ```

-### avro_ocf
+## avro_ocf

 Supports reading Avro Object Container Format (OCF) files based on the 1.11.0 specification.

 Capable of handling null, deflate, and snappy codecs for data compression.

 Limitations:
- - Schema does not support self-referential types, only built-in types.
- - Decimal logical types are not supported for decoding, will just be treated as their primitive type

-#### References and links
+- Schema does not support self-referential types, only built-in types.
+- Decimal logical types are not supported for decoding, will just be treated as their primitive type

+### References
 - https://avro.apache.org/docs/current/spec.html#Object+Container+Files

-### bencode
+## bencode

-#### Examples
+### Convert represented value to JSON

-Supports `torepr`
 ```
-$ fq -d bencode torepr file
+$ fq -d bencode torepr file.torrent
 ```

-Supports `torepr`
-```
-... | bencode | torepr
-```
-
-#### References and links
-
+### References
 - https://wiki.theory.org/BitTorrentSpecification#Bencoding

-### bson
+## bitcoin_block

-#### Examples
+### Options

-BSON as JSON
+|Name        |Default|Description|
+|-           |-      |-|
+|`has_header`|false  |Has blkdat header|
+
+### Examples
+
+Decode file using bitcoin_block options
 ```
-$ fq -d bson torepr file
+$ fq -d bitcoin_block -o has_header=false . file
 ```

-Supports `torepr`
+Decode value as bitcoin_block
 ```
-$ fq -d bson torepr file
+... | bitcoin_block({has_header:false})
 ```

-Supports `torepr`
+## bson
+
+### Convert represented value to JSON
+
 ```
-... | bson | torepr
+$ fq -d bson torepr file.bson
 ```

-#### References and links
+### Filter represented value

- https://wiki.theory.org/BitTorrentSpecification#Bencoding
-
-### cbor
-
-#### Examples
-
-Supports `torepr`
 ```
-$ fq -d cbor torepr file
+$ fq -d bson 'torepr | select(.name=="bob")' file.bson
 ```

-Supports `torepr`
+### References
+- https://bsonspec.org/spec.html
+
+## cbor
+
+### Convert represented value to JSON
+
 ```
-... | cbor | torepr
+$ fq -d cbor torepr file.cbor
 ```

-#### References and links
-
+### References
 - https://en.wikipedia.org/wiki/CBOR
 - https://www.rfc-editor.org/rfc/rfc8949.html

-### csv
+## csv

-#### Options
+### Options

 |Name     |Default|Description|
 |-        |-      |-|
 |`comma`  |,      |Separator character|
 |`comment`|#      |Comment line character|

-#### Examples
+### Examples

 Decode file using csv options
 ```
@ -310,15 +301,27 @@ Decode value as csv
 ... | csv({comma:",",comment:"#"})
 ```

-### flac_frame
+### TSV to CSV

-#### Options
+```sh
+$ fq -d csv -o comma="\t" tocsv file.tsv
+```
+
+### Convert rows to objects based on header row
+
+```sh
+$ fq -d csv '.[0] as $t | .[1:] | map(with_entries(.key = $t[.key]))' file.csv
+```
+
+## flac_frame
+
+### Options

 |Name             |Default|Description|
 |-                |-      |-|
 |`bits_per_sample`|16     |Bits per sample|

-#### Examples
+### Examples

 Decode file using flac_frame options
 ```
@ -330,15 +333,15 @@ Decode value as flac_frame
 ... | flac_frame({bits_per_sample:16})
 ```

-### hevc_au
+## hevc_au

-#### Options
+### Options

 |Name         |Default|Description|
 |-            |-      |-|
 |`length_size`|4      |Length value size|

-#### Examples
+### Examples

 Decode file using hevc_au options
 ```
@ -350,9 +353,9 @@ Decode value as hevc_au
 ... | hevc_au({length_size:4})
 ```

-### html
+## html

-#### Options
+### Options

 |Name              |Default|Description|
 |-                 |-      |-|
@ -360,7 +363,7 @@ Decode value as hevc_au
 |`attribute_prefix`|@      |Prefix for attribute keys|
 |`seq`             |false  |Use seq attribute to preserve element order|

-#### Examples
+### Examples

 Decode file using html options
 ```
@ -372,53 +375,50 @@ Decode value as html
 ... | html({array:false,attribute_prefix:"@",seq:false})
 ```

-### macho
+## macho

 Supports decoding vanilla and FAT Mach-O binaries.

-#### Examples
+### Select 64bit load segments

-Select 64bit load segments
-```
+```sh
 $ fq '.load_commands[] | select(.cmd=="segment_64")' file
 ```

-#### References and links
-
+### References
 - https://github.com/aidansteele/osx-abi-macho-file-format-reference

-### matroska
+## matroska

-#### Examples
+### Lookup element path using `matroska_path`

-Lookup element decode value using `matroska_path`
-```
-... | matroska_path(".Segment.Tracks[0)"
+```sh
+$ fq 'matroska_path(".Segment.Tracks[0)")' file.mkv
 ```

-Return `matroska_path` string for a box decode value
-```
-... | grep_by(.id == "Tracks") | matroska_path
+### Get element path using `matroska_path`
+
+```sh
+$ fq 'grep_by(.id == "Tracks") | matroska_path' file.mkv
 ```

-#### References and links
-
+### References
 - https://tools.ietf.org/html/draft-ietf-cellar-ebml-00
 - https://matroska.org/technical/specs/index.html
 - https://www.matroska.org/technical/basics.html
 - https://www.matroska.org/technical/codec_specs.html
 - https://wiki.xiph.org/MatroskaOpus

-### mp3
+## mp3

-#### Options
+### Options

 |Name                       |Default|Description|
 |-                          |-      |-|
 |`max_sync_seek`            |32768  |Max byte distance to next sync|
 |`max_unique_header_configs`|5      |Max number of unique frame header configs allowed|

-#### Examples
+### Examples

 Decode file using mp3 options
 ```
@ -430,28 +430,16 @@ Decode value as mp3
 ... | mp3({max_sync_seek:32768,max_unique_header_configs:5})
 ```

-### mp4
+## mp4

-Support `mp4_path`
-
-#### Options
+### Options

 |Name             |Default|Description|
 |-                |-      |-|
 |`allow_truncated`|false  |Allow box to be truncated|
 |`decode_samples` |true   |Decode supported media samples|

-#### Examples
-
-Lookup box decode value using `mp4_path`
-```
-... | mp4_path(".moov.trak[1]")
-```
-
-Return `mp4_path` string for a box decode value
-```
-... | grep_by(.type == "trak") | mp4_path
-```
+### Examples

 Decode file using mp4 options
 ```
@ -463,54 +451,96 @@ Decode value as mp4
 ... | mp4({allow_truncated:false,decode_samples:true})
 ```

-#### References and links
+### `mp4_path($path)` - Lookup mp4 box using a mp4 box path.
+
+```sh
+# <decode value box> | mp4_path($path) -> <decode value box>
+$ fq 'mp4_path(".moov.trak[1]")' file.mp4
+```
+
+### `mp4_path` - Return mp4 box path for a decode value box.
+
+```sh
+# <decode value box> | mp4_path -> string
+$ fq 'grep_by(.type == "trak") | mp4_path' file.mp4
+```
+
+### Force decode a single box
+
+```sh
+$ fq -n '"AAAAHGVsc3QAAAAAAAAAAQAAADIAAAQAAAEAAA==" | frombase64 | mp4({force:true}) | d'
+```
+
+### Don't decode samples and manually decode first sample for first track as a `aac_frame`
+
+```sh
+$ fq -o decode_samples=false '.tracks[0].samples[0] | aac_frame | d' file.mp4
+```
+
+### Entries for first edit list as values
+
+```sh
+$ fq 'first(grep_by(.type=="elst").entries) | tovalue' file.mp4
+```
+
+### References

 - [ISO/IEC base media file format (MPEG-4 Part 12)](https://en.wikipedia.org/wiki/ISO/IEC_base_media_file_format)
 - [Quicktime file format](https://developer.apple.com/standards/qtff-2001.pdf)

-### msgpack
+## msgpack

-#### Examples
+### Convert represented value to JSON

-Supports `torepr`
 ```
-$ fq -d msgpack torepr file
+$ fq -d msgpack torepr file.msgpack
 ```

-Supports `torepr`
-```
-... | msgpack | torepr
-```
-
-#### References and links
-
+### References
 - https://github.com/msgpack/msgpack/blob/master/spec.md

-### protobuf
+## protobuf

-#### Examples
+### Can decode sub messages

-Can be used to decode sub messages
-```
-$ fq -d protobuf '.fields[6].wire_value | protobuf | d'
+```sh
+$ fq -d protobuf '.fields[6].wire_value | protobuf | d' file
 ```

-#### References and links
-
+### References
 - https://developers.google.com/protocol-buffers/docs/encoding

-### rtmp
+## rtmp

 Current only supports plain RTMP (not RTMPT or encrypted variants etc) with AMF0 (not AMF3).

-#### References and links
-
+### References
 - https://rtmp.veriskope.com/docs/spec/
 - https://rtmp.veriskope.com/pdf/video_file_format_spec_v10.pdf

-### xml
+## wasm

-#### Options
+### Count opcode usage
+```sh
+$ fq '.sections[] | select(.id == "code_section") | [.. | .opcode? // empty] | count | map({key: .[0], value: .[1]}) | from_entries' file.wasm
+```
+
+### List exports and imports
+```sh
+$ fq '.sections | {import: map(select(.id == "import_section").content.im.x[].nm.b), export: map(select(.id == "export_section").content.ex.x[].nm.b)}' file.wasm
+```
+
+### Authors
+- Takashi Oguma
+[@bitbears-dev](https://github.com/bitbears-dev)
+[@0xb17bea125](https://twitter.com/0xb17bea125)
+
+### References
+- https://webassembly.github.io/spec/core/
+
+## xml
+
+### Options

 |Name              |Default|Description|
 |-                 |-      |-|
@ -518,7 +548,7 @@ Current only supports plain RTMP (not RTMPT or encrypted variants etc) with AMF0
 |`attribute_prefix`|@      |Prefix for attribute keys|
 |`seq`             |false  |Use seq attribute to preserve element order|

-#### Examples
+### Examples

 Decode file using xml options
 ```
@ -530,21 +560,18 @@ Decode value as xml
 ... | xml({array:false,attribute_prefix:"@",seq:false})
 ```

-#### References and links
-
+### References
 - [xml.com's Converting Between XML and JSON](https://www.xml.com/pub/a/2006/05/31/converting-between-xml-and-json.html)

-### zip
+## zip

-Supports ZIP64.
-
-#### Options
+### Options

 |Name        |Default|Description|
 |-           |-      |-|
 |`uncompress`|true   |Uncompress and probe files|

-#### Examples
+### Examples

 Decode file using zip options
 ```
@ -556,9 +583,11 @@ Decode value as zip
 ... | zip({uncompress:true})
 ```

-#### References and links
+Supports ZIP64.

+### References
 - https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT
+- https://opensource.apple.com/source/zip/zip-6/unzip/unzip/proginfo/extra.fld


 [#]: sh-end
--- a/doc/formats.svg
+++ b/doc/formats.svg
--- a/format/all/all.go
+++ b/format/all/all.go
@ -28,6 +28,7 @@ import (
 	_ "github.com/wader/fq/format/jpeg"
 	_ "github.com/wader/fq/format/json"
 	_ "github.com/wader/fq/format/macho"
+	_ "github.com/wader/fq/format/markdown"
 	_ "github.com/wader/fq/format/math"
 	_ "github.com/wader/fq/format/matroska"
 	_ "github.com/wader/fq/format/mp3"
--- a/format/all/help.fqtest
+++ b/format/all/help.fqtest
--- a/format/asn1/asn1_ber.go
+++ b/format/asn1/asn1_ber.go
@ -29,6 +29,7 @@ import (
 )

 //go:embed asn1_ber.jq
+//go:embed asn1_ber.md
 var asn1FS embed.FS

 func init() {
@ -36,7 +37,7 @@ func init() {
 		Name:        format.ASN1_BER,
 		Description: "ASN1 BER (basic encoding rules, also CER and DER)",
 		DecodeFn:    decodeASN1BER,
-		Functions:   []string{"torepr", "_help"},
+		Functions:   []string{"torepr"},
 	})
 	interp.RegisterFS(asn1FS)
 }
--- a/format/asn1/asn1_ber.jq
+++ b/format/asn1/asn1_ber.jq
@ -6,24 +6,3 @@ def _asn1_ber_torepr:
    end
  else .constructed | map(_asn1_ber_torepr)
  end;
-
-def _asn1_ber__help:
-  { notes: "Supports decoding BER, CER and DER (X.690).
-
- Currently no extra validation is done for CER and DER.
- Does not support specifying a schema.
- Supports `torepr` but without schema all sequences and sets will be arrays.",
-    examples: [
-      {comment: "`frompem` and `topem` can be used to work with PEM format", shell: "fq -d raw 'frompem | asn1_ber | d' cert.pem"},
-      {comment: "Can be used to decode nested parts", shell: "fq -d asn1_ber '.constructed[1].value | asn1_ber' file.ber"},
-      { comment: "If schema is known and not complicated it can be reproduced",
-        shell: "fq -d asn1_ber 'torepr as $r | [\"version\", \"modulus\", \"private_exponent\", \"private_exponen\", \"prime1\", \"prime2\", \"exponent1\", \"exponent2\", \"coefficient\"] | with_entries({key: .value, value: $r[.key]})' pkcs1.der"
-      }
-    ],
-    links: [
-      {url: "https://www.itu.int/ITU-T/studygroups/com10/languages/X.690_1297.pdf"},
-      {url: "https://en.wikipedia.org/wiki/X.690"},
-      {url: "https://letsencrypt.org/docs/a-warm-welcome-to-asn1-and-der/"},
-      {url: "https://lapo.it/asn1js/"}
-    ]
-  };
--- a/format/asn1/asn1_ber.md
+++ b/format/asn1/asn1_ber.md
@ -0,0 +1,29 @@
+Supports decoding BER, CER and DER (X.690).
+
+- Currently no extra validation is done for CER and DER.
+- Does not support specifying a schema.
+- Supports `torepr` but without schema all sequences and sets will be arrays.
+
+### `frompem` can be used to decode certificates etc
+
+```sh
+$ fq -d raw 'frompem | asn1_ber | d' cert.pem
+```
+
+### Can decode nested values
+
+```sh
+$ fq -d asn1_ber '.constructed[1].value | asn1_ber' file.ber
+```
+
+### Manual schema
+
+```sh
+$ fq -d asn1_ber 'torepr as $r | ["version", "modulus", "private_exponent", "private_exponen", "prime1", "prime2", "exponent1", "exponent2", "coefficient"] | with_entries({key: .value, value: $r[.key]})' pkcs1.der
+```
+
+### References
+- https://www.itu.int/ITU-T/studygroups/com10/languages/X.690_1297.pdf
+- https://en.wikipedia.org/wiki/X.690
+- https://letsencrypt.org/docs/a-warm-welcome-to-asn1-and-der/
+- https://lapo.it/asn1js/
--- a/format/avro/avro_ocf.go
+++ b/format/avro/avro_ocf.go
@ -16,7 +16,7 @@ import (
 	"github.com/wader/fq/pkg/scalar"
 )

-//go:embed avro_ocf.jq
+//go:embed avro_ocf.md
 var avroOcfFS embed.FS

 func init() {
@ -25,7 +25,6 @@ func init() {
 		Description: "Avro object container file",
 		Groups:      []string{format.PROBE},
 		DecodeFn:    decodeAvroOCF,
-		Functions:   []string{"_help"},
 	})
 	interp.RegisterFS(avroOcfFS)
 }
--- a/format/avro/avro_ocf.jq
+++ b/format/avro/avro_ocf.jq
@ -1,12 +0,0 @@
-def _avro_ocf__help:
-  { notes: "Supports reading Avro Object Container Format (OCF) files based on the 1.11.0 specification.
-
-Capable of handling null, deflate, and snappy codecs for data compression.
-
-Limitations:
- - Schema does not support self-referential types, only built-in types.
- - Decimal logical types are not supported for decoding, will just be treated as their primitive type",
-    links: [
-      {url: "https://avro.apache.org/docs/current/spec.html#Object+Container+Files"}
-    ]
-  };
--- a/format/avro/avro_ocf.md
+++ b/format/avro/avro_ocf.md
@ -0,0 +1,11 @@
+Supports reading Avro Object Container Format (OCF) files based on the 1.11.0 specification.
+
+Capable of handling null, deflate, and snappy codecs for data compression.
+
+Limitations:
+
+- Schema does not support self-referential types, only built-in types.
+- Decimal logical types are not supported for decoding, will just be treated as their primitive type
+
+### References
+- https://avro.apache.org/docs/current/spec.html#Object+Container+Files
--- a/format/bencode/bencode.go
+++ b/format/bencode/bencode.go
@ -13,6 +13,7 @@ import (
 )

 //go:embed bencode.jq
+//go:embed bencode.md
 var bencodeFS embed.FS

 func init() {
@ -20,7 +21,7 @@ func init() {
 		Name:        format.BENCODE,
 		Description: "BitTorrent bencoding",
 		DecodeFn:    decodeBencode,
-		Functions:   []string{"torepr", "_help"},
+		Functions:   []string{"torepr"},
 	})
 	interp.RegisterFS(bencodeFS)
 }
--- a/format/bencode/bencode.jq
+++ b/format/bencode/bencode.jq
@ -9,9 +9,3 @@ def _bencode_torepr:
    )
  else error("unknown type \(.type)")
  end;
-
-def _bencode__help:
-  { links: [
-      {url: "https://wiki.theory.org/BitTorrentSpecification#Bencoding"}
-    ]
-  };
--- a/format/bencode/bencode.md
+++ b/format/bencode/bencode.md
@ -0,0 +1,8 @@
+### Convert represented value to JSON
+
+```
+$ fq -d bencode torepr file.torrent
+```
+
+### References
+- https://wiki.theory.org/BitTorrentSpecification#Bencoding
--- a/format/bson/bson.go
+++ b/format/bson/bson.go
@ -13,6 +13,7 @@ import (
 )

 //go:embed bson.jq
+//go:embed bson.md
 var bsonFS embed.FS

 func init() {
@ -20,7 +21,7 @@ func init() {
 		Name:        format.BSON,
 		Description: "Binary JSON",
 		DecodeFn:    decodeBSON,
-		Functions:   []string{"torepr", "_help"},
+		Functions:   []string{"torepr"},
 	})
 	interp.RegisterFS(bsonFS)
 }
--- a/format/bson/bson.jq
+++ b/format/bson/bson.jq
@ -17,11 +17,3 @@ def _bson_torepr:
  | _f
  );

-def _bson__help:
-  { examples: [
-      {comment: "BSON as JSON", shell: "fq -d bson torepr file"}
-    ],
-    links: [
-      {url: "https://wiki.theory.org/BitTorrentSpecification#Bencoding"}
-    ]
-  };
--- a/format/bson/bson.md
+++ b/format/bson/bson.md
@ -0,0 +1,14 @@
+### Convert represented value to JSON
+
+```
+$ fq -d bson torepr file.bson
+```
+
+### Filter represented value
+
+```
+$ fq -d bson 'torepr | select(.name=="bob")' file.bson
+```
+
+### References
+- https://bsonspec.org/spec.html
--- a/format/cbor/cbor.go
+++ b/format/cbor/cbor.go
@ -21,6 +21,7 @@ import (
 )

 //go:embed cbor.jq
+//go:embed cbor.md
 var cborFS embed.FS

 func init() {
@ -28,7 +29,7 @@ func init() {
 		Name:        format.CBOR,
 		Description: "Concise Binary Object Representation",
 		DecodeFn:    decodeCBOR,
-		Functions:   []string{"torepr", "_help"},
+		Functions:   []string{"torepr"},
 	})
 	interp.RegisterFS(cborFS)
 }
--- a/format/cbor/cbor.jq
+++ b/format/cbor/cbor.jq
@ -8,10 +8,3 @@ def _cbor_torepr:
  elif .major_type == "bytes" then .value | tostring
  else .value | tovalue
  end;
-
-def _cbor__help:
-  { links: [
-      {url: "https://en.wikipedia.org/wiki/CBOR"},
-      {url: "https://www.rfc-editor.org/rfc/rfc8949.html"}
-    ]
-  };
--- a/format/cbor/cbor.md
+++ b/format/cbor/cbor.md
@ -0,0 +1,9 @@
+### Convert represented value to JSON
+
+```
+$ fq -d cbor torepr file.cbor
+```
+
+### References
+- https://en.wikipedia.org/wiki/CBOR
+- https://www.rfc-editor.org/rfc/rfc8949.html
--- a/format/csv/csv.go
+++ b/format/csv/csv.go
@ -17,6 +17,7 @@ import (
 )

 //go:embed csv.jq
+//go:embed csv.md
 var csvFS embed.FS

 func init() {
--- a/format/csv/csv.md
+++ b/format/csv/csv.md
@ -0,0 +1,11 @@
+### TSV to CSV
+
+```sh
+$ fq -d csv -o comma="\t" tocsv file.tsv
+```
+
+### Convert rows to objects based on header row
+
+```sh
+$ fq -d csv '.[0] as $t | .[1:] | map(with_entries(.key = $t[.key]))' file.csv
+```
--- a/format/csv/testdata/tsv.fqtest
+++ b/format/csv/testdata/tsv.fqtest
@ -0,0 +1,29 @@
+/test:
+1	2	3
+4	5	6
+$ fq -d csv -o comma=\\t . test
+[
+  [
+    "1",
+    "2",
+    "3"
+  ],
+  [
+    "4",
+    "5",
+    "6"
+  ]
+]
+$ fq -d csv -o comma="\t" . test
+[
+  [
+    "1",
+    "2",
+    "3"
+  ],
+  [
+    "4",
+    "5",
+    "6"
+  ]
+]
--- a/format/format.go
+++ b/format/format.go
@ -86,6 +86,7 @@ const (
 	JSONL               = "jsonl"
 	MACHO               = "macho"
 	MACHO_FAT           = "macho_fat"
+	MARKDOWN            = "markdown"
 	MATROSKA            = "matroska"
 	MP3                 = "mp3"
 	MP3_FRAME           = "mp3_frame"
--- a/format/macho/macho.go
+++ b/format/macho/macho.go
@ -14,7 +14,7 @@ import (
 	"github.com/wader/fq/pkg/scalar"
 )

-//go:embed macho.jq
+//go:embed macho.md
 var machoFS embed.FS

 func init() {
@ -23,7 +23,6 @@ func init() {
 		Description: "Mach-O macOS executable",
 		Groups:      []string{format.PROBE},
 		DecodeFn:    machoDecode,
-		Functions:   []string{"_help"},
 	})
 	interp.RegisterFS(machoFS)
 }
--- a/format/macho/macho.jq
+++ b/format/macho/macho.jq
@ -1,9 +0,0 @@
-def _macho__help:
-  { notes: "Supports decoding vanilla and FAT Mach-O binaries.",
-    examples: [
-      {comment: "Select 64bit load segments", shell: "fq '.load_commands[] | select(.cmd==\"segment_64\")' file"}
-    ],
-    links: [
-      {url: "https://github.com/aidansteele/osx-abi-macho-file-format-reference"}
-    ]
-  };
--- a/format/macho/macho.md
+++ b/format/macho/macho.md
@ -0,0 +1,10 @@
+Supports decoding vanilla and FAT Mach-O binaries.
+
+### Select 64bit load segments
+
+```sh
+$ fq '.load_commands[] | select(.cmd=="segment_64")' file
+```
+
+### References
+- https://github.com/aidansteele/osx-abi-macho-file-format-reference
--- a/format/markdown/markdown.go
+++ b/format/markdown/markdown.go
@ -0,0 +1,319 @@
+package markdown
+
+import (
+	"embed"
+	"fmt"
+	"io"
+
+	"github.com/gomarkdown/markdown"
+	"github.com/gomarkdown/markdown/ast"
+	"github.com/wader/fq/format"
+	"github.com/wader/fq/pkg/bitio"
+	"github.com/wader/fq/pkg/decode"
+	"github.com/wader/fq/pkg/interp"
+	"github.com/wader/fq/pkg/scalar"
+)
+
+//go:embed markdown.jq
+var markdownFS embed.FS
+
+func init() {
+	interp.RegisterFormat(decode.Format{
+		Name:        format.MARKDOWN,
+		Description: "Markdown",
+		DecodeFn:    decodeMarkdown,
+		Functions:   []string{"_todisplay"},
+	})
+	interp.RegisterFS(markdownFS)
+}
+
+func decodeMarkdown(d *decode.D, _ any) any {
+	b, err := io.ReadAll(bitio.NewIOReader(d.RawLen(d.Len())))
+	if err != nil {
+		panic(err)
+	}
+
+	var s scalar.S
+	s.Actual = node(markdown.Parse(b, nil))
+	d.Value.V = &s
+	d.Value.Range.Len = d.Len()
+
+	return nil
+}
+
+func stringSlice[T string | []byte](ss []T) []any {
+	var vs []any
+	for _, e := range ss {
+		vs = append(vs, string(e))
+	}
+	return vs
+}
+
+func sliceMap[F, T any](vs []F, fn func(F) T) []T {
+	ts := make([]T, len(vs))
+	for i, v := range vs {
+		ts[i] = fn(v)
+	}
+	return ts
+}
+
+func intSlice[T ~int](ss []T) []any {
+	var vs []any
+	for _, e := range ss {
+		vs = append(vs, e)
+	}
+	return vs
+}
+
+func attr(v map[string]any, attr *ast.Attribute) {
+	if attr == nil {
+		return
+	}
+
+	v["id"] = string(attr.ID)
+
+	var as []any
+	for _, a := range attr.Attrs {
+		as = append(as, string(a))
+	}
+	v["attrs"] = as
+
+	var cs []any
+	for _, a := range attr.Classes {
+		cs = append(cs, string(a))
+	}
+	v["classes"] = cs
+}
+
+func leaf(v map[string]any, typ string, l ast.Leaf) {
+	v["type"] = typ
+	v["literal"] = string(l.Literal)
+
+	attr(v, l.Attribute)
+}
+
+func container(v map[string]any, typ string, c ast.Container) {
+	v["type"] = typ
+	v["literal"] = string(c.Literal)
+
+	var cs []any
+	children := c.GetChildren()
+	for _, n := range children {
+		cv := node(n)
+		if cv != nil {
+			cs = append(cs, node(n))
+		}
+	}
+	v["children"] = cs
+
+	attr(v, c.Attribute)
+}
+
+func listType(t ast.ListType) []any {
+	var vs []any
+
+	if t&ast.ListTypeOrdered == ast.ListTypeOrdered {
+		vs = append(vs, "ordered")
+	}
+	if t%ast.ListTypeOrdered == ast.ListTypeOrdered {
+		vs = append(vs, "ordered")
+	}
+	if t%ast.ListTypeDefinition == ast.ListTypeDefinition {
+		vs = append(vs, "definition")
+	}
+	if t%ast.ListTypeTerm == ast.ListTypeTerm {
+		vs = append(vs, "term")
+	}
+	if t%ast.ListItemContainsBlock == ast.ListItemContainsBlock {
+		vs = append(vs, "contains_block")
+	}
+	if t%ast.ListItemBeginningOfList == ast.ListItemBeginningOfList {
+		vs = append(vs, "beginning_of_list")
+	}
+	if t%ast.ListItemEndOfList == ast.ListItemEndOfList {
+		vs = append(vs, "end_of_list")
+	}
+
+	return vs
+}
+
+func node(n ast.Node) any {
+	v := map[string]any{}
+
+	switch n := n.(type) {
+	case *ast.Text:
+		if n.Leaf.Attribute == nil {
+			if len(n.Leaf.Literal) > 0 {
+				return string(n.Leaf.Literal)
+			}
+			// skip
+			return nil
+		}
+	case *ast.Softbreak:
+		leaf(v, "softbreak", n.Leaf)
+	case *ast.Hardbreak:
+		leaf(v, "hardbreak", n.Leaf)
+	case *ast.NonBlockingSpace:
+		leaf(v, "nbsp", n.Leaf)
+	case *ast.Emph:
+		container(v, "em", n.Container)
+	case *ast.Strong:
+		container(v, "strong", n.Container)
+	case *ast.Del:
+		container(v, "del", n.Container)
+	case *ast.BlockQuote:
+		container(v, "blockquote", n.Container)
+	case *ast.Aside:
+		container(v, "aside", n.Container)
+	case *ast.Link:
+		container(v, "link", n.Container)
+		v["destination"] = string(n.Destination)
+		v["title"] = string(n.Title)
+		v["note_id"] = n.NoteID
+		v["deferred_id"] = string(n.DeferredID)
+		v["additional_attributes"] = stringSlice(n.AdditionalAttributes)
+	case *ast.CrossReference:
+		container(v, "cross_reference", n.Container)
+		v["destination"] = string(n.Destination)
+	case *ast.Citation:
+		leaf(v, "citation", n.Leaf)
+		v["destination"] = stringSlice(n.Destination)
+		v["type"] = sliceMap(n.Type, func(v ast.CitationTypes) string {
+			switch v {
+			case ast.CitationTypeNone:
+				return "none"
+			case ast.CitationTypeSuppressed:
+				return "suppressed"
+			case ast.CitationTypeInformative:
+				return "informative"
+			case ast.CitationTypeNormative:
+				return "normative"
+			default:
+				return "unknown"
+			}
+		})
+		v["type"] = intSlice(n.Type)
+		v["suffix"] = stringSlice(n.Suffix)
+	case *ast.Image:
+		container(v, "image", n.Container)
+		v["destination"] = string(n.Destination)
+		v["title"] = string(n.Title)
+	case *ast.Code:
+		leaf(v, "code", n.Leaf)
+	case *ast.CodeBlock:
+		leaf(v, "code_block", n.Leaf)
+		v["is_fenced"] = n.IsFenced
+		v["info"] = string(n.Info)
+		if n.FenceChar != 0 {
+			v["fence_char"] = string(n.FenceChar)
+		}
+		v["fence_length"] = n.FenceLength
+		v["fence_offset"] = n.FenceOffset
+	case *ast.Caption:
+		container(v, "caption", n.Container)
+	case *ast.CaptionFigure:
+		container(v, "caption_figure", n.Container)
+		v["heading_id"] = n.HeadingID
+	case *ast.Document:
+		container(v, "document", n.Container)
+	case *ast.Paragraph:
+		container(v, "paragraph", n.Container)
+	case *ast.HTMLSpan:
+		leaf(v, "html_span", n.Leaf)
+	case *ast.HTMLBlock:
+		leaf(v, "html_block", n.Leaf)
+	case *ast.Heading:
+		container(v, "heading", n.Container)
+		v["level"] = n.Level
+		v["heading_id"] = n.HeadingID
+		v["is_titleblock"] = n.IsTitleblock
+		v["is_special"] = n.IsSpecial
+	case *ast.HorizontalRule:
+		leaf(v, "hr", n.Leaf)
+	case *ast.List:
+		container(v, "list", n.Container)
+		v["list_flags"] = listType(n.ListFlags)
+		v["tight"] = n.Tight
+		if n.BulletChar != 0 {
+			v["bullet_char"] = string(n.BulletChar)
+		}
+		if n.Delimiter != 0 {
+			v["delimiter"] = string(n.Delimiter)
+		}
+		v["start"] = n.Start
+		v["ref_link"] = string(n.RefLink)
+		v["is_footnotes_list"] = n.IsFootnotesList
+	case *ast.ListItem:
+		container(v, "list_item", n.Container)
+		v["list_flags"] = listType(n.ListFlags)
+		v["tight"] = n.Tight
+		if n.BulletChar != 0 {
+			v["bullet_char"] = string(n.BulletChar)
+		}
+		if n.Delimiter != 0 {
+			v["delimiter"] = string(n.Delimiter)
+		}
+		v["ref_link"] = string(n.RefLink)
+		v["is_footnotes_list"] = n.IsFootnotesList
+	case *ast.Table:
+		container(v, "table", n.Container)
+	case *ast.TableCell:
+		container(v, "table_cell", n.Container)
+		v["is_header"] = n.IsHeader
+		v["align"] = n.Align.String()
+		v["col_span"] = n.ColSpan
+	case *ast.TableHeader:
+		container(v, "table_header", n.Container)
+	case *ast.TableBody:
+		container(v, "table_body", n.Container)
+	case *ast.TableRow:
+		container(v, "table_row", n.Container)
+	case *ast.TableFooter:
+		container(v, "table_footer", n.Container)
+	case *ast.Math:
+		leaf(v, "math", n.Leaf)
+	case *ast.MathBlock:
+		container(v, "math_block", n.Container)
+	case *ast.DocumentMatter:
+		container(v, "document_matter", n.Container)
+		v["matter"] = func(v ast.DocumentMatters) string {
+			switch v {
+			case ast.DocumentMatterNone:
+				return "none"
+			case ast.DocumentMatterFront:
+				return "front"
+			case ast.DocumentMatterMain:
+				return "main"
+			case ast.DocumentMatterBack:
+				return "back"
+			default:
+				return "unknown"
+			}
+		}(n.Matter)
+	case *ast.Callout:
+		leaf(v, "callout", n.Leaf)
+		v["id"] = string(n.ID)
+	case *ast.Index:
+		leaf(v, "index", n.Leaf)
+		v["primary"] = n.Primary
+		v["item"] = string(n.Item)
+		v["subitem"] = string(n.Subitem)
+		v["id"] = n.ID
+	case *ast.Subscript:
+		leaf(v, "subscript", n.Leaf)
+	case *ast.Superscript:
+		leaf(v, "superscript", n.Leaf)
+	case *ast.Footnotes:
+		container(v, "footnotes", n.Container)
+	default:
+		panic(fmt.Sprintf("unknown node %T", node))
+	}
+
+	for k, e := range v {
+		if s, ok := e.(string); ok && s == "" {
+			delete(v, k)
+		}
+	}
+
+	return v
+}
--- a/format/markdown/markdown.jq
+++ b/format/markdown/markdown.jq
@ -0,0 +1,52 @@
+def _markdown__todisplay: tovalue;
+
+def word_break($width):
+  def _f($a; $acc; $l):
+    ( $a[0] as $w
+    | ($w // "" | length) as $wl
+    | if $w == null then $acc
+      elif ($l + $wl) >= $width then
+        ( $acc
+        , _f($a[1:]; [$w]; $wl)
+        )
+      else _f($a[1:]; $acc+[$w]; $l+$wl)
+      end
+    );
+  ( [_f([splits("\\s{1,}")]; []; 0)]
+  | map(join(" "))
+  );
+
+def _markdown_to_text($width; $header_depth):
+  def lb: if $width > 0 then word_break($width) | join("\n") end;
+  def _f($pln):
+    if type == "string" then gsub("\n"; " ")
+    elif .type == "document" then .children[] | _f("\n\n")
+    elif .type == "heading" then "#" * (.level+$header_depth), " ", (.children[] | _f("\n\n")), "\n"
+    elif .type == "paragraph" then
+      ( ( [.children[] | _f("\n\n")]
+        | join("")
+        | lb
+        )
+      , $pln
+      )
+    elif .type == "link" then
+      ( ( [ .children[]
+          | _f("")
+          ]
+        | join("")
+        ) as $text
+      | $text
+      , if $text != .destination then " (", .destination, ")"
+        else empty
+        end
+      )
+    elif .type == "code_block" then "\n", ("  ", .literal | split("\n") | join("\n  ")), "\n"
+    elif .type == "code" then .literal
+    elif .type == "list" then (.children[] | _f("\n\n")), "\n" # TODO: delim
+    elif .type == "list_item" then .bullet_char, " ", (.children[] | _f("\n"))
+    elif .type == "html_span" then .literal | gsub("<br>"; "\n") # TODO: more?
+    else empty
+    end;
+  [_f("\n\n")] | join("");
+def _markdown_to_text:
+  _markdown_to_text(-1; 0);
--- a/format/markdown/testdata/test.fqtest
+++ b/format/markdown/testdata/test.fqtest
@ -0,0 +1,316 @@
+$ fq -d markdown . test.md
+{
+  "children": [
+    {
+      "children": [
+        "Before"
+      ],
+      "type": "paragraph"
+    },
+    {
+      "children": [
+        "header 1"
+      ],
+      "is_special": false,
+      "is_titleblock": false,
+      "level": 1,
+      "type": "heading"
+    },
+    {
+      "children": [
+        "Paragraph with ",
+        {
+          "children": [
+            "bold"
+          ],
+          "type": "strong"
+        },
+        " and ",
+        {
+          "children": [
+            "italic"
+          ],
+          "type": "em"
+        },
+        "\non\nmultiple\nlines."
+      ],
+      "type": "paragraph"
+    },
+    {
+      "children": [
+        {
+          "children": [
+            "Some citation"
+          ],
+          "type": "paragraph"
+        }
+      ],
+      "type": "blockquote"
+    },
+    {
+      "children": [
+        "A footnote",
+        {
+          "additional_attributes": [],
+          "children": [
+            "^1"
+          ],
+          "destination": "footnote1",
+          "note_id": 0,
+          "type": "link"
+        },
+        " and this also",
+        {
+          "additional_attributes": [],
+          "children": [
+            "^note"
+          ],
+          "destination": "footnote2",
+          "note_id": 0,
+          "type": "link"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "children": [
+        "header 2"
+      ],
+      "is_special": false,
+      "is_titleblock": false,
+      "level": 2,
+      "type": "heading"
+    },
+    {
+      "fence_length": 0,
+      "fence_offset": 0,
+      "info": "jq",
+      "is_fenced": true,
+      "literal": "code\nblock\n",
+      "type": "code_block"
+    },
+    {
+      "fence_length": 0,
+      "fence_offset": 0,
+      "is_fenced": false,
+      "literal": "also\ncode\n",
+      "type": "code_block"
+    },
+    {
+      "children": [
+        "header 3"
+      ],
+      "is_special": false,
+      "is_titleblock": false,
+      "level": 3,
+      "type": "heading"
+    },
+    {
+      "children": [
+        "Some text with ",
+        {
+          "literal": "code",
+          "type": "code"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "children": [
+        "header 4"
+      ],
+      "is_special": false,
+      "is_titleblock": false,
+      "level": 4,
+      "type": "heading"
+    },
+    {
+      "children": [
+        "Some text ",
+        {
+          "additional_attributes": [],
+          "children": [
+            "with a link"
+          ],
+          "destination": "http://host/path",
+          "note_id": 0,
+          "type": "link"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "children": [
+        "An image ",
+        {
+          "children": [
+            "img alt text"
+          ],
+          "destination": "path/image.png",
+          "type": "image"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "children": [
+        "header 5"
+      ],
+      "is_special": false,
+      "is_titleblock": false,
+      "level": 5,
+      "type": "heading"
+    },
+    {
+      "children": [
+        {
+          "bullet_char": "-",
+          "children": [
+            {
+              "children": [
+                "list of"
+              ],
+              "type": "paragraph"
+            }
+          ],
+          "delimiter": ".",
+          "is_footnotes_list": false,
+          "list_flags": [],
+          "tight": false,
+          "type": "list_item"
+        },
+        {
+          "bullet_char": "-",
+          "children": [
+            {
+              "children": [
+                "things"
+              ],
+              "type": "paragraph"
+            }
+          ],
+          "delimiter": ".",
+          "is_footnotes_list": false,
+          "list_flags": [],
+          "tight": false,
+          "type": "list_item"
+        }
+      ],
+      "delimiter": ".",
+      "is_footnotes_list": false,
+      "list_flags": [],
+      "start": 0,
+      "tight": true,
+      "type": "list"
+    },
+    {
+      "children": [
+        "a table"
+      ],
+      "type": "paragraph"
+    },
+    {
+      "children": [
+        {
+          "children": [
+            {
+              "children": [
+                {
+                  "children": [
+                    "a"
+                  ],
+                  "col_span": 0,
+                  "is_header": true,
+                  "type": "table_cell"
+                },
+                {
+                  "children": [
+                    "b"
+                  ],
+                  "col_span": 0,
+                  "is_header": true,
+                  "type": "table_cell"
+                },
+                {
+                  "children": [
+                    "c"
+                  ],
+                  "col_span": 0,
+                  "is_header": true,
+                  "type": "table_cell"
+                }
+              ],
+              "type": "table_row"
+            }
+          ],
+          "type": "table_header"
+        },
+        {
+          "children": [
+            {
+              "children": [
+                {
+                  "children": [
+                    "1"
+                  ],
+                  "col_span": 0,
+                  "is_header": false,
+                  "type": "table_cell"
+                },
+                {
+                  "children": [
+                    "2"
+                  ],
+                  "col_span": 0,
+                  "is_header": false,
+                  "type": "table_cell"
+                },
+                {
+                  "children": [
+                    "3"
+                  ],
+                  "col_span": 0,
+                  "is_header": false,
+                  "type": "table_cell"
+                }
+              ],
+              "type": "table_row"
+            }
+          ],
+          "type": "table_body"
+        }
+      ],
+      "type": "table"
+    },
+    {
+      "children": [
+        "header 6"
+      ],
+      "is_special": false,
+      "is_titleblock": false,
+      "level": 6,
+      "type": "heading"
+    },
+    {
+      "children": [
+        "Some text with line ",
+        {
+          "literal": "<br>",
+          "type": "html_span"
+        },
+        " break and ",
+        {
+          "literal": "<b>",
+          "type": "html_span"
+        },
+        "bold",
+        {
+          "literal": "</b>",
+          "type": "html_span"
+        }
+      ],
+      "type": "paragraph"
+    }
+  ],
+  "type": "document"
+}
--- a/format/markdown/testdata/test.md
+++ b/format/markdown/testdata/test.md
@ -0,0 +1,50 @@
+Before
+
+# header 1
+
+Paragraph with **bold** and *italic*
+on
+multiple
+lines.
+
+> Some citation
+
+A footnote[^1] and this also[^note]
+
+## header 2
+
+```jq
+code
+block
+```
+
+    also
+    code
+
+### header 3
+
+Some text with `code`
+
+#### header 4
+
+Some text [with a link](http://host/path)
+
+An image ![img alt text](path/image.png)
+
+##### header 5
+
+- list of
+- things
+
+a table
+
+| a   | b   | c   |
+| --- | --- | --- |
+| 1   | 2   | 3   |
+
+###### header 6
+
+Some text with line <br> break and <b>bold</b>
+
+[^1]: footnote1
+[^note]: footnote2
--- a/format/matroska/matroska.go
+++ b/format/matroska/matroska.go
@ -27,6 +27,7 @@ import (
 )

 //go:embed matroska.jq
+//go:embed matroska.md
 var matroskaFS embed.FS

 var aacFrameFormat decode.Group
@ -78,7 +79,6 @@ func init() {
 			{Names: []string{format.VP9_CFM}, Group: &vp9CFMFormat},
 			{Names: []string{format.VP9_FRAME}, Group: &vp9FrameFormat},
 		},
-		Functions: []string{"_help"},
 	})
 	interp.RegisterFS(matroskaFS)

--- a/format/matroska/matroska.jq
+++ b/format/matroska/matroska.jq
@ -12,17 +12,3 @@ def matroska_path:
    | format_root
    | matroska_path($c)
    );
-
-def _matroska__help:
-  { examples: [
-      {comment: "Lookup element decode value using `matroska_path`", expr: "matroska_path(\".Segment.Tracks[0)\""},
-      {comment: "Return `matroska_path` string for a box decode value", expr: "grep_by(.id == \"Tracks\") | matroska_path"}
-    ],
-    links: [
-      {url: "https://tools.ietf.org/html/draft-ietf-cellar-ebml-00"},
-      {url: "https://matroska.org/technical/specs/index.html"},
-      {url: "https://www.matroska.org/technical/basics.html"},
-      {url: "https://www.matroska.org/technical/codec_specs.html"},
-      {url: "https://wiki.xiph.org/MatroskaOpus"}
-    ]
-  };
--- a/format/matroska/matroska.md
+++ b/format/matroska/matroska.md
@ -0,0 +1,18 @@
+### Lookup element path using `matroska_path`
+
+```sh
+$ fq 'matroska_path(".Segment.Tracks[0)")' file.mkv
+```
+
+### Get element path using `matroska_path`
+
+```sh
+$ fq 'grep_by(.id == "Tracks") | matroska_path' file.mkv
+```
+
+### References
+- https://tools.ietf.org/html/draft-ietf-cellar-ebml-00
+- https://matroska.org/technical/specs/index.html
+- https://www.matroska.org/technical/basics.html
+- https://www.matroska.org/technical/codec_specs.html
+- https://wiki.xiph.org/MatroskaOpus
--- a/format/mp4/boxes.go
+++ b/format/mp4/boxes.go
@ -62,21 +62,118 @@ var subTypeNames = scalar.StrToDescription{
 }

 var dataFormatNames = scalar.StrToDescription{
+	// additional codecs
 	"apch": "Apple ProRes 422 High Quality",
 	"apcn": "Apple ProRes 422 Standard Definition",
 	"apcs": "Apple ProRes 422 LT",
 	"apco": "Apple ProRes 422 Proxy",
 	"ap4h": "Apple ProRes 4444",
-	"fLaC": "Fres Lossless Audio Codec",
-	"Opus": "Xiph Opus",
-	"vp09": "VP9",
-	"avc1": "Advanced Video Coding / H.264 / MPEG-4 Part 10",
-	"hev1": "High Efficiency Video Coding / H.265 / MPEG-H Part 2",
-	"hvc1": "High Efficiency Video Coding / H.265 / MPEG-H Part 2",
-	"av01": "AV1",
-	"mp4a": "MPEG Audio",
-	"mp4v": "MPEG Video",
 	"jpeg": "JPEG Image",
+
+	// codecs from https://mp4ra.org/
+	"3gvo": "3GPP Video Orientation",
+	"a3d1": "Multiview Video Coding",
+	"a3d2": "Multiview Video Coding",
+	"a3d3": "Multiview Video Coding",
+	"a3d4": "Multiview Video Coding",
+	"a3ds": "Auro-Cx 3D audio",
+	"ac-3": "AC-3 audio",
+	"ac-4": "AC-4 audio",
+	"alac": "Apple lossless audio codec",
+	"alaw": "a-Law",
+	"av01": "AV1 video",
+	"avc1": "Advanced Video Coding",
+	"avc2": "Advanced Video Coding",
+	"avc3": "Advanced Video Coding",
+	"avc4": "Advanced Video Coding",
+	"avcp": "Advanced Video Coding Parameters",
+	"dra1": "DRA Audio",
+	"drac": "Dirac Video Coder",
+	"dts-": "Dependent base layer for DTS layered audio",
+	"dts+": "Enhancement layer for DTS layered audio",
+	"dtsc": "DTS Coherent Acoustics audio",
+	"dtse": "DTS Express low bit rate audio, also known as DTS LBR",
+	"dtsh": "DTS-HD High Resolution Audio",
+	"dtsl": "DTS-HD Master Audio",
+	"dtsx": "DTS:X",
+	"dvav": "AVC-based “Dolby Vision”",
+	"dvhe": "HEVC-based “Dolby Vision”",
+	"ec-3": "Enhanced AC-3 audio",
+	"enca": "Encrypted/Protected audio",
+	"encf": "Encrypted/Protected font",
+	"encm": "Encrypted/Protected metadata stream",
+	"encs": "Encrypted Systems stream",
+	"enct": "Encrypted Text",
+	"encv": "Encrypted/protected video",
+	"fdp ": "File delivery hints",
+	"fLaC": "Fres Lossless Audio Codec",
+	"g719": "ITU-T Recommendation G.719 (2008)",
+	"g726": "ITU-T Recommendation G.726 (1990)",
+	"hev1": "High Efficiency Video Coding",
+	"hvc1": "High Efficiency Video Coding",
+	"hvt1": "High Efficiency Video Coding",
+	"ixse": "DVB Track Level Index Track",
+	"lhe1": "Layered High Efficiency Video Coding",
+	"lht1": "Layered High Efficiency Video Coding",
+	"lhv1": "Layered High Efficiency Video Coding",
+	"m2ts": "MPEG-2 transport stream for DMB",
+	"m4ae": "MPEG-4 Audio Enhancement MP4v1/2",
+	"mett": "Text timed metadata that is not XML",
+	"metx": "XML timed metadata",
+	"mha1": "MPEG-H Audio (single stream, uncapsulated)",
+	"mha2": "MPEG-H Audio (multi-stream, unencapsulated)",
+	"mhm1": "MPEG-H Audio (single stream, MHAS encapsulated)",
+	"mhm2": "MPEG-H Audio (multi-stream, MHAS encapsulated)",
+	"mjp2": "Motion JPEG 2000",
+	"mlix": "DVB Movie level index track",
+	"mlpa": "MLP Audio",
+	"mp4a": "MPEG-4 Audio",
+	"mp4s": "MPEG-4 Systems",
+	"mp4v": "MPEG-4 Visual",
+	"mvc1": "Multiview coding",
+	"mvc2": "Multiview coding",
+	"mvc3": "Multiview coding",
+	"mvc4": "Multiview coding",
+	"mvd1": "Multiview coding",
+	"mvd2": "Multiview coding",
+	"mvd3": "Multiview coding",
+	"mvd4": "Multiview coding",
+	"oksd": "OMA Keys",
+	"Opus": "Opus audio coding",
+	"pm2t": "Protected MPEG-2 Transport",
+	"prtp": "Protected RTP Reception",
+	"raw ": "Uncompressed audio",
+	"resv": "Restricted Video",
+	"rm2t": "MPEG-2 Transport Reception",
+	"rrtp": "RTP reception",
+	"rsrp": "SRTP Reception",
+	"rtmd": "Real Time Metadata Sample Entry(XAVC Format)",
+	"rtp ": "RTP Hints",
+	"s263": "ITU H.263 video (3GPP format)",
+	"samr": "Narrowband AMR voice",
+	"sawb": "Wideband AMR voice",
+	"sawp": "Extended AMR-WB (AMR-WB+)",
+	"sevc": "EVRC Voice",
+	"sm2t": "MPEG-2 Transport Server",
+	"sqcp": "13K Voice",
+	"srtp": "SRTP Hints",
+	"ssmv": "SMV Voice",
+	"STGS": "Subtitle Sample Entry (HMMP)",
+	"stpp": "Subtitles (Timed Text)",
+	"svc1": "Scalable Video Coding",
+	"svc2": "Scalable Video Coding",
+	"svcM": "SVC Metadata",
+	"tc64": "64 bit timecode samples",
+	"tmcd": "32 bit timecode samples",
+	"twos": "Uncompressed 16-bit audio",
+	"tx3g": "Timed Text stream",
+	"ulaw": "Samples have been compressed using uLaw 2:1.",
+	"unid": "Dynamic Range Control (DRC) data",
+	"urim": "Binary timed metadata identified by URI",
+	"vc-1": "SMPTE VC-1",
+	"vp08": "VP8 video",
+	"vp09": "VP9 video",
+	"wvtt": "WebVTT",
 }

 var (
--- a/format/mp4/mp4.go
+++ b/format/mp4/mp4.go
@ -26,6 +26,7 @@ import (
 )

 //go:embed mp4.jq
+//go:embed mp4.md
 var mp4FS embed.FS

 var aacFrameFormat decode.Group
@ -55,7 +56,7 @@ var vpxCCRFormat decode.Group
 func init() {
 	interp.RegisterFormat(decode.Format{
 		Name:        format.MP4,
-		Description: "ISOBMFF MPEG-4 part 12 and similar",
+		Description: "ISOBMFF, QuickTime and similar",
 		Groups: []string{
 			format.PROBE,
 			format.IMAGE, // avif
@ -90,7 +91,6 @@ func init() {
 			{Names: []string{format.VP9_FRAME}, Group: &vp9FrameFormat},
 			{Names: []string{format.VPX_CCR}, Group: &vpxCCRFormat},
 		},
-		Functions: []string{"_help"},
 	})
 	interp.RegisterFS(mp4FS)
 }
--- a/format/mp4/mp4.jq
+++ b/format/mp4/mp4.jq
@ -12,15 +12,3 @@ def mp4_path:
  | format_root
  | mp4_path($c)
  );
-
-def _mp4__help:
-  { notes: "Support `mp4_path`",
-    examples: [
-      {comment: "Lookup box decode value using `mp4_path`", expr: "mp4_path(\".moov.trak[1]\")"},
-      {comment: "Return `mp4_path` string for a box decode value", expr: "grep_by(.type == \"trak\") | mp4_path"}
-    ],
-    links: [
-      {title: "ISO/IEC base media file format (MPEG-4 Part 12)", url: "https://en.wikipedia.org/wiki/ISO/IEC_base_media_file_format"},
-      {title: "Quicktime file format", url: "https://developer.apple.com/standards/qtff-2001.pdf"}
-    ]
-  };
--- a/format/mp4/mp4.md
+++ b/format/mp4/mp4.md
@ -0,0 +1,36 @@
+### `mp4_path($path)` - Lookup mp4 box using a mp4 box path.
+
+```sh
+# <decode value box> | mp4_path($path) -> <decode value box>
+$ fq 'mp4_path(".moov.trak[1]")' file.mp4
+```
+
+### `mp4_path` - Return mp4 box path for a decode value box.
+
+```sh
+# <decode value box> | mp4_path -> string
+$ fq 'grep_by(.type == "trak") | mp4_path' file.mp4
+```
+
+### Force decode a single box
+
+```sh
+$ fq -n '"AAAAHGVsc3QAAAAAAAAAAQAAADIAAAQAAAEAAA==" | frombase64 | mp4({force:true}) | d'
+```
+
+### Don't decode samples and manually decode first sample for first track as a `aac_frame`
+
+```sh
+$ fq -o decode_samples=false '.tracks[0].samples[0] | aac_frame | d' file.mp4
+```
+
+### Entries for first edit list as values
+
+```sh
+$ fq 'first(grep_by(.type=="elst").entries) | tovalue' file.mp4
+```
+
+### References
+
+- [ISO/IEC base media file format (MPEG-4 Part 12)](https://en.wikipedia.org/wiki/ISO/IEC_base_media_file_format)
+- [Quicktime file format](https://developer.apple.com/standards/qtff-2001.pdf)
--- a/format/mp4/testdata/aac.fqtest
+++ b/format/mp4/testdata/aac.fqtest
@ -192,7 +192,7 @@ $ fq -d mp4 dv aac.mp4
     |                                               |                |                          boxes[0:1]: 0x437-0x490.7 (90)
     |                                               |                |                            [0]{}: box 0x437-0x490.7 (90)
 0x430|                     00 00 00 5a               |       ...Z     |                              size: 90 0x437-0x43a.7 (4)
-0x430|                                 6d 70 34 61   |           mp4a |                              type: "mp4a" (MPEG Audio) 0x43b-0x43e.7 (4)
+0x430|                                 6d 70 34 61   |           mp4a |                              type: "mp4a" (MPEG-4 Audio) 0x43b-0x43e.7 (4)
 0x430|                                             00|               .|                              reserved: raw bits 0x43f-0x444.7 (6)
 0x440|00 00 00 00 00                                 |.....           |
 0x440|               00 01                           |     ..         |                              data_reference_index: 1 0x445-0x446.7 (2)
@ -429,4 +429,4 @@ $ fq -d mp4 dv aac.mp4
 0x290|b4                                             |.               |          [1]: raw bits byte_align 0x290.6-0x290.7 (0.2)
 0x290|   70                                          | p              |          [2]: raw bits data 0x291-0x291.7 (1)
     |                                               |                |      id: 1 0x59d-NA (0)
-     |                                               |                |      data_foramt: "mp4a" (MPEG Audio) 0x59d-NA (0)
+     |                                               |                |      data_foramt: "mp4a" (MPEG-4 Audio) 0x59d-NA (0)
--- a/format/mp4/testdata/av1.fqtest
+++ b/format/mp4/testdata/av1.fqtest
@ -178,7 +178,7 @@ $ fq -d mp4 dv av1.mp4
      |                                               |                |                          boxes[0:1]: 0x1369-0x13f3.7 (139)
      |                                               |                |                            [0]{}: box 0x1369-0x13f3.7 (139)
 0x1360|                           00 00 00 8b         |         ....   |                              size: 139 0x1369-0x136c.7 (4)
-0x1360|                                       61 76 30|             av0|                              type: "av01" (AV1) 0x136d-0x1370.7 (4)
+0x1360|                                       61 76 30|             av0|                              type: "av01" (AV1 video) 0x136d-0x1370.7 (4)
 0x1370|31                                             |1               |
 0x1370|   00 00 00 00 00 00                           | ......         |                              reserved: raw bits 0x1371-0x1376.7 (6)
 0x1370|                     00 01                     |       ..       |                              data_reference_index: 1 0x1377-0x1378.7 (2)
@ -341,4 +341,4 @@ $ fq -d mp4 dv av1.mp4
 0x0050|f6 0a 4f ae f3 fe ec e7 30 4f 3f 13 9c 75 c9 6a|..O.....0O?..u.j|            data: raw bits 0x50-0x11bf.7 (4464)
 *     |until 0x11bf.7 (4464)                          |                |
      |                                               |                |      id: 1 0x14b2-NA (0)
-      |                                               |                |      data_foramt: "av01" (AV1) 0x14b2-NA (0)
+      |                                               |                |      data_foramt: "av01" (AV1 video) 0x14b2-NA (0)
--- a/format/mp4/testdata/avc.fqtest
+++ b/format/mp4/testdata/avc.fqtest
@ -196,7 +196,7 @@ $ fq -d mp4 dv avc.mp4
       |                                               |                |                          boxes[0:1]: 0xf2a-0xfd9.7 (176)
       |                                               |                |                            [0]{}: box 0xf2a-0xfd9.7 (176)
 0x00f20|                              00 00 00 b0      |          ....  |                              size: 176 0xf2a-0xf2d.7 (4)
-0x00f20|                                          61 76|              av|                              type: "avc1" (Advanced Video Coding / H.264 / MPEG-4 Part 10) 0xf2e-0xf31.7 (4)
+0x00f20|                                          61 76|              av|                              type: "avc1" (Advanced Video Coding) 0xf2e-0xf31.7 (4)
 0x00f30|63 31                                          |c1              |
 0x00f30|      00 00 00 00 00 00                        |  ......        |                              reserved: raw bits 0xf32-0xf37.7 (6)
 0x00f30|                        00 01                  |        ..      |                              data_reference_index: 1 0xf38-0xf39.7 (2)
@ -514,4 +514,4 @@ $ fq -d mp4 dv avc.mp4
 0x00d50|79 0a ff 01 f9 2d 04 d3 29 fe 4d 76 42 26 f6 cd|y....-..).MvB&..|
 *      |until 0xd80.7 (51)                             |                |
       |                                               |                |      id: 1 0x10e0-NA (0)
-       |                                               |                |      data_foramt: "avc1" (Advanced Video Coding / H.264 / MPEG-4 Part 10) 0x10e0-NA (0)
+       |                                               |                |      data_foramt: "avc1" (Advanced Video Coding) 0x10e0-NA (0)
--- a/format/mp4/testdata/dash.fqtest
+++ b/format/mp4/testdata/dash.fqtest
@ -204,7 +204,7 @@ $ fq -d mp4 dv dash_audio_init.mp4
     |                                               |                |                          boxes[0:1]: 0x218-0x265.7 (78)
     |                                               |                |                            [0]{}: box 0x218-0x265.7 (78)
 0x210|                        00 00 00 4e            |        ...N    |                              size: 78 0x218-0x21b.7 (4)
-0x210|                                    6d 70 34 61|            mp4a|                              type: "mp4a" (MPEG Audio) 0x21c-0x21f.7 (4)
+0x210|                                    6d 70 34 61|            mp4a|                              type: "mp4a" (MPEG-4 Audio) 0x21c-0x21f.7 (4)
 0x220|00 00 00 00 00 00                              |......          |                              reserved: raw bits 0x220-0x225.7 (6)
 0x220|                  00 01                        |      ..        |                              data_reference_index: 1 0x226-0x227.7 (2)
 0x220|                        00 00                  |        ..      |                              version: 0 0x228-0x229.7 (2)
@ -348,7 +348,7 @@ $ fq -d mp4 dv dash_audio_init.mp4
     |                                               |                |  tracks[0:1]: 0x330-NA (0)
     |                                               |                |    [0]{}: track 0x330-NA (0)
     |                                               |                |      id: 1 0x330-NA (0)
-     |                                               |                |      data_foramt: "mp4a" (MPEG Audio) 0x330-NA (0)
+     |                                               |                |      data_foramt: "mp4a" (MPEG-4 Audio) 0x330-NA (0)
     |                                               |                |      samples[0:0]: 0x330-NA (0)
 $ fq -d mp4 dv dash_audio_1.m4s
     |00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f|0123456789abcdef|.{}: dash_audio_1.m4s (mp4) 0x0-0x4eb.7 (1260)
@ -696,7 +696,7 @@ $ fq -d mp4 dv dash_video_init.mp4
      |                                               |                |                          boxes[0:1]: 0x21c-0x2a2.7 (135)
      |                                               |                |                            [0]{}: box 0x21c-0x2a2.7 (135)
 0x0210|                                    00 00 00 87|            ....|                              size: 135 0x21c-0x21f.7 (4)
-0x0220|61 76 63 31                                    |avc1            |                              type: "avc1" (Advanced Video Coding / H.264 / MPEG-4 Part 10) 0x220-0x223.7 (4)
+0x0220|61 76 63 31                                    |avc1            |                              type: "avc1" (Advanced Video Coding) 0x220-0x223.7 (4)
 0x0220|            00 00 00 00 00 00                  |    ......      |                              reserved: raw bits 0x224-0x229.7 (6)
 0x0220|                              00 01            |          ..    |                              data_reference_index: 1 0x22a-0x22b.7 (2)
 0x0220|                                    00 00      |            ..  |                              version: 0 0x22c-0x22d.7 (2)
@ -886,7 +886,7 @@ $ fq -d mp4 dv dash_video_init.mp4
      |                                               |                |  tracks[0:1]: 0x333-NA (0)
      |                                               |                |    [0]{}: track 0x333-NA (0)
      |                                               |                |      id: 1 0x333-NA (0)
-      |                                               |                |      data_foramt: "avc1" (Advanced Video Coding / H.264 / MPEG-4 Part 10) 0x333-NA (0)
+      |                                               |                |      data_foramt: "avc1" (Advanced Video Coding) 0x333-NA (0)
      |                                               |                |      samples[0:0]: 0x333-NA (0)
 $ fq -d mp4 dv dash_video_1.m4s
      |00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f|0123456789abcdef|.{}: dash_video_1.m4s (mp4) 0x0-0x1fd0.7 (8145)
--- a/format/mp4/testdata/decode_samples.fqtest
+++ b/format/mp4/testdata/decode_samples.fqtest
@ -14,4 +14,4 @@ $ fq -o decode_samples=false -d mp4 '.tracks | dv' aac.mp4
 0x280|                                       01 18 81|             ...|      [3]: raw bits sample 0x28d-0x291.7 (5)
 0x290|b4 70                                          |.p              |
     |                                               |                |    id: 1 0x59d-NA (0)
-     |                                               |                |    data_foramt: "mp4a" (MPEG Audio) 0x59d-NA (0)
+     |                                               |                |    data_foramt: "mp4a" (MPEG-4 Audio) 0x59d-NA (0)
--- a/format/mp4/testdata/fragmented.fqtest
+++ b/format/mp4/testdata/fragmented.fqtest
@ -154,7 +154,7 @@ $ fq -d mp4 dv fragmented.mp4
       |                                               |                |                          boxes[0:1]: 0x1a9-0x23f.7 (151)
       |                                               |                |                            [0]{}: box 0x1a9-0x23f.7 (151)
 0x001a0|                           00 00 00 97         |         ....   |                              size: 151 0x1a9-0x1ac.7 (4)
-0x001a0|                                       61 76 63|             avc|                              type: "avc1" (Advanced Video Coding / H.264 / MPEG-4 Part 10) 0x1ad-0x1b0.7 (4)
+0x001a0|                                       61 76 63|             avc|                              type: "avc1" (Advanced Video Coding) 0x1ad-0x1b0.7 (4)
 0x001b0|31                                             |1               |
 0x001b0|   00 00 00 00 00 00                           | ......         |                              reserved: raw bits 0x1b1-0x1b6.7 (6)
 0x001b0|                     00 01                     |       ..       |                              data_reference_index: 1 0x1b7-0x1b8.7 (2)
@ -411,7 +411,7 @@ $ fq -d mp4 dv fragmented.mp4
       |                                               |                |                          boxes[0:1]: 0x391-0x3fe.7 (110)
       |                                               |                |                            [0]{}: box 0x391-0x3fe.7 (110)
 0x00390|   00 00 00 6e                                 | ...n           |                              size: 110 0x391-0x394.7 (4)
-0x00390|               6d 70 34 61                     |     mp4a       |                              type: "mp4a" (MPEG Audio) 0x395-0x398.7 (4)
+0x00390|               6d 70 34 61                     |     mp4a       |                              type: "mp4a" (MPEG-4 Audio) 0x395-0x398.7 (4)
 0x00390|                           00 00 00 00 00 00   |         ...... |                              reserved: raw bits 0x399-0x39e.7 (6)
 0x00390|                                             00|               .|                              data_reference_index: 1 0x39f-0x3a0.7 (2)
 0x003a0|01                                             |.               |
@ -1167,7 +1167,7 @@ $ fq -d mp4 dv fragmented.mp4
 0x02240|86 f8 14 d8 53 23 af ff f2 50 06 7f 30 02 17 55|....S#...P..0..U|
 *      |until 0x2af4.7 (2234)                          |                |
       |                                               |                |      id: 1 0x2bb4-NA (0)
-       |                                               |                |      data_foramt: "avc1" (Advanced Video Coding / H.264 / MPEG-4 Part 10) 0x2bb4-NA (0)
+       |                                               |                |      data_foramt: "avc1" (Advanced Video Coding) 0x2bb4-NA (0)
       |                                               |                |    [1]{}: track 0x13e0-0x2bb3.7 (6100)
       |                                               |                |      samples[0:6]: 0x13e0-0x2af9.7 (5914)
       |00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f|0123456789abcdef|        [0][0:4]: sample (aac_frame) 0x13e0-0x14ad.7 (206)
@ -1270,4 +1270,4 @@ $ fq -d mp4 dv fragmented.mp4
 0x02af0|                        b4                     |        .       |          [1]: raw bits byte_align 0x2af8.6-0x2af8.7 (0.2)
 0x02af0|                           70                  |         p      |          [2]: raw bits data 0x2af9-0x2af9.7 (1)
       |                                               |                |      id: 2 0x2bb4-NA (0)
-       |                                               |                |      data_foramt: "mp4a" (MPEG Audio) 0x2bb4-NA (0)
+       |                                               |                |      data_foramt: "mp4a" (MPEG-4 Audio) 0x2bb4-NA (0)
--- a/format/mp4/testdata/hevc.fqtest
+++ b/format/mp4/testdata/hevc.fqtest
@ -196,7 +196,7 @@ $ fq -d mp4 dv hevc.mp4
      |                                               |                |                          boxes[0:1]: 0xa2a-0x13dc.7 (2483)
      |                                               |                |                            [0]{}: box 0xa2a-0x13dc.7 (2483)
 0x0a20|                              00 00 09 b3      |          ....  |                              size: 2483 0xa2a-0xa2d.7 (4)
-0x0a20|                                          68 65|              he|                              type: "hev1" (High Efficiency Video Coding / H.265 / MPEG-H Part 2) 0xa2e-0xa31.7 (4)
+0x0a20|                                          68 65|              he|                              type: "hev1" (High Efficiency Video Coding) 0xa2e-0xa31.7 (4)
 0x0a30|76 31                                          |v1              |
 0x0a30|      00 00 00 00 00 00                        |  ......        |                              reserved: raw bits 0xa32-0xa37.7 (6)
 0x0a30|                        00 01                  |        ..      |                              data_reference_index: 1 0xa38-0xa39.7 (2)
@ -636,4 +636,4 @@ $ fq -d mp4 dv hevc.mp4
 0x0040|fd a9 78 83 ff fb 75 6c 0b 3f ff 94 ce 7f aa fe|..x...ul.?......|
 *     |until 0x880.7 (2127)                           |                |
      |                                               |                |      id: 1 0x149b-NA (0)
-      |                                               |                |      data_foramt: "hev1" (High Efficiency Video Coding / H.265 / MPEG-H Part 2) 0x149b-NA (0)
+      |                                               |                |      data_foramt: "hev1" (High Efficiency Video Coding) 0x149b-NA (0)
--- a/format/mp4/testdata/mp3.fqtest
+++ b/format/mp4/testdata/mp3.fqtest
@ -192,7 +192,7 @@ $ fq -d mp4 dv mp3.mp4
     |                                               |                |                          boxes[0:1]: 0x443-0x492.7 (80)
     |                                               |                |                            [0]{}: box 0x443-0x492.7 (80)
 0x440|         00 00 00 50                           |   ...P         |                              size: 80 0x443-0x446.7 (4)
-0x440|                     6d 70 34 61               |       mp4a     |                              type: "mp4a" (MPEG Audio) 0x447-0x44a.7 (4)
+0x440|                     6d 70 34 61               |       mp4a     |                              type: "mp4a" (MPEG-4 Audio) 0x447-0x44a.7 (4)
 0x440|                                 00 00 00 00 00|           .....|                              reserved: raw bits 0x44b-0x450.7 (6)
 0x450|00                                             |.               |
 0x450|   00 01                                       | ..             |                              data_reference_index: 1 0x451-0x452.7 (2)
@ -506,4 +506,4 @@ $ fq -d mp4 dv mp3.mp4
 *    |until 0x29d.7 (188)                            |                |
     |                                               |                |          crc_calculated: "c36b" (raw bits) 0x29e-NA (0)
     |                                               |                |      id: 1 0x565-NA (0)
-     |                                               |                |      data_foramt: "mp4a" (MPEG Audio) 0x565-NA (0)
+     |                                               |                |      data_foramt: "mp4a" (MPEG-4 Audio) 0x565-NA (0)
--- a/format/mp4/testdata/mpeg2.fqtest
+++ b/format/mp4/testdata/mpeg2.fqtest
@ -195,7 +195,7 @@ $ fq -d mp4 dv mpeg2.mp4
      |                                               |                |                            [0]{}: box 0x214f-0x21ea.7 (156)
 0x2140|                                             00|               .|                              size: 156 0x214f-0x2152.7 (4)
 0x2150|00 00 9c                                       |...             |
-0x2150|         6d 70 34 76                           |   mp4v         |                              type: "mp4v" (MPEG Video) 0x2153-0x2156.7 (4)
+0x2150|         6d 70 34 76                           |   mp4v         |                              type: "mp4v" (MPEG-4 Visual) 0x2153-0x2156.7 (4)
 0x2150|                     00 00 00 00 00 00         |       ......   |                              reserved: raw bits 0x2157-0x215c.7 (6)
 0x2150|                                       00 01   |             .. |                              data_reference_index: 1 0x215d-0x215e.7 (2)
 0x2150|                                             00|               .|                              version: 0 0x215f-0x2160.7 (2)
@ -356,4 +356,4 @@ $ fq -d mp4 dv mpeg2.mp4
 0x0040|00 00 00 00 01 b8 00 08 00 40 00 00 01 00 00 0f|.........@......|
 *     |until 0x1fa5.7 (8046)                          |                |
      |                                               |                |      id: 1 0x22a9-NA (0)
-      |                                               |                |      data_foramt: "mp4v" (MPEG Video) 0x22a9-NA (0)
+      |                                               |                |      data_foramt: "mp4v" (MPEG-4 Visual) 0x22a9-NA (0)
--- a/format/mp4/testdata/opus.fqtest
+++ b/format/mp4/testdata/opus.fqtest
@ -187,7 +187,7 @@ $ fq -d mp4 dv opus.mp4
     |                                               |                |                          boxes[0:1]: 0x33c-0x372.7 (55)
     |                                               |                |                            [0]{}: box 0x33c-0x372.7 (55)
 0x330|                                    00 00 00 37|            ...7|                              size: 55 0x33c-0x33f.7 (4)
-0x340|4f 70 75 73                                    |Opus            |                              type: "Opus" (Xiph Opus) 0x340-0x343.7 (4)
+0x340|4f 70 75 73                                    |Opus            |                              type: "Opus" (Opus audio coding) 0x340-0x343.7 (4)
 0x340|            00 00 00 00 00 00                  |    ......      |                              reserved: raw bits 0x344-0x349.7 (6)
 0x340|                              00 01            |          ..    |                              data_reference_index: 1 0x34a-0x34b.7 (2)
 0x340|                                    00 00      |            ..  |                              version: 0 0x34c-0x34d.7 (2)
@ -353,4 +353,4 @@ $ fq -d mp4 dv opus.mp4
 0x120|02 cc 49 57 27 d4 a3 83 e9 53 33 fe 45 62 33 33|..IW'....S3.Eb33|
 *    |until 0x196.7 (120)                            |                |
     |                                               |                |      id: 1 0x439-NA (0)
-     |                                               |                |      data_foramt: "Opus" (Xiph Opus) 0x439-NA (0)
+     |                                               |                |      data_foramt: "Opus" (Opus audio coding) 0x439-NA (0)
--- a/format/mp4/testdata/stz2.fqtest
+++ b/format/mp4/testdata/stz2.fqtest
@ -179,7 +179,7 @@ $ fq -d mp4 'dv' stz2.mp4
     |                                               |                |                            [0]{}: box 0x1ce-0x214.7 (71)
 0x1c0|                                          00 00|              ..|                              size: 71 0x1ce-0x1d1.7 (4)
 0x1d0|00 47                                          |.G              |
-0x1d0|      6d 70 34 61                              |  mp4a          |                              type: "mp4a" (MPEG Audio) 0x1d2-0x1d5.7 (4)
+0x1d0|      6d 70 34 61                              |  mp4a          |                              type: "mp4a" (MPEG-4 Audio) 0x1d2-0x1d5.7 (4)
 0x1d0|                  00 00 00 00 00 00            |      ......    |                              reserved: raw bits 0x1d6-0x1db.7 (6)
 0x1d0|                                    00 01      |            ..  |                              data_reference_index: 1 0x1dc-0x1dd.7 (2)
 0x1d0|                                          00 00|              ..|                              version: 0 0x1de-0x1df.7 (2)
@ -463,4 +463,4 @@ $ fq -d mp4 'dv' stz2.mp4
 *    |until 0x4f5.7 (188)                            |                |
     |                                               |                |          crc_calculated: "c36b" (raw bits) 0x4f6-NA (0)
     |                                               |                |      id: 1 0x530-NA (0)
-     |                                               |                |      data_foramt: "mp4a" (MPEG Audio) 0x530-NA (0)
+     |                                               |                |      data_foramt: "mp4a" (MPEG-4 Audio) 0x530-NA (0)
--- a/format/mp4/testdata/vorbis.fqtest
+++ b/format/mp4/testdata/vorbis.fqtest
@ -194,7 +194,7 @@ $ fq -d mp4 dv vorbis.mp4
      |                                               |                |                          boxes[0:1]: 0x382-0x10b6.7 (3381)
      |                                               |                |                            [0]{}: box 0x382-0x10b6.7 (3381)
 0x0380|      00 00 0d 35                              |  ...5          |                              size: 3381 0x382-0x385.7 (4)
-0x0380|                  6d 70 34 61                  |      mp4a      |                              type: "mp4a" (MPEG Audio) 0x386-0x389.7 (4)
+0x0380|                  6d 70 34 61                  |      mp4a      |                              type: "mp4a" (MPEG-4 Audio) 0x386-0x389.7 (4)
 0x0380|                              00 00 00 00 00 00|          ......|                              reserved: raw bits 0x38a-0x38f.7 (6)
 0x0390|00 01                                          |..              |                              data_reference_index: 1 0x390-0x391.7 (2)
 0x0390|      00 00                                    |  ..            |                              version: 0 0x392-0x393.7 (2)
@ -383,4 +383,4 @@ $ fq -d mp4 dv vorbis.mp4
 0x0130|f2 81 46 bb c2 48 52 08 27 b8 83 10 ca 08 b1 a7|..F..HR.'.......|
 *     |until 0x1dc.7 (174)                            |                |
      |                                               |                |      id: 1 0x1189-NA (0)
-      |                                               |                |      data_foramt: "mp4a" (MPEG Audio) 0x1189-NA (0)
+      |                                               |                |      data_foramt: "mp4a" (MPEG-4 Audio) 0x1189-NA (0)
--- a/format/mp4/testdata/vp9.fqtest
+++ b/format/mp4/testdata/vp9.fqtest
@ -178,7 +178,7 @@ $ fq -d mp4 dv vp9.mp4
      |                                               |                |                            [0]{}: box 0x170d-0x1790.7 (132)
 0x1700|                                       00 00 00|             ...|                              size: 132 0x170d-0x1710.7 (4)
 0x1710|84                                             |.               |
-0x1710|   76 70 30 39                                 | vp09           |                              type: "vp09" (VP9) 0x1711-0x1714.7 (4)
+0x1710|   76 70 30 39                                 | vp09           |                              type: "vp09" (VP9 video) 0x1711-0x1714.7 (4)
 0x1710|               00 00 00 00 00 00               |     ......     |                              reserved: raw bits 0x1715-0x171a.7 (6)
 0x1710|                                 00 01         |           ..   |                              data_reference_index: 1 0x171b-0x171c.7 (2)
 0x1710|                                       00 00   |             .. |                              version: 0 0x171d-0x171e.7 (2)
@ -336,4 +336,4 @@ $ fq -d mp4 dv vp9.mp4
 0x0040|f9 be 8f e7 71 ff 5f 97 ef c3 f9 7e 37 b0 7e ad|....q._....~7.~.|
 *     |until 0x1563.7 (5424)                          |                |
      |                                               |                |      id: 1 0x184f-NA (0)
-      |                                               |                |      data_foramt: "vp09" (VP9) 0x184f-NA (0)
+      |                                               |                |      data_foramt: "vp09" (VP9 video) 0x184f-NA (0)
--- a/format/msgpack/msgpack.go
+++ b/format/msgpack/msgpack.go
@ -14,6 +14,7 @@ import (
 )

 //go:embed msgpack.jq
+//go:embed msgpack.md
 var msgPackFS embed.FS

 func init() {
@ -21,7 +22,7 @@ func init() {
 		Name:        format.MSGPACK,
 		Description: "MessagePack",
 		DecodeFn:    decodeMsgPack,
-		Functions:   []string{"torepr", "_help"},
+		Functions:   []string{"torepr"},
 	})
 	interp.RegisterFS(msgPackFS)
 }
--- a/format/msgpack/msgpack.jq
+++ b/format/msgpack/msgpack.jq
@ -9,8 +9,3 @@ def _msgpack_torepr:
  else .value | tovalue
  end;

-def _msgpack__help:
-  { links: [
-      {url: "https://github.com/msgpack/msgpack/blob/master/spec.md"}
-    ]
-  };
--- a/format/msgpack/msgpack.md
+++ b/format/msgpack/msgpack.md
@ -0,0 +1,8 @@
+### Convert represented value to JSON
+
+```
+$ fq -d msgpack torepr file.msgpack
+```
+
+### References
+- https://github.com/msgpack/msgpack/blob/master/spec.md
--- a/format/protobuf/protobuf.go
+++ b/format/protobuf/protobuf.go
@ -12,7 +12,7 @@ import (
 	"github.com/wader/fq/pkg/scalar"
 )

-//go:embed protobuf.jq
+//go:embed protobuf.md
 var protobufFS embed.FS

 func init() {
@ -20,7 +20,6 @@ func init() {
 		Name:        format.PROTOBUF,
 		Description: "Protobuf",
 		DecodeFn:    protobufDecode,
-		Functions:   []string{"_help"},
 	})
 	interp.RegisterFS(protobufFS)
 }
--- a/format/protobuf/protobuf.jq
+++ b/format/protobuf/protobuf.jq
@ -1,8 +0,0 @@
-def _protobuf__help:
-  { examples: [
-      {comment: "Can be used to decode sub messages", shell: "fq -d protobuf '.fields[6].wire_value | protobuf | d'"}
-    ],
-    links: [
-      {url: "https://developers.google.com/protocol-buffers/docs/encoding"}
-    ]
-  };
--- a/format/protobuf/protobuf.md
+++ b/format/protobuf/protobuf.md
@ -0,0 +1,8 @@
+### Can decode sub messages
+
+```sh
+$ fq -d protobuf '.fields[6].wire_value | protobuf | d' file
+```
+
+### References
+- https://developers.google.com/protocol-buffers/docs/encoding
--- a/format/rtmp/rtmp.go
+++ b/format/rtmp/rtmp.go
@ -21,7 +21,7 @@ import (
 var rtmpAmf0Group decode.Group
 var rtmpMpegASCFormat decode.Group

-//go:embed rtmp.jq
+//go:embed rtmp.md
 var rtmpFS embed.FS

 func init() {
@ -36,7 +36,6 @@ func init() {
 			{Names: []string{format.AMF0}, Group: &rtmpAmf0Group},
 			{Names: []string{format.MPEG_ASC}, Group: &rtmpMpegASCFormat},
 		},
-		Functions: []string{"_help"},
 	})
 	interp.RegisterFS(rtmpFS)
 }
--- a/format/rtmp/rtmp.jq
+++ b/format/rtmp/rtmp.jq
@ -1,7 +0,0 @@
-def _rtmp__help:
-  { notes: "Current only supports plain RTMP (not RTMPT or encrypted variants etc) with AMF0 (not AMF3).",
-    links: [
-      {url: "https://rtmp.veriskope.com/docs/spec/"},
-      {url: "https://rtmp.veriskope.com/pdf/video_file_format_spec_v10.pdf"}
-    ]
-  };
--- a/format/rtmp/rtmp.md
+++ b/format/rtmp/rtmp.md
@ -0,0 +1,5 @@
+Current only supports plain RTMP (not RTMPT or encrypted variants etc) with AMF0 (not AMF3).
+
+### References
+- https://rtmp.veriskope.com/docs/spec/
+- https://rtmp.veriskope.com/pdf/video_file_format_spec_v10.pdf
--- a/format/wasm/wasm.go
+++ b/format/wasm/wasm.go
@ -3,6 +3,7 @@ package wasm
 // https://webassembly.github.io/spec/core/

 import (
+	"embed"
 	"math"
 	"sync"

@ -12,6 +13,9 @@ import (
 	"github.com/wader/fq/pkg/scalar"
 )

+//go:embed wasm.md
+var wasmFS embed.FS
+
 func init() {
 	interp.RegisterFormat(decode.Format{
 		Name:        format.WASM,
@ -19,6 +23,7 @@ func init() {
 		DecodeFn:    decodeWASM,
 		Groups:      []string{format.PROBE},
 	})
+	interp.RegisterFS(wasmFS)
 }

 const (
--- a/format/wasm/wasm.md
+++ b/format/wasm/wasm.md
@ -0,0 +1,17 @@
+### Count opcode usage
+```sh
+$ fq '.sections[] | select(.id == "code_section") | [.. | .opcode? // empty] | count | map({key: .[0], value: .[1]}) | from_entries' file.wasm
+```
+
+### List exports and imports
+```sh
+$ fq '.sections | {import: map(select(.id == "import_section").content.im.x[].nm.b), export: map(select(.id == "export_section").content.ex.x[].nm.b)}' file.wasm
+```
+
+### Authors
+- Takashi Oguma
+[@bitbears-dev](https://github.com/bitbears-dev)
+[@0xb17bea125](https://twitter.com/0xb17bea125)
+
+### References
+- https://webassembly.github.io/spec/core/
--- a/format/xml/xml.go
+++ b/format/xml/xml.go
@ -29,6 +29,7 @@ import (
 )

 //go:embed xml.jq
+//go:embed xml.md
 var xmlFS embed.FS

 func init() {
@ -43,7 +44,7 @@ func init() {
 			Array:           false,
 			AttributePrefix: "@",
 		},
-		Functions: []string{"_todisplay", "_help"},
+		Functions: []string{"_todisplay"},
 	})
 	interp.RegisterFS(xmlFS)
 	interp.RegisterFunc1("toxml", toXML)
--- a/format/xml/xml.jq
+++ b/format/xml/xml.jq
@ -1,8 +1,2 @@
 def toxml: toxml(null);
 def _xml__todisplay: tovalue;
-
-def _xml__help:
-  { links: [
-      {title: "xml.com's Converting Between XML and JSON", url: "https://www.xml.com/pub/a/2006/05/31/converting-between-xml-and-json.html"}
-    ]
-  };
--- a/format/xml/xml.md
+++ b/format/xml/xml.md
@ -0,0 +1,2 @@
+### References
+- [xml.com's Converting Between XML and JSON](https://www.xml.com/pub/a/2006/05/31/converting-between-xml-and-json.html)
--- a/format/zip/zip.go
+++ b/format/zip/zip.go
@ -15,7 +15,7 @@ import (
 	"github.com/wader/fq/pkg/scalar"
 )

-//go:embed zip.jq
+//go:embed zip.md
 var zipFS embed.FS

 var probeFormat decode.Group
@ -32,7 +32,6 @@ func init() {
 		Dependencies: []decode.Dependency{
 			{Names: []string{format.PROBE}, Group: &probeFormat},
 		},
-		Functions: []string{"_help"},
 	})
 	interp.RegisterFS(zipFS)
 }
--- a/format/zip/zip.jq
+++ b/format/zip/zip.jq
@ -1,6 +0,0 @@
-def _zip__help:
-  { notes: "Supports ZIP64.",
-    links: [
-      {url: "https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT"}
-    ]
-  };
--- a/format/zip/zip.md
+++ b/format/zip/zip.md
@ -0,0 +1,5 @@
+Supports ZIP64.
+
+### References
+- https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT
+- https://opensource.apple.com/source/zip/zip-6/unzip/unzip/proginfo/extra.fld
--- a/go.mod
+++ b/go.mod
@ -25,6 +25,10 @@ require (
 	// bump: gomod-golang-snappy link "Source diff $CURRENT..$LATEST" https://github.com/golang/snappy/compare/v$CURRENT..v$LATEST
 	github.com/golang/snappy v0.0.4

+	// has no tags
+	// go get -d github.com/gomarkdown/markdown@master && go mod tidy
+	github.com/gomarkdown/markdown v0.0.0-20220627144906-e9a81102ebeb
+
 	// has no tags yet
 	// bump-disabled: gomod-gopacket /github\.com\/gopacket\/gopacket v(.*)/ https://github.com/gopacket/gopacket.git|^1
 	// bump-disabled: gomod-gopacket command go get -d github.com/gopacket/gopacket@v$LATEST && go mod tidy
--- a/go.sum
+++ b/go.sum
@ -4,6 +4,8 @@ github.com/creasty/defaults v1.6.0 h1:ltuE9cfphUtlrBeomuu8PEyISTXnxqkBIoQfXgv7BS
 github.com/creasty/defaults v1.6.0/go.mod h1:iGzKe6pbEHnpMPtfDXZEr0NVxWnPTjb1bbDy08fPzYM=
 github.com/golang/snappy v0.0.4 h1:yAGX7huGHXlcLOEtBnF4w7FQwA26wojNCwOYAEhLjQM=
 github.com/golang/snappy v0.0.4/go.mod h1:/XxbfmMg8lxefKM7IXC3fBNl/7bRcc72aCRzEWrmP2Q=
+github.com/gomarkdown/markdown v0.0.0-20220627144906-e9a81102ebeb h1:5b/eFaSaKPFG9ygDBaPKkydKU5nFJYk08g9jPIVogMg=
+github.com/gomarkdown/markdown v0.0.0-20220627144906-e9a81102ebeb/go.mod h1:JDGcbDT52eL4fju3sZ4TeHGsQwhG9nbDV21aMyhwPoA=
 github.com/gopacket/gopacket v0.0.0-20220819214934-ee81b8c880da h1:AAwDU9N39fQNYUtg270aiU6N7U2ZVsGZKiRwsCMsWEo=
 github.com/gopacket/gopacket v0.0.0-20220819214934-ee81b8c880da/go.mod h1:DlRRfaM/QjAu2ADqraIure1Eif0HpNL8hmyVQ+qci5Y=
 github.com/itchyny/timefmt-go v0.1.3 h1:7M3LGVDsqcd0VZH2U+x393obrzZisp7C0uEe921iRkU=
--- a/pkg/interp/funcs.jq
+++ b/pkg/interp/funcs.jq
@ -153,23 +153,6 @@ def paste:
    )
  end;

-# very simple markdown to text converter
-# assumes very basic markdown as input
-def _markdown_to_text:
-  ( .
-  # ```
-  # code
-  # ```
-  # -> code
-  | gsub("\\n```\\n"; "\n"; "m")
-  # #, ##, ###, ... -> #
-  | gsub("(?<line>\\n)?#+(?<title>.*)\\n"; "\(.line // "")#\(.title)\n"; "m")
-  # [title](url) -> title (url)
-  | gsub("\\[(?<title>.*)\\]\\((?<url>.*)\\)"; "\(.title) (\(.url))")
-  # `code` -> code
-  | gsub("`(?<code>.*)`"; .code)
-  );
-
 def expr_to_path: _expr_to_path;
 def path_to_expr: _path_to_expr;

--- a/pkg/interp/help.jq
+++ b/pkg/interp/help.jq
@ -64,14 +64,6 @@ def _help_format_enrich($arg0; $f; $include_basic):
        , {comment: "Decode value as \($f.name)", expr: "\($f.name)"}
        ]
    end
-  | (($f.functions // []) | map(select(startswith("_") | not))) as $public_functions
-  | if ($public_functions | length) > 0 then
-      .examples +=
-        [ $public_functions[]
-        | {comment: "Supports `\(.)`", shell: "fq -d \($f.name) torepr file"}
-        , {comment: "Supports `\(.)`", expr: "\($f.name) | torepr"}
-        ]
-    end
  | if $f.decode_in_arg then
      .examples +=
        [ { comment: "Decode file using \($f.name) options"
@ -146,13 +138,14 @@ def _help($arg0; $topic):
    elif _registry.formats | has($topic) then
      ( _registry.formats[$topic] as $f
      | (_format_func($f.name; "_help")? // {} | _help_format_enrich($arg0; $f; true)) as $fhelp
+      | ((_registry.files[][] | select(.name=="\($topic).md").data) // false) as $doc
      | "\($f.name): \($f.description) decoder"
-      , ($fhelp.notes | if . then _markdown_to_text else empty end)
      , if $f.decode_in_arg then
          ( $f.decode_in_arg
          | to_entries
          | map(["  \(.key)=\(.value)  ", $f.decode_in_arg_doc[.key]])
-          | "Options:"
+          | "# Options"
+          , ""
          , table(
              .;
              map(
@ -167,28 +160,19 @@ def _help($arg0; $topic):
          )
        else empty
        end
-      , "Examples:"
+      , ""
+      , "# Decode examples"
+      , ""
      , ( $fhelp.examples[]
-        | "  # \(.comment | _markdown_to_text)"
+        | "  # \(.comment)"
        , if .shell then "  $ \(.shell)"
          elif .expr then "  ... | \(.expr)"
          else empty
          end
        )
-      , if isempty($f.functions | select(. == "torepr")) | not then
-          ( "Supports torepr:"
-          , "  ... | \($f.name) | torepr"
-          )
-        else empty
-        end
-      , if $fhelp.links then
-          ( "References and links"
-          , ( $fhelp.links[]
-            | if .title then "  \(.title) \(.url)"
-              else "  \(.url)"
-              end
-            )
-          )
+      , ""
+      # TODO: [:-1] hack to remove extra newline as we use println later
+      , if $doc then $doc | markdown | _markdown_to_text(options.width; -2)[:-1]
        else empty
        end
      )
--- a/pkg/interp/options.jq
+++ b/pkg/interp/options.jq
@ -311,7 +311,11 @@ def _opt_from_csv_kv_obj:
 def _opt_to_fuzzy:
  ( . as $s
  | try fromjson
-    catch $s
+    catch
+      ( $s
+      | _opt_to_string
+      // $s
+      )
  );

 def _opt_to($type):
--- a/pkg/interp/testdata/args.fqtest
+++ b/pkg/interp/testdata/args.fqtest
@ -162,10 +162,11 @@ json                 JavaScript Object Notation
 jsonl                JavaScript Object Notation Lines
 macho                Mach-O macOS executable
 macho_fat            Fat Mach-O macOS executable (multi-architecture)
+markdown             Markdown
 matroska             Matroska file
 mp3                  MP3 file
 mp3_frame            MPEG audio layer 3 frame
-mp4                  ISOBMFF MPEG-4 part 12 and similar
+mp4                  ISOBMFF, QuickTime and similar
 mpeg_asc             MPEG-4 Audio Specific Config
 mpeg_es              MPEG Elementary Stream
 mpeg_pes             MPEG Packetized elementary stream