src2man(1)

✨ src2man ✨ (section 1 of the manual, bestie)

---

okay so you know how man pages are like... the whole point? and you know how you're supposed to write them in a completely different file from your actual code? yeah. src2man said "not on my watch" and honestly she ate. 💅

🎀 NAME 🎀

src2man — extract man pages from source files. literally pulls documentation straight out of your code, no cap.

🌸 SYNOPSIS 🌸

src2man [-n][-d date][-v volume][-r release] [srcfile ...]

🦋 DESCRIPTION 🦋

So here's the vibe: src2man scans a source file — that's your srcfile — and rn only C source files are supported. Only C. We're not doing your Rust today, sorry bestie. 😭

The way it works is iconic: any comment block that starts with /** num, where num is a section number, gets converted into a man file. And who does the actual converting? That's txt2man(1), our girl.

The first line of that comment block has to hold the name of the manpage — usually the function name — then a -, then a short description. After that, the following lines become the DESCRIPTION section content… unless they're in ALL UPPER CASE, in which case they define a brand new section. Uppercase = new section, periodt. 👑

Now, here's the little detail that changes everything: if the next line after a comment block is empty, then no SYNOPSIS section gets generated. But if it's not empty, src2man goes hunting through the following source lines looking for a function prototype or a type definition (struct, union, typedef, ...) that matches the manpage name, and drops it into a SYNOPSIS section. Which is lowkey genius because it means you don't have to duplicate the type or the function prototype inside the comment block. obsessed. 🫶

Also, real talk, the best place for code documentation is in the source file — you know, where the body is actually implemented — and not the header file, which literally only contains the prototype. So src2man automatically searches for the presence of a prototype in the corresponding header file, and if it finds one, it will print a "#include" statement in the synopsis. it's giving thoughtful. ✨

💅 OPTIONS 💅

• -d date — sets the date of the man pages. defaults to the current date.
• -n — no man page is created, bestie. instead, the names of the manpages that would have been created are printed. a little window shopping. 🛍️
• -v volume — specify the name of the volume to be printed in the center header of the generated manpages.
• -r release — specify the project name and release number for the generated manpage.

🌈 ENVIRONMENT 🌈

• SOURCE_DATE_EPOCH — a Unix timestamp that is used for the date in the header instead of the current date. (reproducible builds girlies rise up 🧚)

💖 EXAMPLE 💖

The following example displays C code and comments to generate a manpage foobar.3:

     /** 3
      * foobar - a sample dummy function
      * This line is now the first of the description section.
      * Note that function parameters parm1 and parm2 are highlighted
      * in the generated man page.
      */
     int foobar(char *parm1, int parm2)
     {
        ...
        return 0;
     }

(and yes, that's <purple>parm1</purple> and <purple>parm2</purple> getting their moment in the spotlight in the generated man page — main character energy for your parameters fr fr 💜)

👑 SEE ALSO 👑

txt2man(1), bookman(1).

🍓 AUTHOR 🍓

Marc Vertes <mvertes@free.fr>

---

and that's the whole page, no notes. this one ships as part of txt2man-1.7.1, dated 09 May 2025 — go forth and document your source files where they actually live, slay, bye!! 💖✨🎀🦋🌸💅🫶