Re: Nice indentation for info allowed?

[karl]

    After a successful trial with `info´ file `texinfo´ I have
    reformatted `texinfo.txi´ (without touching the wording) to include
    it here as a proposal; please see the diff output attached below.

Dietrich, thanks for this suggestion (from March 2000!).  However, I
confess that I prefer the @direntry in texinfo.txi as it stands. It is
traditional to put the node name (`Invoking install-info', etc.)
directly after the ).  I suspect some software wouldn't work if it was
moved as you suggest; I don't see any compelling reason to move it.

There are no real standards for how to create these @direntry's.  That
means they don't all look perfectly nice together.  Perhaps the way
texinfo.txi does it will make more sense to you if you look at the dir
file I myself use, which I've also appended.  (It's in the Texinfo
distribution as dir-example.)

Thanks,
karl



diff -C 5 texinfo.txi.proposed texinfo.txi > texinfo.txi.diff

*** texinfo.txi.proposed        Thu Mar 16 10:40:21 2000
--- texinfo.txi Tue Sep 28 21:38:01 1999
***************
*** 23,40 ****
  @comment %**end of header
  
  @dircategory Texinfo documentation system
  @direntry
  * Texinfo: (texinfo).           The GNU documentation format.
! * install-info: (texinfo)       Invoking install-info.
!                                   Update info/dir entries.
! * texi2dvi: (texinfo)           Format with texi2dvi.
!                                   Print Texinfo documents.
! * texindex: (texinfo)           Format with tex/texindex.
!                                   Sort Texinfo index files.
! * makeinfo: (texinfo)           makeinfo Preferred.
!                                   Translate Texinfo source.
  @end direntry
  
  @c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a
  @c prefix arg).  This updates the node pointers, which texinfmt.el needs.
  
--- 23,36 ----
  @comment %**end of header
  
  @dircategory Texinfo documentation system
  @direntry
  * Texinfo: (texinfo).           The GNU documentation format.
! * install-info: (texinfo)Invoking install-info. Update info/dir entries.
! * texi2dvi: (texinfo)Format with texi2dvi.      Print Texinfo documents.
! * texindex: (texinfo)Format with tex/texindex.  Sort Texinfo index files.
! * makeinfo: (texinfo)makeinfo Preferred.        Translate Texinfo source.
  @end direntry
  
  @c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a
  @c prefix arg).  This updates the node pointers, which texinfmt.el needs.
  


This is the directory file `dir' a.k.a. `DIR', which contains the
  topmost node of the Info hierarchy.
This particular dir file is merely made available for your hacking
  pleasure, not official or standard in any way.  If it doesn't make sense
  to you, or you don't like it, ignore it.
If you have dir entries for Texinfo manuals you'd like to be added here,
  please send them to address@hidden

$Id: dir-example,v 1.20 2000/11/11 00:42:17 karl Exp $

File: dir,      Node: Top,      This is the top of the INFO tree.

This is the Info main menu (aka directory node).
A few useful Info commands:

  `q' quits;
  `?' lists all Info commands;
  `h' starts the Info tutorial;
  `mTexinfo RET' visits the Texinfo manual, etc.

Not all of the topics shown below may be available on this system.

* Menu:

GNU Packages
* accounting: (psacct).         GNU process accounting suite.
* Bash: (bash).                 Bourne-Again SHell.
* Cpio: (cpio).                 Copy-in-copy-out archiver.
* DC: (dc).                     Postfix desk calculator.
* Diff: (diff).                 Comparing and merging programs.
* Ed: (ed).                     Line editor.
* Emacs: (emacs).               Extensible self-documenting text editor.
* File utilities: (fileutils).  GNU file utilities.
* Finding files: (find).        Operating on files matching certain criteria.
* Font utilities: (fontu).      Programs for font manipulation.
* Gawk: (gawk.info).            A text scanning and processing language.
* Gcal: (gcal).                 GNU calendar program.
* Gzip: (gzip).                 General (de)compression.
* Identifier DB: (id-utils).    Identifier database utilities.
* Ispell: (ispell).             Interactive spelling corrector.
* M4: (m4).                     Macro processor.
* Make: (make).                 Remake files automatically.
* Ptx: (ptx).                   Permuted index generator.
* Shar utilities: (sharutils).  Shell archiver, uudecode/uuencode.
* Shell utilities: (sh-utils).  GNU shell utilities.
* tar: (tar).                   Making tape (or disk) archives.
* Text utilities: (textutils).  GNU text utilities.
* Time: (time).                 Measuring program resource usage.
* UUCP: (uucp).                 Copying between machines, offline.
* Wdiff: (wdiff).               Word-by-word comparison.
* Wget: (wget).                 URL download.

GNU programming tools
* As: (as).                     Assembler.
* Binutils: (binutils).         ar/copy/objdump/nm/size/strip/ranlib.
* Bison: (bison).               LALR(1) parser generator.
* CPP: (cpp).                   C preprocessor.
* CVS: (cvs).                   Concurrent versions system for source control.
* DejaGnu: (dejagnu).           Testing framework.
* egcs: (egcs).                 Experimental GNU C compiler.
* g77: (g77).                   GNU Fortran 77 compiler.
* Flex: (flex).                 A fast scanner generator.
* Gasp: (gasp).                 GNU Assembler preprocessor.
* Libtool: (libtool).           Generic library support script.
* GCC: (gcc).                   C compiler.
* GDB: (gdb).                   Source-level debugger for C and C++.
* Gettext Utilities: (gettext). GNU gettext utilities.
* Gperf: (gperf).               Perfect hash function generator.
* Gprof: (gprof).               Profiler.
* Indent: (indent).             Prettyprinter for programs.
* Ld: (ld).                     Linker.
* R FAQ: (R-FAQ).               The R statistical language FAQ.

Texinfo documentation system
* Info: (info).                 Documentation browsing system.
* Texinfo: (texinfo).           The GNU documentation format.
* info program: (info-stnd).    Standalone Info-reading program.
* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
* texi2dvi: (texinfo)Format with texi2dvi.      Printing Texinfo documentation.
* texindex: (texinfo)Format with tex/texindex.  Sorting Texinfo index files.
* makeinfo: (texinfo)makeinfo options.  Translate Texinfo source.

Printing Tools
* a2ps: (a2ps).                    PostScript Generating Utility
* PreScript: (a2ps) PreScript.     Input language for a2ps
* card: (a2ps) card.               Print Reference Cards
* fixps: (a2ps) fixps.             Fixing Some Ill Designed PostScript Files
* fixnt: (a2ps) fixnt.             Fixing Microsoft NT PostScript Files
* pdiff: (a2ps) pdiff.             Produce Pretty Comparison of Files
* psmandup: (a2ps) psmandup.       Printing Duplex on Simplex Printers
* psset: (a2ps) psset.             Inserting calls to setpagedevice

GNU Emacs Lisp
* Elisp: (elisp).               GNU Emacs Lisp reference manual.
* Intro Elisp: (emacs-lisp-intro). Introduction to Elisp programming.

* AUC TeX: (auctex).            Editing (La)TeX files.
* Calc: (calc).                 Calculator and more.
* CC mode: (ccmode).            Editing C, C++, Objective C, and Java.
* Common Lisp: (cl).            Partial Common Lisp support for Emacs Lisp.
* Dired-x: (dired-x).           Extra directory editor features.
* Edebug: (edebug).             Source-level debugger for Emacs Lisp.
* Ediff: (ediff).               Comprehensive visual interface to diff & patch.
* EDB: (edb).                   Database for Emacs.
* Forms: (forms).               Fill-in-the-form data entry.
* Gmhist: (gmhist).             Generic minibuffer history.
* GNUS: (gnus).                 Netnews reading and posting.
* Mailcrypt: (mailcrypt).       Use PGP in Emacs.
* MH-E: (mh-e).                 Emacs interface to the MH mail system.
* PCL-CVS: (pcl-cvs).           Emacs front end to CVS.
* Supercite: (sc).              Supercite for including other people's words.
* VIP: (vip).                   vi emulation.
* VIPER: (viper).               The new VI-emulation mode in Emacs-19.29.
* VM: (vm).                     Mail reader.
* W3: (w3).                     WWW browser.

GNU programming support
* Autoconf: (autoconf).         Automatic generation of package configuration.
* Configure: (configure).       Cygnus configure.
* Gnats: (gnats).               Cygnus bug tracking system.
* help2man: (help2man).         Automatic manual page generation.
* Remsync: (remsync).           Remote synchronization of directory trees.
* Send PR: (send-pr).           Cygnus bug reporting for Gnats.

GNU libraries
* Annotate: (annotate).         High-level GDB to GUI's.
* BFD: (bfd).                   Binary file descriptors for object file IO.
* CVS protocol: (cvsclient).    CVS client/server protocol specification.
* GDB library: (libgdb).        Application programming interface to GDB.
* GDBM: (gdbm).                 Hashed databases.
* GDK: (gdk).                   General drawing kit.
* GTK: (gtk).                   GIMP toolkit.
* History: (history).           Recall previous lines of input.
* Iostream: (iostream).         C++ input/output.
* Libc: (libc).                 C library.
* Libg++: (libg++).             C++ classes.
* Mmalloc: (mmalloc).           Memory-mapped malloc.
* Readline: (readline).         General command-line interface.
* Regex: (regex).               Regular expressions.
* Termcap: (termcap).           All about /etc/termcap.

GNU programming documentation
* GDB internals: (gdbint).      Debugger internals.
* Ld internals: (ldint).        GNU linker internals.
* Maintaining: (maintain).      Maintaining GNU software.
* Source config: (cfg-paper).   Some theory on configuring source packages.
* Stabs: (stabs).               Symbol table debugging information format.
* Standards: (standards).       GNU coding standards.

Linux
* dosemu: (dosemu).             Linux DOS emulator.
* gpm: (gpm).                   Linux general purpose mouse interface.
* linux-faq: (linux-faq).       The Linux FAQ List.

TeX
* Afm2tfm: (dvips)Invoking afm2tfm.  Making Type 1 fonts available to TeX.
* Dvips: (dvips).               DVI-to-PostScript translator.
* Eplain: (eplain).             Expanding on plain TeX.
* Kpathsearch: (kpathsea).      File lookup along search paths.
* LaTeX: (latex).               LaTeX.
* MakeIndex: (makeindex).       Index creation for TeX.
* Naming fonts: (fontname).     Filenames for TeX fonts.
* TDS: (tds).                   Standard TeX directory structure.
* TeXDraw: (texdraw).           Drawing PostScript diagrams within TeX.
* Web2c: (web2c).               TeX, Metafont, and their companion programs.

DOS 
* GNUish: (gnuish).             GNU utilities for DOS.
* Mtools: (mtools).             Access DOS disks from Unix.

Other things
* Amd: (am-utils).              Filesystem automounter.
* CMUCL: (cmu-user).            CMU Common Lisp.
* File headers: (filehdr).      Bibliographic information for computer files.
* GCP: (gcp).                   Game club protocol.
* GIMP: (pdb).                  The GIMP procedural database.
* HTML: (snafu).                Hypertext Markup Language 2.0 specification.
* Jargon: (jargon).             The jargon file.
* JED: (jed).                   JED editor documentation.
* octave: (octave).             Octave - A language for numerical computation.
* Perl: (perl).                 Practical extraction and report language.
* PRCS: (prcs).                 Project revision control system.
* Screen: (screen).             Terminal multiplexer.

Individual utilities
* aclocal: (automake)Invoking aclocal.          Generating aclocal.m4.
* aid: (id-utils)aid invocation.                Matching strings.
* ar: (binutils)ar.                             Create/modify/extract archives.
* at-pr: (gnats)at-pr.                          Bug report timely reminders.
* automake: (automake).                         Making Makefile.in's.
* autoreconf: (autoconf)Invoking autoreconf.    Remake multiple configure's.
* autoscan: (autoconf)Invoking autoscan.        Automate initial configure.in.
* awk: (gawk)Invoking gawk.                     Text processing and scanning.
* basename: (sh-utils)basename invocation.      Strip directory and suffix.
* bibtex: (web2c)BibTeX invocation.             Maintaining bibliographies.
* bzip2: (bzip2).                               (de)compression.
* c++filt: (binutils)c++filt.                   Demangle C++ symbols.
* cat: (textutils)cat invocation.               Concatenate and write files.
* chgrp: (fileutils)chgrp invocation.           Change file groups.
* chmod: (fileutils)chmod invocation.           Change file permissions.
* chown: (fileutils)chown invocation.           Change file owners/groups.
* chroot: (sh-utils)chroot invocation.          Specify the root directory.
* cksum: (textutils)cksum invocation.           Print POSIX CRC checksum.
* cmp: (diff)Invoking cmp.                      Character-by-character diff.
* comm: (textutils)comm invocation.             Compare sorted files by line.
* cp: (fileutils)cp invocation.                 Copy files.
* csplit: (textutils)csplit invocation.         Split by context.
* cut: (textutils)cut invocation.               Print selected parts of lines.
* date: (sh-utils)date invocation.              Print/set system date and time.
* dd: (fileutils)dd invocation.                 Copy and convert a file.
* df: (fileutils)df invocation.                 Report filesystem disk usage.
* diff3: (diff)Invoking diff3.                  Three-way diff.
* dir: (fileutils)dir invocation.               List directories briefly.
* dircolors: (fileutils)dircolors invocation.   Color setup for ls.
* dirname: (sh-utils)dirname invocation.        Strip non-directory suffix.
* dmp: (web2c)Dmp invocation.                   Troff->MPX (MetaPost pictures).
* du: (fileutils)du invocation.                 Report on disk usage.
* dvicopy: (web2c)DVIcopy invocation.           Virtual font expansion
* dvitomp: (web2c)DVItoMP invocation.           DVI to MPX (MetaPost pictures).
* dvitype: (web2c)DVItype invocation.           DVI to human-readable text.
* echo: (sh-utils)echo invocation.              Print a line of text.
* edit-pr: (gnats)Invoking edit-pr.             Changing bugs.
* eid: (id-utils)eid invocation.                Invoking an editor on matches.
* emacsclient: (emacs)Emacs Server.             Connecting to a running Emacs.
* emacsserver: (emacs)Emacs Server.             Connecting to a running Emacs.
* env: (sh-utils)env invocation.                Modify the environment.
* etags: (emacs)Create Tags Table.              Creating a TAGS table.
* expand: (textutils)expand invocation.         Convert tabs to spaces.
* expr: (sh-utils)expr invocation.              Evaluate expressions.
* factor: (sh-utils)factor invocation.          Print prime factors
* false: (sh-utils)false invocation.            Do nothing, unsuccessfully.
* fid: (id-utils)fid invocation.                Listing a file's identifiers.
* file-pr: (gnats)file-pr.                      Processing incoming traffic.
* find: (find)Invoking find.                    Finding and acting on files.
* fmt: (textutils)fmt invocation.               Reformat paragraph text.
* fold: (textutils)fold invocation.             Wrap long input lines.
* g++: (gcc)Invoking G++.                       The GNU C++ compiler.
* gcal2txt: (gcal)Invoking gcal2txt.            Calendar resource to text file.
* gettextize: (gettext)gettextize Invocation.   Prepare a package for gettext.
* gftodvi: (web2c)GFtoDVI invocation.           Generic font proofsheets.
* gftopk: (web2c)GFtoPK invocation.             Generic to packed fonts.
* gftype: (web2c)GFtype invocation.             GF to human-readable text.
* gid: (id-utils)gid invocation.                Listing all matching lines.
* git: (git).                                   GNU interactive tools.
* groups: (sh-utils)groups invocation.          Print group names a user is in.
* gunzip: (gzip)Overview.                       Decompression.
* head: (textutils)head invocation.             Output the first part of files.
* hostname: (sh-utils)hostname invocation.      Print or set system name.
* id: (sh-utils)id invocation.                  Print real/effective uid/gid.
* idx: (id-utils)idx invocation.                Testing mkid scanners.
* ifnames: (autoconf)Invoking ifnames.          List conditionals in source.
* iid: (id-utils)iid invocation.                Interactive complex queries.
* inimf: (web2c)inimf invocation.               Initial Metafont.
* inimp: (web2c)inimp invocation.               Initial MetaPost.
* initex: (web2c)initex invocation.             Initial TeX.
* install: (fileutils)install invocation.       Copy and change attributes.
* join: (textutils)join invocation.             Join lines on a common field.
* kpsewhich: (kpathsea)Invoking kpsewhich.      TeX file searching.
* libtoolize: (libtool)Invoking libtoolize.     Adding libtool support.
* lid: (id-utils)lid invocation.                Matching identifier patterns.
* ln: (fileutils)ln invocation.                 Make links between files.
* locate: (find)Invoking locate.                Finding files in a database.
* logname: (sh-utils)logname invocation.        Print current login name.
* ls: (fileutils)ls invocation.                 List directory contents.
* mail-files: (sharutils)mail-files invocation. Send files to remote site.
* mailshar: (sharutils)mailshar invocation.     Make and send a shell archive.
* makempx: (web2c)MakeMPX invocation.           MetaPost label typesetting.
* maketexmf: (kpathsea)MakeTeX scripts.         MF source generation.
* maketexpk: (kpathsea)MakeTeX scripts.         PK bitmap generation.
* maketextex: (kpathsea)MakeTeX scripts.        TeX source generation.
* maketextfm: (kpathsea)MakeTeX scripts.        TeX font metric generation.
* md5sum: (textutils)md5sum invocation.         Print or check message-digests.
* mf: (web2c)mf invocation.                     Creating typeface families.
* mft: (web2c)MFT invocation.                   Prettyprinting Metafont source.
* mgetty: (mgetty).                             Faxes, voicemail and more.
* mkdir: (fileutils)mkdir invocation.           Create directories.
* mkfifo: (fileutils)mkfifo invocation.         Create FIFOs: (named pipes).
* mkid: (id-utils)mkid invocation.              Creating an ID database.
* mknod: (fileutils)mknod invocation.           Create special files.
* mp: (web2c)mp invocation.                     Creating technical diagrams.
* mpto: (web2c)MPto invocation.                 MetaPost label extraction.
* msgfmt: (gettext)msgfmt Invocation.           Make MO files out of PO files.
* msgmerge: (gettext)msgmerge Invocation.       Update two PO files into one.
* mv: (fileutils)mv invocation.                 Rename files.
* newer: (web2c)Newer invocation.               Compare modification times.
* nice: (sh-utils)nice invocation.              Modify scheduling priority.
* nl: (textutils)nl invocation.                 Number lines and write files.
* nlmconv: (binutils)nlmconv.                   Convert object to NetWare LM.
* nm: (binutils)nm.                             List symbols in object files.
* nohup: (sh-utils)nohup invocation.            Immunize to hangups.
* objcopy: (binutils)objcopy.                   Copy/translate object files.
* objdump: (binutils)objdump.                   Display info from object files.
* od: (textutils)od invocation.                 Dump files in octal, etc.
* paste: (textutils)paste invocation.           Merge lines of files.
* patch: (diff)Invoking patch.                  Automatically applying diffs.
* patgen: (web2c)Patgen invocation.             Creating hyphenation patterns.
* pathchk: (sh-utils)pathchk invocation.        Check file name portability.
* pid: (id-utils)pid invocation.                Looking up filenames.
* pktogf: (web2c)PKtoGF invocation.             Packed to generic fonts.
* pktype: (web2c)PKtype invocation.             PK to human-readable text.
* pltotf: (web2c)PLtoTF invocation.             Property list to TFM.
* pooltype: (web2c)Pooltype invocation.         Display WEB pool files.
* pr-addr: (gnats)pr-addr.                      Bug report address retrieval.
* pr-edit: (gnats)pr-edit.                      The edit-pr driver.
* pr: (textutils)pr invocation.                 Paginate or columnate files.
* printenv: (sh-utils)printenv invocation.      Print environment variables.
* printf: (sh-utils)printf invocation.          Format and print data.
* pwd: (sh-utils)pwd invocation.                Print working directory.
* query-pr: (gnats)Invoking query-pr.           Bug searching/reporting.
* queue-pr: (gnats)queue-pr.                    Handling incoming traffic.
* ranlib: (binutils)ranlib.                     Index archive file contents.
* rm: (fileutils)rm invocation.                 Remove files.
* rmdir: (fileutils)rmdir invocation.           Remove empty directories.
* sdiff: (diff)Invoking sdiff.                  Interactively merge files.
* send-pr: (gnats)Invoking send-pr.             Submitting bugs.
* seq: (sh-utils)seq invocation.                Print numeric sequences
* shar: (sharutils)shar invocation.             Create shell archive.
* size: (binutils)size.                         List object file section sizes.
* sleep: (sh-utils)sleep invocation.            Delay for a specified time.
* sort: (textutils)sort invocation.             Sort text files.
* split: (textutils)split invocation.           Split into fixed-size pieces.
* strings: (binutils)strings.                   List printable strings.
* strip: (binutils)strip.                       Discard symbols.
* stty: (sh-utils)stty invocation.              Print/change terminal settings.
* su: (sh-utils)su invocation.                  Modify user and group id.
* sum: (textutils)sum invocation.               Print traditional checksum.
* sync: (fileutils)sync invocation.             Synchronize memory and disk.
* tabs: (tput)Invoking tabs.                    Tab settings.
* tac: (textutils)tac invocation.               Reverse files.
* tail: (textutils)tail invocation.             Output the last part of files.
* tangle: (web2c)Tangle invocation.             WEB to Pascal.
* tcal: (gcal)Invoking tcal.                    Run Gcal with tomorrow's date.
* tee: (sh-utils)tee invocation.                Redirect to multiple files.
* test: (sh-utils)test invocation.              File/string tests.
* tex: (web2c)tex invocation.                   Typesetting.
* tftopl: (web2c)TFtoPL invocation.             TFM -> property list.
* touch: (fileutils)touch invocation.           Change file timestamps.
* tput: (tput)Invoking tput.                    Termcap in shell scripts.
* tr: (textutils)tr invocation.                 Translate characters.
* true: (sh-utils)true invocation.              Do nothing, successfully.
* tty: (sh-utils)tty invocation.                Print terminal name.
* txt2gcal: (gcal)Invoking txt2gcal.            Calendar text to resource file.
* umb-scheme: (umb-scheme).                     UMB Scheme Interpreter.
* uname: (sh-utils)uname invocation.            Print system information.
* unexpand: (textutils)unexpand invocation.     Convert spaces to tabs.
* uniq: (textutils)uniq invocation.             Uniqify files.
* unshar: (sharutils)unshar invocation.         Extract from shell archive.
* updatedb: (find)Invoking updatedb.            Building the locate database.
* users: (sh-utils)users invocation.            Print current user names.
* vdir: (fileutils)vdir invocation.             List directories verbosely.
* vftovp: (web2c)VFtoVP invocation.             Virtual font -> virtual pl.
* view-pr: (gnats)Invoking view-pr.             Showing bug reports.
* virmf: (web2c)virmf invocation.               Virgin Metafont.
* virmp: (web2c)virmp invocation.               Virgin MetaPost.
* virtex: (web2c)virtex invocation.             Virgin TeX.
* vptovf: (web2c)VPtoVF invocation.             Virtual pl -> virtual font.
* wc: (textutils)wc invocation.                 Byte, word, and line counts.
* weave: (web2c)Weave invocation.               WEB to TeX.
* who: (sh-utils)who invocation.                Print who is logged in.
* whoami: (sh-utils)whoami invocation.          Print effective user id.
* xargs: (find)Invoking xargs.                  Operating on many files.
* xgettext: (gettext)xgettext Invocation.       Extract strings into a PO file.
* yes: (sh-utils)yes invocation.                Print a string indefinitely.
* zcat: (gzip)Overview.                         Decompression to stdout.
* zsh: (zsh).                                   An enhanced Bourne shell.