Converting GNU info files to a man(1) page

So you've built a lovely piece of software or installed a pre-built version and find there is a gi-normous set of GNU info files that document it. You could use the info command. However, if you refer to the documentation frequently and don't remember exactly which info node has that special argument then inf2manp might be the answer.

inf2manp converts GNU info file(s) to a monolithic man page. Not intended to be pretty but simply make the info data available in a pager for searching.

Texinfo is the documentation tool of choice by GNU projects. It specifically excludes creation of man page output even though it creates many others. The rationale was that Texinfo is used to create documentation, not quick references like man pages.

Ironically, many GNU softwares include a man page that may give some minimal information and then directs the user to use `info' to access the rest of documentation. This seems silly. For instance, gawk is an enhancement to the the original awk. gawk has many subtleties and in-depth use generally requires several visits to the documentation to find function names and syntax, etc.

info gawk doesn't provide a "search all" function and it can take considerable time to find the topic of interest. Having all of the document in one man page makes it easy to use the pager's search function to home in on subjects quickly. Its about writing code and not spending time trying to find syntax or fighting we a tool that neither allows book marks nor will return to the previous position in a node that has already been viewed.

GNU info made sense back in the day when memory was limited but in 2016 it's no big deal to generate and browse a 75,000 line man page (libc) created from the GNU info files and search up the 'C' function and write some code.

This awk script totally abuses the man page conventions and just dumps the meaningful bits of the info file(s) onto stdout. It does try to put meaningful references in column 1 so the start-of-line anchor (^) gets to the material quickly.

In between --- Upcoming, searchable, sections: and --- End searchable is a list of items with descriptions. The items will occur later in the output so /^item in a pager will get you there in a hurry.

The output is not perfectly formatted, that is sacrificed for speed. No text re-flow. Whatever texinfo output is put in the man page verbatim. If the subject matter needs intense study I suggest you use texinfo to create a PDF file from original input, not the info files, and print it out or use your favourite PDF viewer.

Here's an example using sed's info files:

inf2manp | nroff -man | less

inf2manp can handle more than one input file. So for libc, using a bash shell:

`inf2manp{1,2,3,4,5,6,7,8,9,10} | nroff -man | less`