Mail Archives: djgpp-workers/2002/02/24/21:31:27
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)
- Raw text -