birthday(1)

🎂 birthday(1) — the manual page, but make it make sense 💖

okay bestie, sit down, grab a snack 🍓 — this is birthday, a little command from the General Commands Manual (section 1, the big leagues 💅), and she's here to warn you about upcoming birthdays and other events. no cap.

---

✨ NAME ✨

birthday — warn about upcoming birthdays and other events 🎈

---

🌸 SYNOPSIS 🌸

birthday [-w|-c] [-f file] [-W defwarn] [-M maxwarn] [-m minwarn] [-l lines] [-p weeks] [-d total] [-i width] [-L]

---

🦋 DESCRIPTION 🦋

so the birthday command reads a file — by default ~/.birthdays — and that file is literally just a list of events happening in the near future (the whole format is in FILE FORMAT below, keep scrolling babe 📜).

once she's read it, she can do one of two things:

• spit out a list of events coming up in the next few weeks, or
• give you a text-based calendar with a few lines for each day 📅

main character energy honestly.

---

👑 OPTIONS 👑

• -w — show a list of upcoming events. this is the default, she's lowkey the standard.
• -c — show a calendar, designed to be piped to lpr(1). printer girlies rise 🖨️
• -f file — read the events from file instead of ~/.birthdays. and if file is a single hyphen, read the events from the standard input (usually the terminal). cute.

💜 List Options 💜

• -W warn — warn warn days in advance, for entries that have no w flag (see FILE FORMAT). if you don't pass this switch, it defaults to 21 days.
• -M max — warn at most max days in advance. this overrides any flag given in the file. she said no 🙅
• -m min — warn at least min days in advance. this overrides any flag given in the file too. she said yes 💅
• -L — also output the day and name of month after the number of days hence.

🎀 Calendar Options 🎀

• -l lines — print lines lines for every day.
• -p weeks — print weeks weeks on every page of the calendar. if set to 0, the default, it disables page breaks.
• -d days — print the calendar for up to days days in advance.
• -i width — print the calendar width characters wide. this affects the length of the lines separating each day, and the point at which events will be word-wrapped. 📏

---

🌈 FILE FORMAT 🌈

okay this is the part where you actually learn the language of the file, iykyk.

• every line starting with a hash sign, #, is a comment and will be ignored. (yes, just like your fave scripting language 💅)
• lines starting with an ampersand, &, are directives. right now there's only one such directive: &include file, which reads in a seperate file from your .birthdays file. file should be given with an absolute path, and it should not use the tilde notation to specify your home directory. no ~ shenanigans bestie, she will not be fooled.
• any other line specifies the name of a person or event, followed by an equals sign and a date (DD/MM, DD/MM/YY or DD/MM/YYYY, where the form DD/MM/YY is assumed to give a date in the 20th century and is now deprecated 🚨), and finally some extra options.

here are those extra options, one by one:

• bd — this line is a birthday (the default). the year, if given, should be when the person was born. a line designated as a birthday will produce output like Erin has a birthday in 3 days' time or Jemima is 3 in 2 weeks' time. 🎂
• ann — this line is an anniversary. the year, if given, should be the year in which the thing happened, producing output like Pen exploded 3 years ago tomorrow given a line such as Pen exploded=12/09/93 ann. 💥
• ev — this line is an event of some sort. if a year is given, the text will be displayed in that year only; otherwise, it will be displayed every year. the remaining time is simply appended to the text; for instance, the input Easter=7/4/1996 ev would give rise to the text Easter in 1 week's time.
• w n — warn n days in advance of the date, rather than the default of 21 days or the number given with the -W flag.
• todate — the event lasts until date, which should be in the same format as for the date of the event.
• fordays — the event lasts for days days.

---

⭐ DATE SPECIFICATION ⭐

so the file format documented here handles dates in a couple of slightly non-standard ways, and we need to talk about it fr fr.

firstly: the dates are given in British format of DD/MM/YYYY, as opposed to the more normal US format MM/DD/YYYY. 🇬🇧

secondly: dates with a two-digit year are assumed to be in the 20th century (19xx), rather than taking the standard convention of assuming all two-digit years less than 70 are in the 21st century. this is for reasons of compatibility with older data files, since many people have birthdays before 1970, and the program was written before the author came across the Y2K issues. :-( 😭

bestie. you should probably avoid this format. that's a direct quote, not me being dramatic. (ok it's also me being dramatic. but she said it first.)

---

🧚 EXAMPLE 🧚

Joe Blow=25/04/1974

---

💖 FILES 💖

• ~/.birthdays — your default birthdays file. your home base 🏠

---

🫶 SEE ALSO 🫶

• cal(1)

---

💀 BUGS 💀

• Both the "features" in the DATE SPECIFICATION section could be construed as bugs, and are mostly present for backwards compatibility. (the scare quotes around "features" are doing SO much work here 😭)
• The calendar mode should be a seperate program.
• The program cannot warn more than one year in advance of anything. one year. that's the ceiling. periodt.

---

🌟 AUTHOR 🌟

Andy Mortimer <andy.mortimer@zetnet.co.uk>

---

and that's the whole thing, bestie 💅 this page lives in the General Commands Manual as birthday(1) — that's the title up top and the very last line of the page, section 1 energy only, no version or date given, so don't come for me about it 🙈✨ love u, go wish somebody a happy birthday 🎀🦋