branch master updated: Documentation of @dircategory

[Gavin D. Smith]

This is an automated email from the git hooks/post-receive script.

gavin pushed a commit to branch master
in repository texinfo.

The following commit(s) were added to refs/heads/master by this push:
     new 2d933b5258 Documentation of @dircategory
2d933b5258 is described below

commit 2d933b5258586cc43f164603c860ad7696f0545e
Author: Gavin Smith <gavinsmith0123@gmail.com>
AuthorDate: Mon Jan 10 19:51:03 2022 +0000

    Documentation of @dircategory
    
    * doc/texinfo.texi (Directory Category): New node, to document
    @dircategory independently of install-info and dir files.  Expand
    list of categories based on what is in util/dir-example.
    (Installing Dir Entries):  Move much material to new node.
    (Directory File): Move reference to util/dir-example file here.
---
 ChangeLog        | 10 +++++++
 doc/texinfo.texi | 82 +++++++++++++++++++++++++++++++++++++++-----------------
 2 files changed, 67 insertions(+), 25 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 38e8228ff7..e3fcde8259 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2022-01-10  Gavin Smith  <gavinsmith0123@gmail.com>
+
+       Documentation of @dircategory
+
+       * doc/texinfo.texi (Directory Category): New node, to document
+       @dircategory independently of install-info and dir files.  Expand
+       list of categories based on what is in util/dir-example.
+       (Installing Dir Entries):  Move much material to new node.
+       (Directory File): Move reference to util/dir-example file here.
+
 2022-01-10  Gavin Smith  <gavinsmith0123@gmail.com>
 
        *  util/htmlxref.cnf:
diff --git a/doc/texinfo.texi b/doc/texinfo.texi
index 7ef9aad4c7..6f81f25a4b 100644
--- a/doc/texinfo.texi
+++ b/doc/texinfo.texi
@@ -158,6 +158,7 @@ Writing a Texinfo File
 * Minimum::                     What a Texinfo file must have.
 * Short Sample Texinfo File::   A short sample Texinfo file.
 * Texinfo File Header::         The first lines.
+* Directory Category::          A category for a manual.
 * Document Permissions::        Ensuring your manual is free.
 * Titlepage & Copyright Page::  Creating the title and copyright pages.
 * Contents::                    How to create a table of contents.
@@ -1282,6 +1283,7 @@ file, and gives a short sample file.
 * Minimum::                     What a Texinfo file must have.
 * Short Sample Texinfo File::   A short sample Texinfo file.
 * Texinfo File Header::         The first lines.
+* Directory Category::          A category for a manual.
 * Document Permissions::        Ensuring your manual is free.
 * Titlepage & Copyright Page::  Creating the title and copyright pages.
 * Contents::                    How to create a table of contents.
@@ -1866,6 +1868,53 @@ Text ending the preamble
 @end example
 @end group
 
+
+@node Directory Category
+@section Directory Category
+
+@findex dircategory
+@cindex Free Software Directory
+@cindex Dir categories, choosing
+@cindex Categories, choosing
+Use the @code{@@dircategory} command to specify a category
+for the manual.  When choosing the name of the category, we
+recommend consulting the @uref{http://www.gnu.org/directory,
+Free Software Directory}.  If your program is not listed there,
+or listed incorrectly or incompletely, please report the situation to
+the directory maintainers (@url{http://directory.fsf.org}) so that the
+category names can be kept in sync.
+
+Here are a few examples of category names:
+@c from util/dir-example
+
+@display
+Basics
+Text creation and manipulation
+Archiving
+Compression
+Database
+Editors
+Emacs
+Email
+Graphics
+Localization
+Network applications
+Printing
+Science
+Software development
+Software libraries
+Version control
+@end display
+
+@code{@@dircategory} commands are usually followed by a
+@code{@@direntry} blocks, which are used by @command{install-info}.
+@xref{Installing Dir Entries}, for details.
+
+The first @code{@@dircategory} command in a manual is the category for
+the entire manual.  Subsequent uses of @code{@@dircategory} set the category
+for following @code{@@direntry} blocks only.
+
+
 @node Document Permissions
 @anchor{Software Copying Permissions}@c old node name
 @section Document Permissions
@@ -17554,6 +17603,10 @@ In this case, the @file{dir} file name is written in 
uppercase
 letters---it can be written in either upper- or lowercase.  This is not
 true in general, it is a special case for @file{dir}.
 
+See the @file{util/dir-example} file in the Texinfo distribution for
+a large sample @code{dir} file.
+
+
 
 @node New Info File
 @subsection Listing a New Info File
@@ -17686,15 +17739,16 @@ When you install an Info file onto your system, you 
can use the program
 Normally the makefile for the package runs @code{install-info}, just
 after copying the Info file into its proper installed location.
 
-@findex dircategory
+
 @findex direntry
 In order for the Info file to work with @code{install-info}, you include
 the commands @code{@@dircategory} and
 @code{@@direntry}@dots{}@code{@@end direntry} in the Texinfo source
 file.  Use @code{@@direntry} to specify the menu entries to add to the
 Info directory file, and use @code{@@dircategory} to specify which part
-of the Info directory to put it in.  Here is how these commands are used
-in this manual:
+of the Info directory to put it in.  @xref{Directory Category}.
+
+Here is how these commands are used in this manual:
 
 @example
 @@dircategory Texinfo documentation system
@@ -17739,28 +17793,6 @@ If you use @code{@@dircategory} more than once in the 
Texinfo source,
 each usage specifies the `current' category; any subsequent
 @code{@@direntry} commands will add to that category.
 
-@cindex Free Software Directory
-@cindex Dir categories, choosing
-@cindex Categories, choosing
-When choosing a category name for the @code{@@dircategory} command, we
-recommend consulting the @uref{http://www.gnu.org/directory,
-Free Software Directory}.  If your program is not listed there,
-or listed incorrectly or incompletely, please report the situation to
-the directory maintainers (@url{http://directory.fsf.org}) so that the
-category names can be kept in sync.
-
-Here are a few examples (see the @file{util/dir-example} file in the
-Texinfo distribution for large sample @code{dir} file):
-
-@display
-Emacs
-Localization
-Printing
-Software development
-Software libraries
-Text creation and manipulation
-@end display
-
 @cindex Invoking nodes, including in dir file
 Each `Invoking' node for every program installed should have a
 corresponding @code{@@direntry}.  This lets users easily find the