From 832eed84d50d5f157772001917c000eceee282cc Mon Sep 17 00:00:00 2001
From: Vitor Henrique <87824454+vitorhcl@users.noreply.github.com>
Date: Wed, 14 Feb 2024 17:25:58 -0300
Subject: [PATCH] cal: improve util-linux page and split POSIX, osx and *BSD
 (#12172)

Co-authored-by: Juri Dispan <juri.dispan@posteo.net>
Co-authored-by: Sebastiaan Speck <12570668+sebastiaanspeck@users.noreply.github.com>
---
 pages/common/cal.md  | 16 ++++++++++++++++
 pages/freebsd/cal.md | 32 ++++++++++++++++++++++++++++++++
 pages/linux/cal.md   | 12 ++++++++++--
 pages/netbsd/cal.md  | 36 ++++++++++++++++++++++++++++++++++++
 pages/openbsd/cal.md | 32 ++++++++++++++++++++++++++++++++
 5 files changed, 126 insertions(+), 2 deletions(-)
 create mode 100644 pages/common/cal.md
 create mode 100644 pages/freebsd/cal.md
 create mode 100644 pages/netbsd/cal.md
 create mode 100644 pages/openbsd/cal.md

diff --git a/pages/common/cal.md b/pages/common/cal.md
new file mode 100644
index 000000000..fb520c6aa
--- /dev/null
+++ b/pages/common/cal.md
@@ -0,0 +1,16 @@
+# cal
+
+> Display a calendar with the current day highlighted.
+> More information: <https://manned.org/cal.1p>.
+
+- Display a calendar for the current month:
+
+`cal`
+
+- Display a calendar for a specific year:
+
+`cal {{year}}`
+
+- Display a calendar for a specific month and year:
+
+`cal {{month}} {{year}}`
diff --git a/pages/freebsd/cal.md b/pages/freebsd/cal.md
new file mode 100644
index 000000000..e303b3a9b
--- /dev/null
+++ b/pages/freebsd/cal.md
@@ -0,0 +1,32 @@
+# cal
+
+> Display a calendar with the current day highlighted.
+> More information: <https://man.freebsd.org/cgi/man.cgi?cal>.
+
+- Display a calendar for the current month:
+
+`cal`
+
+- Display a calendar for a specific year:
+
+`cal {{year}}`
+
+- Display a calendar for a specific month and year:
+
+`cal {{month}} {{year}}`
+
+- Display the whole calendar for the current year:
+
+`cal -y`
+
+- Don't [h]ighlight today and display [3] months spanning the date:
+
+`cal -h -3 {{month}} {{year}}`
+
+- Display the 2 months [B]efore and 3 [A]fter a specific [m]onth of the current year:
+
+`cal -A 3 -B 2 {{month}}`
+
+- Display [j]ulian days (starting from one, numbered from January 1):
+
+`cal -j`
diff --git a/pages/linux/cal.md b/pages/linux/cal.md
index da909d75a..1bb9a8850 100644
--- a/pages/linux/cal.md
+++ b/pages/linux/cal.md
@@ -1,16 +1,24 @@
 # cal
 
-> Prints calendar information, with the current day highlighted.
+> Display a calendar with the current day highlighted.
 > More information: <https://manned.org/cal>.
 
 - Display a calendar for the current month:
 
 `cal`
 
-- Display previous, current and next month:
+- Display [3] months spanning the date:
 
 `cal -3`
 
+- Display the whole calendar for the current [y]ear:
+
+`cal --year`
+
+- Display the next twelve months:
+
+`cal --twelve`
+
 - Use Monday as the first day of the week:
 
 `cal --monday`
diff --git a/pages/netbsd/cal.md b/pages/netbsd/cal.md
new file mode 100644
index 000000000..7259c1726
--- /dev/null
+++ b/pages/netbsd/cal.md
@@ -0,0 +1,36 @@
+# cal
+
+> Display a calendar.
+> More information: <https://man.freebsd.org/cgi/man.cgi?cal>.
+
+- Display a calendar for the current month:
+
+`cal`
+
+- Display a calendar for a specific year:
+
+`cal {{year}}`
+
+- Display a calendar for a specific month and year:
+
+`cal {{month}} {{year}}`
+
+- Display the whole calendar for the current year using [j]ulian days (one-based, numbered from January 1):
+
+`cal -y -j`
+
+- [h]ighlight today and display [3] months spanning the date:
+
+`cal -h -3 {{month}} {{year}}`
+
+- Display the 2 months [B]efore and 3 [A]fter a specific [m]onth of the current year:
+
+`cal -A 3 -B 2 {{month}}`
+
+- Display a specific number of months before and after ([C]ontext) the specified month:
+
+`cal -C {{months}} {{month}}`
+
+- Specify the starting [d]ay of the week (0: Sunday, 1: Monday, ..., 6: Saturday):
+
+`cal -d {{0..6}}`
diff --git a/pages/openbsd/cal.md b/pages/openbsd/cal.md
new file mode 100644
index 000000000..820283c1d
--- /dev/null
+++ b/pages/openbsd/cal.md
@@ -0,0 +1,32 @@
+# cal
+
+> Display a calendar with the current day highlighted.
+> More information: <https://man.openbsd.org/cal>.
+
+- Display a calendar for the current month:
+
+`cal`
+
+- Display a calendar for a specific year:
+
+`cal {{year}}`
+
+- Display a calendar for a specific month and year:
+
+`cal {{month}} {{year}}`
+
+- Display a calendar for the current [y]ear:
+
+`cal -y`
+
+- Display [j]ulian days (starting from one, numbered from January 1):
+
+`cal -j`
+
+- Use [m]onday as week start instead of Sunday:
+
+`cal -m`
+
+- Number [w]eek numbers (incompatible with `-j`):
+
+`cal -w`