Readme reader like man

The GNU C library has a reference manual that includes documentation for all or most of the data structures in the standard library and extensions. This has a type index. Beware there's also a "GNU C Reference Manual", but it and the "GNU C Library Reference Manual" are two different things.

You can also autogenerate documentation sufficient for browsing data structures with doxygen (note that it works much better with stuff that's actually annotated for it, but it can be crudely used this way). I tried this here on /usr/include and it took < 2 minutes (producing, n.b., ~800 MB of html). The steps were:

1. Create a basic config file somewhere (anywhere), doxygen -g doxygen.conf.

2. Edit the file and change the following settings:

   OUTPUT_DIRECTORY       = /home/foo/whatever # documentation goes here
   OPTIMIZE_OUTPUT_FOR_C  = YES
   EXTRACT_ALL            = YES
   INPUT                  = /usr/include
   FILE_PATTERNS          = *.h
   RECURSIVE              = YES
   GENERATE_LATEX         = NO
   

   Note that all those already exist in the config file, you need to search through and change/set the values as shown.

3. Generate: doxygen doxygen.conf.

Now open /home/foo/whatever/html/files.html. There is an index.html, but it is probably WTF'd up (again, doxygen is primarily intended for stuff that's purposefully annotated for it), so the file list is of the most predicatable entry point. There's also a copious "Data Structure Index", but for whatever reason, not everything you would think is indexed in it. E.g., there's a structstat.html you can reach by following the file list, asm-generic -> stat.h, but "struct stat" is not mentioned in the "Data Structures Index". Many standard C lib things follow this pattern: there's a macro/define/typedef in the predicatable header (sys/stat.h) that pulls in something extern that ends up being in a platform/system specific header in, e.g. asm-generic.h. I'm sure you've noticed this before. The stat example is not so bad in so far as at least the final definition is still called struct stat and not struct _fooX_stat.

So this takes some getting used to and is, in the end, not much better than tooling around with grep. It also has the dis(?)advantage that non-user fields are included (e.g., compare the struct stat as documented above to its description in man 2 stat). For the standard library (and GNU extensions) the reference manual is much better. However, WRT stuff that's not in that manual, it is slightly better than nothing. I'd recommend that if you do want to use it that way, it would be better to do individual directories independently rather than the whole shebang (clue: you can set RECURSION = NO). 800 MB of html is pretty unwieldy.

You need to remove the lines matching /usr/share/man and /usr/share/groff from /etc/dpkg/dpkg.cfg.d/01_nodoc, then reinstall groff, man-db, manpages and any other package whose manpages you want to restore. The cp manpage for example is in the coreutils package.