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 ([EMAIL PROTECTED]) _______________________________________________ Bug-texinfo mailing list [EMAIL PROTECTED] http://mail.gnu.org/mailman/listinfo/bug-texinfo
