bug-texinfo
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Suggestions for dircategory values and /info/dir structure


From: Peter J. Farley III
Subject: Suggestions for dircategory values and /info/dir structure
Date: Sat, 02 Mar 2002 13:58:29 -0500

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)




reply via email to

[Prev in Thread] Current Thread [Next in Thread]