X-Authentication-Warning: delorie.com: mailnull set sender to djgpp-workers-bounces using -f Message-Id: <5.1.0.14.2.20020224202214.00ab8e50@mail.dorsai.org> X-Sender: pjfarley AT mail DOT dorsai DOT org X-Mailer: QUALCOMM Windows Eudora Version 5.1 Date: Sun, 24 Feb 2002 21:33:18 -0500 To: djgpp-workers AT delorie DOT com From: "Peter J. Farley III" Subject: Dircategories and (tex|txi|texi|texinfo]) files Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii"; format=flowed Reply-To: djgpp-workers AT delorie DOT com Hi all, It's been a while, and I'm not sure how much time I can personally devote to resolving this, but Rich Dawe suggested I bring this issue to the list, so here it is. I decided to rejeuvenate my DJGPP installation with the latest v2.03 refresh zips, and also decided to try to use zippo to perform the installation. The particular problem that came up during that effort was that the "install-info" post-install tasks performed by zippo left the "info/dir" file in *terrible* condition, because many of the GNU packages do not use the "@dircategory" and "@direntry" commands. Those that have anything at all (and some have none) use the "@format" command and directly specify the info command "START-INFO-DIR-ENTRY", and do *not* specify the "INFO-DIR-SECTION" entry. This all results (after a large number of zippo installs) in a DJGPP "info/dir" file with almost everything under the "Miscellaneous" section, and most of DJGPP's careful work in organizing the "info/dir" contents gone to heck in a handbasket. The result is unusable as an information resource unless you already know the name of the utility or package you want information about. If you type just "info" to *look* for the right tool to use (which I find myself doing as often as not), the mess you have to look through is very much less than helpful. Now, I already know that the failure to specify info section names is *not* the fault of anyone on *this* list. However, if zippo is going to be the installation tool of the future of DJGPP, some decisions need to be made, and some work thereafter needs to be done. There are a few alternatives AFAICS, not necessarily mutually exclusive: 1. DJGPP package maintainers (and/or volunteers like me) attack the root of the problem, and update GNU package texinfo files to use both the "@dircategory" and "@direntry" commands instead of specifying the "START-INFO-DIR-ENTRY" directly. And submit these patches to the appropriate GNU buglists, of course. 2. Patch the DJGPP-released source files to at least specify the same "@dircategory" or "INFO-DIR-SECTION" name as is already used in the hand-crafted DJGPP "info/dir" file. These would *not* be submitted to the GNU maintainers, and would add a continuing extra burden on DJGPP package porters/maintainers. 3. Update zippo to look at the texinfo files it is going to run an install-info on and programmatically replace all "START-INFO-DIR-ENTRY" lines (or at least the ones it "knows" about via some database of known packages) with the appropriate "@dircategory" and "@direntry" lines. This is tricky, but should be possible, at least for the "root" info files that are installed by zippo. "@include" files would obviously be more difficult to process, and would not be processed in an initial release. 4. Change zippo DSM files *not* to use "install-info" for packages already carefully hand-inserted into the DJGPP "info/dir" file. Run "install-info" *only* for those packages that already use "@dircategory" commands, and update the hand-crafted DJGPP "info/dir" file to match them. Vis-a-vis alternative #3, there *is* a recommendation in the GNU Programming Standards document about how "info/dir" files should be structured and sectioned. I quote from the GNU standard, slightly reformatted to make it 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." Now, the suggested standard in the last sentence is *much* harder to do, since it requires multiple "@dircategory" and "@direntry" changes/additions to package texinfo files, but IMHO if we can at least get the "@dircategories" to accord with the standard, we will have contributed something to the community as a whole, as well as to ourselves. I personally don't agree with the GNU standard section names; I don't think there are enough of them. They're too broad, and not necessarily all that helpful as they stand. *HOWEVER*, they are there as a recommended standard, and at least they provide a place to begin. Vis-a-vis alternative #4, I compiled a list from the packages that I have downloaded of which ones use "@dircategory", and if so what name they use. Below is that list, and hopefully it won't wrap too badly: Name texinfo filename dirent dircat Section name used --------- ------------------ ------ ------ --------------------- a2ps a2ps.texi Y Y Printing Tools autoconf autoconf.texi Y Y GNU Admin autoconf standards.texi N N automake automake.texi Y Y Utilities bc bc.texi Y Y Utilities bc dc.texi Y Y Utilities binutils binutils.texi N N binutils as.texinfo N N binutils bfd.texinfo N N binutils ld.texinfo N N binutils ldint.texinfo N N binutils gprof.texi N N bool None bash bashref.texi Y Y Utilities bash rluserman.texinfo Y Y Libraries bison bison.texinfo N N diff diff.texi Y Y Diffutils djNNN203 (None) N N enscript enscript.texi Y Y Utilities faq djgppfaq.txi Y Y From faqNNNb.zip fileutils fileutils.texi N N find find.texi N N flex flex.texi N N gcc gcc.texi Y Y Programming gcc cpp.texi Y Y Programming gcc g77.texi Y Y Programming gdb gdb.texinfo Y Y Programming & development tools. *Note 1 gdbm gdbm.texinfo Y N gpp (Not Available) gperf gprf.texi Y Y Programming Tools grep grep.texi Y N groff groff.texinfo Y Y Miscellaneous gettext gettext.texi Y Y GNU Gettext Utilities gawk gawk.texi Y Y Programming Languages gzip gzip.texi Y Y Utilities hello hello.texi N N *Note 2 id-utils id-utils.texi N N indent indent.texinfo Y Y Indent Code Formatter lcset (None) iconv (None) less (None) m4 m4.texinfo N N make make.texinfo Y Y GNU Packages misc (None) p2c (None) patch (None) perl (None) *Note 3 sed sed.texi Y N sharutils sharutils.texi N N sh-utils sh-utils.texi N N tar tar.texi N N texinfo texinfo.txi Y Y Texinfo documentation system textutils textutils.texi N N which which.texinfo N N *Note 2 *Note 1 -- Main texinfo file has direntry/category, others do not. *Note 2 -- No START-INFO-DIR-ENTRY either. *Note 3 -- Uses POD format for docs. --------------------------------------------------------- Peter J. Farley III (pjfarley AT dorsai DOT org)