SCAN(1mh)

✨ SCAN(1mh) ✨

okay so hi bestie 💖 this is the manual page for scan (from the nmh fam, 1mh section, iykyk). Let me put you on.

---

🌸 NAME 🌸

scan — it produces a summary listing of your nmh messages. that's the whole job. and it eats. 💅

---

🦋 SYNOPSIS 🦋

scan [-help] [-version] [+folder] [msgs] [-clear | -noclear] [-form
     formatfile] [-format string] [-header | -noheader] [-width columns]
     [-reverse | -noreverse] [-file filename]

---

💜 DESCRIPTION 💜

scan gives you a one-line-per-message listing of whatever folder or messages you point it at. no cap. 📋

Every scan line has the message number (that's the name), the date, the From: field, the Subject: field, and — if there's room left over — a lil peek at the body of the message. like so:

15+  10/05 crocker    nned  <<Last week I asked some of
16-  10/05 crocker    message id format  <<I recommend
18   10/06 brien      Re: Exit status from mkdir
19   10/07*brien      “scan” listing format in nmh

let me decode the little symbols for you because they're lowkey doing a lot:

• The + on message 15 means it's the current message. main character energy 👑
• The - on message 16 means it's been replied to — that's shown by a Replied: component, which gets produced by the -annotate switch on the repl command.
• The * on message 19 means there was no Date: header at all. in that case, scan gives you the time of last modification of the message instead. it's doing its best 🫶

If there's enough room left on the scan line after the subject, the line gets filled with text from the body, preceded by <<, and terminated by >> if the body is short enough. and yes, scan actually reads every single message you specified and parses them to pull out the fields it wants. during parsing, if any of the messages have format errors, you'll get appropriate error messages. it will tell you. 😭

By default, scan will decode RFC 2047 (MIME) encoding in these scan listings. but — important — scan will only decode those fields if your terminal can natively display the character set used in the encoding. so you should set the appropriate locale(1) environment variables to your native character set, if it's not US-ASCII. go read locale(1) for the details on which environment variables you need, bestie. 🌈

The -reverse switch makes scan list the messages in reverse order. (flip it and reverse it ✨)

The -file filename switch lets you get a scan listing of a mail drop. note: this listing includes every message in the mail drop — you can't scan individual messages with this. also, the -reverse switch is ignored with this option. if filename is a file, it can be in mbox or MMDF format, as produced by packf. if filename is a directory, it's considered to be in Maildir format. 📁

The -width columns switch lets you specify the width of the scan line. default is to just use the width of your terminal.

The -header switch produces a header line before the scan listing kicks in. currently it outputs the name of the folder and the current date and time (peep the HISTORY section for more on this).

Now — the -clear switch. if you use it and scan's output is going to a terminal, then scan will consult the environment variables $TERM and $TERMCAP to figure out your terminal type, so it knows how to clear the screen before exiting. but if -clear is used and the output is not directed to a terminal (like a pipe or a file), then scan sends a formfeed before exiting instead. context matters, babe. 💀

For example, this command:

(scan -clear -header; show all -show pr -f) | lpr

produces a scan listing of the current folder, followed by a formfeed, followed by a formatted listing of all messages in the folder, one per page. and if you omit -show pr -f, the messages get concatenated, separated by a one-line header and two blank lines.

To override the output format scan uses, you've got -format string or -form file. this lets you extract individual fields of the scan listing with ease. the string is simply a format string and the file is simply a format file. go see mh-format(5) for the details, fr fr.

On top of the standard mh-format(5) escapes, scan also recognizes these extra component escapes:

• body — returns string — the (compressed) first part of the body
• dtimenow — returns date — the current date
• folder — returns string — the name of the current folder

heads up: {body} returns a string without MIME decoding, i.e. the MIME boundary separator may be the first text shown. 🙈

If there's no date header in the message, the function escapes that operate on {date} will return values for the date of last modification of the message file itself. this is super handy for scanning a draft folder, since message drafts usually aren't allowed to have dates in them. 🎀

The /etc/nmh directory contains several format files as examples of customized scan output.

One more thing: scan will update the nmh context before it starts the listing, so if you interrupt a long scan listing, the new context is preserved. nmh purists hate this idea. 💀 not sorry.

---

🍓 FILES 🍓

• $HOME/.mh_profile — The user profile

---

🧚 PROFILE COMPONENTS 🧚

• Path: — To determine the user's nmh directory
• Alternate-Mailboxes: — To determine the user's mailboxes
• Current-Folder: — To find the default current folder

---

⭐ SEE ALSO ⭐

pick(1), show(1), mh-format(5)

---

🎀 DEFAULTS 🎀

• +folder defaults to the current folder
• msgs defaults to all
• -format defaulted as described above
• -noheader
• -width defaulted to the width of the terminal

---

💅 CONTEXT 💅

If a folder is given, it will become the current folder. periodt.

---

👑 HISTORY 👑

Back before the format string mechanism existed, -header used to generate a heading saying what each column in the listing was. format strings prevent this from happening. glow-up. ✨

---

🌈 BUGS 🌈

The value of each component escape is set by scan to the contents of the first message header scan encounters with the corresponding component name; any following headers with the same component name are ignored. so yeah. that's the vibe. 🦋

---

and that's the whole page, bestie — this was nmh-1.8, dated 2020-02-17, and it's giving SCAN(1mh) in the most iconic way possible 💖🫶 no cap, go scan something.