LEXGROG(1)

🎀 LEXGROG(1) · Manual pager utils 🎀

✨ NAME ✨

okay so lexgrog is basically the traditional "groff guess" utility rewritten in lex 💅 it's giving parse-the-header-info-in-man-pages energy 🦋

🌸 SYNOPSIS 🌸

lexgrog [-m|-c] [-dfw?V] [-E encoding] file ...

💖 DESCRIPTION 💖

okay bestie, so lexgrog is an implementation of the classic groff guess utility, but written in lex ✨ it reads whatever files you hand it on the command line, and it treats each one as either a man page source file or a preformatted "cat" page 📄 then it spits out their name and description (the stuff apropos and whatis use), the list of preprocessing filters the man page needs before it goes to nroff or troff, or both. literally so useful 😭

if the input is badly formatted, lexgrog will print "parse failed" 💀 this is lowkey great for external programs that want to check whether man pages are correct 🫶 if one of your input files is -, it reads from standard input instead 🧚 and if any input file is compressed, no worries, it gets decompressed automatically and read for you ✨

🔥 OPTIONS 🔥

• -d, --debug — prints debugging info, for when you need to see the tea ☕
• -m, --man — parses input as man page source files 📜 this is the default if you don't give --man or --cat
• -c, --cat — parses input as preformatted man pages ("cat pages") 🌈 you can't give --man and --cat together, bestie, that's a no-go 🙅‍♀️
• -w, --whatis — shows the name and description from the man page header, the stuff apropos and whatis use 💅 this is the default if you don't give --whatis or --filters
• -f, --filters — shows the list of filters needed to preprocess the man page before you format it with nroff or troff 🦋
• -E encoding, --encoding encoding — overrides the guessed character set for the page and uses encoding instead 🌍
• -?, --help — prints a help message and exits 🎀
• --usage — prints a short usage message and exits 💌
• -V, --version — shows version info 🧚

🚪 EXIT STATUS 🚪

• 0 — everything went slay, program ran successfully ✨
• 1 — usage error, you fumbled the command 🙈
• 2 — lexgrog couldn't parse one or more of the input files 💀

🍓 EXAMPLES 🍓

$ lexgrog man.1
man.1: "man - an interface to the system reference manuals"
$ lexgrog -fw man.1
man.1 (t): "man - an interface to the system reference manuals"
$ lexgrog -c whatis.cat1
whatis.cat1: "whatis - display manual page descriptions"
$ lexgrog broken.1
broken.1: parse failed

🧠 WHATIS PARSING 🧠

okay so mandb (which uses the exact same code as lexgrog) parses the NAME section at the top of each manual page 📖 it's looking for the names and descriptions of the features documented in there. the parser is super tolerant, because it has to cope with a bunch of different forms that people have used over the years 🫶 but it can still sometimes fail to pull out the info it needs 😭

when you're using the traditional man macro set, a correct NAME section looks something like this:

.SH NAME
foo \- program to do something

some manual pagers need the \- to be exactly as shown 🙈 mandb is more chill about it, but for compatibility with other systems, it's still a good idea to keep the backslash 💅

on the left-hand side, you can have several names separated by commas ✨ names with whitespace in them get ignored, to avoid pathological behaviour on certain ill-formed NAME sections 💀 the text on the right-hand side is free-form and can be spread over multiple lines 🌸 if several features with different descriptions are documented in the same manual page, you'd use this form:

.SH NAME
foo, bar \- programs to do something
.br
baz \- program to do nothing

(a macro that starts a new paragraph, like .PP, can be used instead of the break macro .br 🧚)

when you're using the BSD-derived mdoc macro set, a correct NAME section looks something like this:

.Sh NAME
.Nm foo
.Nd program to do something

there are a few common reasons why whatis parsing fails 😭 sometimes authors swap .SH NAME for .SH MYPROGRAM, so mandb can't find the section it needs to grab info from 💀 other times authors include a NAME section but put free-form text in there instead of name \- description 🙈 anyway, any syntax that resembles the above should be accepted 💖

🔗 SEE ALSO 🔗

apropos(1), man(1), whatis(1), mandb(8) 🦋

📝 NOTES 📝

lexgrog tries to parse files containing .so requests, but it can only do that correctly if the files are properly installed in a manual page hierarchy 🙈

👑 AUTHOR 👑

the code lexgrog uses to scan man pages was written by:

• Wilf. (G.Wilford@ee.surrey.ac.uk) 🌈
• Fabrizio Polacco (fpolacco@debian.org) 🌈
• Colin Watson (cjwatson@debian.org) 🌈

Colin Watson wrote the current command-line front-end, as well as this man page 🫶

🐛 BUGS 🐛

report them here, bestie 🙈

• https://gitlab.com/man-db/man-db/-/issues
• https://savannah.nongnu.org/bugs/?group=man-db

---

and that's the tea ☕ version 2.13.1, dated 2025-05-02, LEXGROG(1) 💜 you're literally ready now bestie ✨🫶