txt2man(1)

💖 txt2man 💖

okay bestie gather round, this is the manual for txt2man — the little icon that takes your flat boring ASCII text and ✨*transforms*✨ it into a real-deal manual page. ngl it's giving magic. so without further ado, welcome to section 1, let's get into it 🫶

---

✨ NAME ✨

txt2man — convert flat ASCII text to man page format

---

🌸 SYNOPSIS 🌸

txt2man [-hpTX] [-t mytitle] [-P pname] [-r rel] [-s sect]
        [-v vol] [-I txt] [-B txt] [-d date] [ifile]

---

🦋 DESCRIPTION 🦋

so like. txt2man takes your input text and converts it into nroff/troff standard man(7) macros — you know, the actual stuff that formats Unix manual pages. and it's not just bare minimum either, it can make genuinely nice pages 💅 specially for commands (section 1 or 8) or for C functions reference (sections 2, 3), and it has the ability to recognize and format command and function names, flags, types and arguments. it knows things.

txt2man is also able to recognize and format sections, paragraphs, lists (standard, numbered, description, nested), cross references and literal display blocks. yes. all of that. she ate.

if input file ifile is omitted, standard input is used. result is displayed on standard output. simple as that, no cap.

here's literally how text patterns get recognized and processed:

📌 Sections

these headers are defined by a line in upper case, starting column 1. if there is one or more leading spaces, a sub-section will be generated instead. optionally, the Section name can be preceded by a blank line. this is useful for a better visualization of the source text to be used to generate the manpage 🌈

📌 Paragraphs

they must be separated by a blank line, and left aligned. alternatively two blank spaces can be used to produce the same result. this option will provide a better visualization of the source text to be used to generate the manpage 💫

📌 Tag list

the item definition is separated from the item description by at least 2 blank spaces, even before a new line, if definition is too long. definition will be emphasized by default 👑

📌 Bullet list

bullet list items are defined by the first word being - or * or o. pick your fighter 🎀

📌 Enumerated list

the first word must be a number followed by a dot. 1. 2. 3. periodt.

📌 Literal display blocks

this paragraph type is used to display unmodified text, for example source code. it must be separated by a blank line and be indented by a TAB. it is primarily used to format unmodified source code. it will be printed using fixed font whenever possible (troff). untouched, unbothered, exactly as you wrote it 🧚

📌 Cross references

a cross reference (another man page) is defined by a word followed by a number in parenthesis. iykyk.

---

👑 Special sections: 👑

NAME

the function or command name and short description are set in this section.

SYNOPSIS

this section receives a special treatment to identify command name, flags and arguments, and propagate corresponding attributes later in the text. if a C like function is recognized (word immediately followed by an open parenthesis), txt2man will print function name in bold font, types in normal font, and variables in italic font. the whole section will be printed using a fixed font family (courier) whenever possible (troff).

---

fr fr, it is a good practice to embed documentation into source code, by using comments or constant text variables. txt2man allows one to do that, keeping the document source readable, usable even without further formatting (i.e. for online help) and easy to write. the result is high quality and standard complying document 💖 no notes.

---

💅 OPTIONS 💅

• -h — the option -h displays help. that's it. that's the option 🫶
• -d date — set date in header. defaults to current date.
• -P pname — set pname as project name in header. default to uname -s.
• -p — probe title, section name and volume.
• -t mytitle — set mytitle as title of generated man page.
• -r rel — set rel as project name and release.
• -s sect — set sect as section in heading, usually a value from 1 to 8.
• -v vol — set vol as volume name, i.e. "Unix user 's manual".
• -I txt — italicize txt in output. can be specified more than once.
• -B txt — emphasize (bold) txt in output. can be specified more than once.
• -T — text result previewing using PAGER, usually more(1).
• -X — X11 result previewing using gxditview(1).

---

🌈 ENVIRONMENT 🌈

• PAGER — name of paging command, usually more(1), or less(1). if not set falls back to more(1).
• SOURCE_DATE_EPOCH — Unix timestamp that is used for date in header instead of current date.

---

⭐ EXAMPLES ⭐

try this command to format this text itself:

$ txt2man -h 2>&1 | txt2man -T

the following command will generate a manpage level 1 to foo-1.1.0 program, from foo.txt file, used as source code to previously mentioned manpage:

$ txt2man -d "15 May 2016" -t foo -r foo-1.1.0 -s 1 -v "show stars on screen" foo.txt > foo.1

---

🎀 HINTS 🎀

to obtain an overall good formatting of output document, keep paragraphs indented correctly. if you have unwanted bold sections, search for multiple spaces between words, which are used to identify a tag list (term followed by a description). choose also carefully the name of command line or function parameters, as they will be emphasized each time they are encountered in the document 👀

bestie listen. that last bit is not a joke — name your params wisely or they will be bold every single time they show up. main character behavior but make it embarrassing.

---

🔥 SEE ALSO 🔥

man(1), mandoc(7), rman(1), groff(1), more(1), gxditview(1), troff(1).

---

💀 BUGS 💀

• Automatic probe (-p option) works only if input is a regular file (i.e. not stdin).

so like. pipe it in and -p simply will not do its thing. regular file only, sorry bestie 😭

---

💜 AUTHOR 💜

Marc Vertes <mvertes@free.fr>

---

okay that's the whole thing, you're officially a txt2man girlie now 🌸 go forth and format. mwah 💋

this was txt2man-1.7.1, dated 09 May 2025 — catch you in the next section, love u, bye!! 🫶✨