commit 40c3c149e13bf27be62d87523cc12c99a6e36e90
parent 8d85e9dbbdbbbeab078827088afde4696a413ed7
Author: Ed van Bruggen <ed@edryd.org>
Date: Sat, 5 Jul 2025 18:31:44 -0400
Add README that is converted into man page
Diffstat:
| M | Makefile | | | 15 | +++++++++++++-- |
| A | README.md | | | 101 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | markman.1 | | | 116 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
3 files changed, 230 insertions(+), 2 deletions(-)
diff --git a/Makefile b/Makefile
@@ -5,9 +5,12 @@ include config.mk
EXE = markman
SRC = markman.c
-OBJ = $(SRC:.c=.o)
+OBJ = markman.o
+MAN = markman.1
-all: options $(EXE)
+MANOPTS = -Dn -s "`./$(EXE) -h 2>&1 | cut -d' ' -f2-`" -t $(EXE) -V $(VERSION) -d "`date '+%B %Y'`"
+
+all: options $(EXE) $(MAN)
options:
@echo $(EXE) build options:
@@ -32,6 +35,10 @@ $(EXE): $(OBJ)
@echo $(CC) -o $@
@$(CC) -o $@ $(OBJ) $(LDFLAGS)
+$(MAN): README.md $(EXE)
+ @echo updating man page $(EXE).1
+ ./$(EXE) $(MANOPTS) $< > $@
+
clean:
@echo cleaning
@rm -f $(OBJ) $(EXE)
@@ -41,6 +48,10 @@ install: all
@mkdir -p $(DESTDIR)$(PREFIX)/bin
@cp -f $(EXE) $(DESTDIR)$(PREFIX)/bin
@chmod 755 $(DESTDIR)$(PREFIX)/bin/$(EXE)
+ @echo installing $(DESTDIR)$(MANPREFIX)/man1/$(EXE).1
+ @mkdir -p $(DESTDIR)$(MANPREFIX)/man1
+ @cp -f $(EXE).1 $(DESTDIR)$(MANPREFIX)/man1/
+ @chmod 644 $(DESTDIR)$(MANPREFIX)/man1/$(EXE).1
uninstall:
@echo removing $(EXE) from $(DESTDIR)$(PREFIX)/bin
diff --git a/README.md b/README.md
@@ -0,0 +1,101 @@
+# markman \- markdown to man page converter
+
+Simple ad hoc generation of Unix man pages from markdown files.
+It includes customizations and ability to supply additional information or formatting needed for man
+pages not found in traditional markdown.
+For example, you can add a synopsis section from a command's help message, convert the title
+header into the name section, or add a description header before the first paragraph.
+This allows any markdown document to become a manual, including this very README.
+
+## Options
+
+#### -c
+
+Disable auto capitalization of titles and section headers.
+
+#### -C
+
+Enable auto capitalization of titles and section headers (default).
+
+#### -t TITLE
+
+Title displayed at top of man page, usually name of program. Defaults to file name or `stdin`.
+
+#### -d DATE
+
+Date man page was updated, displayed at bottom center. Defaults to current date in YYYY-MM-DD
+format.
+
+#### -V VERSION
+
+Version number of program being documented, displayed at bottom left.
+
+#### -m MIDDLE
+
+Text displayed at top middle of manual. Defaults to name of manual section.
+
+#### -n
+
+Convert the first header into a name section at the top of the man page.
+
+#### -s SYNOPSIS
+
+Text to be inserted as a synopsis section at the top of the man page, under name section.
+
+#### -D
+
+Add description header to the top of the man page, under name or synopsis sections if supplied.
+This allows most standard markdown documents to conform to the man page convention where the first
+paragraphs are in the description section.
+
+#### -SECTION
+
+Set man page section number, be can number from 1 to 8:
+
+* **1**: General commands
+* **2**: System calls
+* **3**: Library functions (eg C standard library)
+* **4**: Special files and drivers (eg /dev)
+* **5**: File formats and conventions
+* **6**: Games and screensavers
+* **7**: Miscellaneous
+* **8**: System admin commands and daemons
+
+#### -h
+
+Print help and exit.
+
+#### -v
+
+Print version info and exit.
+
+## Usage
+
+Convert this README into a man page:
+
+```
+markman -Dn -s "`markman -h 2>&1 | cut -d' ' -f2-`" -t $(EXE) -d "`date '+%B %Y'`" -V $(VERSION) README.md > $(EXE).1
+```
+
+## See Also
+
+See project at <https://edryd.org/projects/markman>
+
+View source code at <https://git.edryd.org/markman>
+
+Projects which use markman to generate their man pages:
+
+* markman
+* [eevo](https://eevo.pub)
+* [gst](https://edryd.org/projects/gst)
+
+[Pandoc](https://pandoc.org/) is also a great alternative for a more general purpose markdown
+converter.
+
+## Author
+
+Edryd van Bruggen <ed@edryd.org>
+
+## License
+
+zlib License
diff --git a/markman.1 b/markman.1
@@ -0,0 +1,116 @@
+.TH MARKMAN 1 "July 2025" "0.0.0"
+.PP
+.SH NAME
+markman \- markdown to man page converter
+.PP
+.SH SYNOPSIS
+markman [-cCnDhv] [-t TITLE] [-d DATE] [-V VERSION] [-m MIDDLE] [-s SYNOPSIS] [-SECNUM] [FILE]
+.PP
+.SH DESCRIPTION
+.PP
+Simple ad hoc generation of Unix man pages from markdown files. It includes customizations and ability to supply additional information or formatting needed for man pages not found in traditional markdown. For example, you can add a synopsis section from a command's help message, convert the title header into the name section, or add a description header before the first paragraph. This allows any markdown document to become a manual, including this very README.
+.PP
+.SH OPTIONS
+.TP
+\fB-c\fP
+Disable auto capitalization of titles and section headers.
+.PP
+.TP
+\fB-C\fP
+Enable auto capitalization of titles and section headers (default).
+.PP
+.TP
+\fB-t TITLE\fP
+Title displayed at top of man page, usually name of program. Defaults to file name or 'stdin'.
+.PP
+.TP
+\fB-d DATE\fP
+Date man page was updated, displayed at bottom center. Defaults to current date in YYYY-MM-DD format.
+.PP
+.TP
+\fB-V VERSION\fP
+Version number of program being documented, displayed at bottom left.
+.PP
+.TP
+\fB-m MIDDLE\fP
+Text displayed at top middle of manual. Defaults to name of manual section.
+.PP
+.TP
+\fB-n\fP
+Convert the first header into a name section at the top of the man page.
+.PP
+.TP
+\fB-s SYNOPSIS\fP
+Text to be inserted as a synopsis section at the top of the man page, under name section.
+.PP
+.TP
+\fB-D\fP
+Add description header to the top of the man page, under name or synopsis sections if supplied. This allows most standard markdown documents to conform to the man page convention where the first paragraphs are in the description section.
+.PP
+.TP
+\fB-SECTION\fP
+Set man page section number, be can number from 1 to 8:
+.PP
+.IP \(bu 8
+\fB1\fP: General commands
+.IP \(bu
+\fB2\fP: System calls
+.IP \(bu
+\fB3\fP: Library functions (eg C standard library)
+.IP \(bu
+\fB4\fP: Special files and drivers (eg /dev)
+.IP \(bu
+\fB5\fP: File formats and conventions
+.IP \(bu
+\fB6\fP: Games and screensavers
+.IP \(bu
+\fB7\fP: Miscellaneous
+.IP \(bu
+\fB8\fP: System admin commands and daemons
+.TP
+\fB-h\fP
+Print help and exit.
+.PP
+.TP
+\fB-v\fP
+Print version info and exit.
+.PP
+.SH USAGE
+.PP
+Convert this README into a man page:
+.PP
+.RS 4
+.EX
+
+markman -Dn -s "`markman -h 2>&1 | cut -d' ' -f2-`" -t $(EXE) -d "`date '+%B %Y'`" -V $(VERSION) README.md > $(EXE).1
+
+.EE
+.RE
+.SH SEE ALSO
+.PP
+See project at <https://edryd.org/projects/markman>
+.PP
+.PP
+View source code at <https://git.edryd.org/markman>
+.PP
+.PP
+Projects which use markman to generate their man pages:
+.PP
+.IP \(bu 2
+markman
+.IP \(bu
+eevo
+.IP \(bu
+gst
+.PP
+Pandoc is also a great alternative for a more general purpose markdown converter.
+.PP
+.SH AUTHOR
+.PP
+Edryd van Bruggen <ed@edryd.org>
+.PP
+.SH LICENSE
+.PP
+zlib License
+.PP
+
