Suggestions for dircategory values and /info/dir structure

[Peter J. Farley III]

Hi all,

Hoping I don't get too many brickbats thrown at me, I am posting these 
suggestions to this list on the recommendation of Eli Zaretskii.

As an occasional participant in the djgpp-workers list, I found some 
time to work on the info documentation side of things there, and found 
the current use of @dircategory/@direntry in the DJGPP ported GNU 
packages woefully lacking.  Then I found that the GNU packages 
themselves don't use them consistently either.  Then I actually read 
the texinfo documentation and saw the extremely sparse recommendations 
for @dircategory values and "/info/dir" structure, and that's what 
prompted this note.

Here is the current recommendation text, reformatted to make the list 
of values clearer:

"Here are some recommended @dircategory categories:

`GNU packages',
`GNU programming tools',
`GNU programming documentation',
`GNU Emacs Lisp',
`GNU libraries',
`Linux',
`TeX',
`Individual utilities'.

The idea is to include the `invoking' node for every program installed
by a package under `Individual utilities', and an entry for the manual
as a whole in the appropriate other category."

I would like to suggest a richer list of categories, and a structural 
formatting recommendation that makes the "/info/dir" file more useful 
to newbies and experts alike, IMHO.

First, the expanded categories:

`GNU packages',
`GNU programming tools',
`GNU C/C++ programming documentation',
`GNU other programming documentation',
`GNU Emacs Lisp',
`GNU C/C++ libraries',
`GNU other libraries',
`GNU tools for maintaining source',
`GNU utilities',
`Linux',
`TeX',
`Individual utilities, by containing package',
`Individual utilities, by name'.

I would also recommend adding to the structure of "/info/dir" as 
follows:

"The idea is to include the `invoking' node for every program installed
by a package under `Individual utilities, by name', and an entry for 
the manual as a whole in the appropriate other category.  Under 
`Individual utilities, by containing package', packages would repeat 
their `invoking' menu entries in sub-sections by name of the package, 
and by the functional subcategory of programs in that package, where 
appropriate, in the format `package-name: functional description'."

An example will make things clearer.  Below is main contents of what 
the "info/dir" file would contain if only the three packages binutils, 
diffutils and fileutils were installed in "/info/dir".  Note that 
binutils and fileutils have functional subcategories, whereas diffutils 
does not, as every program in diffutils performs similar functions.

GNU packages

* Binutils: (binutils).         The GNU binary utilities
* Diffutils: (diff).            GNU difference utilities
* File utilities: (fileutils).  GNU file utilities


Individual utilities, by containing package


Binutils: archive utilities

* ar: (binutils)ar.             Create, modify, and extract from 
archives
* ranlib: (binutils)ranlib.     Generate index to archive contents

Binutils: object file utilities

* addr2line: (binutils)addr2line.       Convert addresses to file and 
line
* c++filt: (binutils)c++filt.   Filter to demangle encoded C++ symbols
* cxxfilt: (binutils)c++filt.   Filter to demangle encoded C++ symbols
* nlmconv: (binutils)nlmconv.   Converts object code into an NLM
* nm: (binutils)nm.             List symbols from object files
* objcopy: (binutils)objcopy.   Copy and translate object files
* objdump: (binutils)objdump.   Display information from object files
* size: (binutils)size.         List section sizes and total size
* strings: (binutils)strings.   List printable strings from files
* strip: (binutils)strip.       Discard symbols

Binutils: GNU assembler, profiler and linker

* as: (as).                     The GNU assembler
* gasp: (gasp).                 The GNU Assembler Preprocessor
* gprof: (gprof).               The GNU profiler
* ld: (ld).                     The GNU linker


Diffutils

* cmp: (diff)Invoking cmp.      Find first difference
* diff: (diff)Invoking diff.    Compare two files
* diff3: (diff)Invoking diff3.  Compare three files
* patch: (diff)Invoking patch.  Update source files given output of 
diff
* sdiff: (diff)Invoking sdiff.  Compare files side by side and merge 
them

Fileutils: Directory listing

* ls: (fileutils)ls invocation.                 List directory contents
* dir: (fileutils)dir invocation.               List directories 
briefly
* vdir: (fileutils)vdir invocation.             List directories 
verbosely
* dircolors: (fileutils)dircolors invocation.   Color setup for ls

Fileutils: Basic operations

* cp: (fileutils)cp invocation.                 Copy files
* dd: (fileutils)dd invocation.                 Copy and convert a file
* install: (fileutils)install invocation.       Copy and change 
attributes
* mv: (fileutils)mv invocation.                 Rename files
* rm: (fileutils)rm invocation.                 Remove files

Fileutils: Special file types

* ln: (fileutils)ln invocation.         Make links between files
* mkdir: (fileutils)mkdir invocation.   Create directories
* mkfifo: (fileutils)mkfifo invocation. Create FIFOs: (named pipes)
* mknod: (fileutils)mknod invocation.   Create special files
* rmdir: (fileutils)rmdir invocation.   Remove empty directories

Fileutils: Changing file attributes

* chown: (fileutils)chown invocation.   Change file owners/groups
* chgrp: (fileutils)chgrp invocation.   Change file groups
* chmod: (fileutils)chmod invocation.   Change file permissions
* touch: (fileutils)touch invocation.   Change file timestamps

Fileutils: Disk usage

* df: (fileutils)df invocation.         Report filesystem disk usage
* du: (fileutils)du invocation.         Report on disk usage
* sync: (fileutils)sync invocation.     Synchronize memory and disk


Individual utilities, by name

* ar: (binutils)ar.             Create, modify, and extract from 
archives
* ranlib: (binutils)ranlib.     Generate index to archive contents
* addr2line: (binutils)addr2line.       Convert addresses to file and 
line
* c++filt: (binutils)c++filt.   Filter to demangle encoded C++ symbols
* cxxfilt: (binutils)c++filt.   Filter to demangle encoded C++ symbols
* nlmconv: (binutils)nlmconv.   Converts object code into an NLM
* nm: (binutils)nm.             List symbols from object files
* objcopy: (binutils)objcopy.   Copy and translate object files
* objdump: (binutils)objdump.   Display information from object files
* size: (binutils)size.         List section sizes and total size
* strings: (binutils)strings.   List printable strings from files
* strip: (binutils)strip.       Discard symbols
* as: (as).                     The GNU assembler
* gasp: (gasp).                 The GNU Assembler Preprocessor
* gprof: (gprof).               The GNU profiler
* ld: (ld).                     The GNU linker
* cmp: (diff)Invoking cmp.      Find first difference
* diff: (diff)Invoking diff.    Compare two files
* diff3: (diff)Invoking diff3.  Compare three files
* patch: (diff)Invoking patch.  Update source files given output of 
diff
* sdiff: (diff)Invoking sdiff.  Compare files side by side and merge 
them
* ls: (fileutils)ls invocation.                 List directory contents
* chgrp: (fileutils)chgrp invocation.   Change file groups
* chmod: (fileutils)chmod invocation.   Change file permissions
* chown: (fileutils)chown invocation.   Change file owners/groups
* cp: (fileutils)cp invocation.                 Copy files
* dd: (fileutils)dd invocation.                 Copy and convert a file
* df: (fileutils)df invocation.         Report filesystem disk usage
* dir: (fileutils)dir invocation.               List directories 
briefly
* dircolors: (fileutils)dircolors invocation.   Color setup for ls
* du: (fileutils)du invocation.         Report on disk usage
* install: (fileutils)install invocation.       Copy and change 
attributes
* ln: (fileutils)ln invocation.         Make links between files
* mkdir: (fileutils)mkdir invocation.   Create directories
* mkfifo: (fileutils)mkfifo invocation. Create FIFOs: (named pipes)
* mknod: (fileutils)mknod invocation.   Create special files
* mv: (fileutils)mv invocation.                 Rename files
* rm: (fileutils)rm invocation.                 Remove files
* rmdir: (fileutils)rmdir invocation.   Remove empty directories
* sync: (fileutils)sync invocation.     Synchronize memory and disk
* touch: (fileutils)touch invocation.   Change file timestamps
* vdir: (fileutils)vdir invocation.             List directories 
verbosely

In support of my recommendations, I would argue that sometimes a user 
of info needs to perform a task, but doesn't know what program will 
help perform that task.  What the user needs in this common case is a 
*functional* categorization of what the programs do in addition to the 
"package" and "individual utility" breakdowns.  Adding this level of 
documentation helps newbies and "experts" alike, as even an "expert" is 
not an expert in all things, and sometimes needs to do something they 
have never before done.

I also realize that an update to makeinfo would be needed to support 
the concept of structuring the `Individual utilities, by containing 
package' sections.  I am open to better ideas of how to do this while 
retaining the concept.  Perhaps a new directive, "@dirsubcategory", 
would be appropriate.

Expanding the recommended list of categories provides (to me) a clearer 
breakdown of the many GNU packages available.  I *could* argue for an 
even *more* detailed set of categories, but I suggest these as a place 
to begin the discussion.
---------------------------------------------------------
Peter J. Farley III (address@hidden)