texinfo ChangeLog util/texi-elements-by-size do...

[Karl Berry]

CVSROOT:        /sources/texinfo
Module name:    texinfo
Changes by:     Karl Berry <karl>       12/04/17 18:23:25

Modified files:
        .              : ChangeLog 
        util           : texi-elements-by-size 
        doc            : info-stnd.texi texinfo.txi 

Log message:
        doc texi-elements-by-size (and texi2html) as examples

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1349&r2=1.1350
http://cvs.savannah.gnu.org/viewcvs/texinfo/util/texi-elements-by-size?cvsroot=texinfo&r1=1.2&r2=1.3
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/info-stnd.texi?cvsroot=texinfo&r1=1.36&r2=1.37
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.433&r2=1.434

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1349
retrieving revision 1.1350
diff -u -b -r1.1349 -r1.1350
--- ChangeLog   17 Apr 2012 00:39:34 -0000      1.1349
+++ ChangeLog   17 Apr 2012 18:23:24 -0000      1.1350
@@ -1,3 +1,10 @@
+2012-04-17  Karl Berry  <address@hidden>
+
+       * doc/texinfo.txi (Tips): mention texi-elements-by-size (for usage).
+       (Reference Implementation): likewise (for an example); also texi2html.
+       * util/texi-elements-by-size: allow invocation from anywhere.
+       { on same line as sub?
+
 2012-04-16  Karl Berry  <address@hidden>
 
        * util/texi-elements-by-size: renamed from

Index: util/texi-elements-by-size
===================================================================
RCS file: /sources/texinfo/texinfo/util/texi-elements-by-size,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- util/texi-elements-by-size  17 Apr 2012 00:39:34 -0000      1.2
+++ util/texi-elements-by-size  17 Apr 2012 18:23:24 -0000      1.3
@@ -26,15 +26,15 @@
 use Getopt::Long qw(GetOptions);
 Getopt::Long::Configure("gnu_getopt");
 
-BEGIN
-{
+BEGIN {
   # The purpose of these includes is to make it possible to run the
   # script from a Texinfo source checkout.  If that's not relevant,
   # probably best to simply assume all the needed packages are in the
   # Perl include path.
   #
-  my $txi_libdir = "../tp";
-  unshift @INC, ($txi_libdir);
+  (my $mydir = $0) =~ s,/[^/]*$,,;  # dir we are in
+  my $txi_libdir = "$mydir/../tp";  # find tp relative to $0
+  unshift (@INC, $txi_libdir);
   #
   my @txi_maint_dirs = qw(Text-Unidecode Unicode-EastAsianWidth libintl-perl);
   unshift (@INC, map { "$txi_libdir/maintain/lib/$_/lib" } @txi_maint_dirs );
@@ -46,8 +46,7 @@
 
 my $my_version = "0.1 (TP $Texinfo::Parser::VERSION)";
 
-my $real_command_name = $0;
-$real_command_name =~ s/.*\///;
+(my $real_command_name = $0) =~ s/.*\///;
 $real_command_name =~ s/\.pl$//;
 
 # determine the path separators
@@ -61,8 +60,7 @@
 my $no_warn = 0;
 
 # placeholder for future i18n.
-sub __($)
-{
+sub __($) {
   return $_[0];
 }
 
@@ -142,18 +140,18 @@
 
 my $input_file_name = shift @input_files;
 
-sub help()
-{
+sub help() {
   my $help =
     sprintf(__("Usage: %s [OPTION]... TEXINFO-FILE...\n"), $real_command_name)
    ."\n".
-    __("Dump out a list of elements sorted by the number of lines (or words) 
-they contain after removal of address@hidden")
+    __("Write to standard output a list of Texinfo elements (nodes or sections)
+sorted by the number of lines (or words) they contain,
+after translation to Info format.\n")
 ."\n";
 
   $help .= __("General Options:
   --count-words    count words instead of lines.
-  --force          keep on even if the Texinfo file parsing failed.
+  --force          keep going even if Texinfo file parsing fails.
   --help           display this help and exit.
   --no-warn        suppress warnings (but not errors).
   --use-sections   use sections as elements instead of nodes.
@@ -184,14 +182,12 @@
   
 }
 
-sub _exit($)
-{
+sub _exit($) {
   my $error_count = shift;
   exit (1) if ($error_count and !$force);
 }
 
-sub handle_errors($$)
-{
+sub handle_errors($$) {
   my $self = shift;
   my $error_count = shift;
   my ($errors, $new_error_count) = $self->errors();
@@ -238,4 +234,4 @@
 
 print STDOUT $formatted_result;
 
-1;
+exit (0);

Index: doc/info-stnd.texi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/info-stnd.texi,v
retrieving revision 1.36
retrieving revision 1.37
diff -u -b -r1.36 -r1.37
--- doc/info-stnd.texi  20 Jan 2012 18:00:59 -0000      1.36
+++ doc/info-stnd.texi  17 Apr 2012 18:23:25 -0000      1.37
@@ -1,5 +1,5 @@
 \input texinfo.tex    @c -*-texinfo-*-
address@hidden $Id: info-stnd.texi,v 1.36 2012/01/20 18:00:59 karl Exp $
address@hidden $Id: info-stnd.texi,v 1.37 2012/04/17 18:23:25 karl Exp $
 @c We must \input texinfo.tex instead of texinfo, otherwise make
 @c distcheck in the Texinfo distribution fails, because the texinfo Info
 @c file is made first, and texi2dvi must include . first in the path.
@@ -869,6 +869,7 @@
 @code{g(emacs)Buffers}
 @end example
 
address@hidden
 finds the node @samp{Buffers} in the Info file @file{emacs}.
 
 @anchor{goto-invocation}

Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.433
retrieving revision 1.434
diff -u -b -r1.433 -r1.434
--- doc/texinfo.txi     14 Apr 2012 00:21:06 -0000      1.433
+++ doc/texinfo.txi     17 Apr 2012 18:23:25 -0000      1.434
@@ -1,5 +1,5 @@
 \input texinfo.tex    @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.433 2012/04/14 00:21:06 karl Exp $
address@hidden $Id: texinfo.txi,v 1.434 2012/04/17 18:23:25 karl Exp $
 @c Ordinarily, Texinfo files have the extension .texi.  But texinfo.texi
 @c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi.
 
@@ -1753,13 +1753,15 @@
 patches and suggestions, they are gratefully acknowledged in the
 @file{ChangeLog} file.  Our mistakes are our own.
 
address@hidden Scribe
address@hidden Reid, Brian
 @cindex History of Texinfo
 @cindex Texinfo history
-A bit of history: in the 1970's at CMU, Brian Reid developed a program
-and format named Scribe to mark up documents for printing.  It used the
address@hidden@@} character to introduce commands, as Texinfo does.  Much more
address@hidden Beginnings
+
address@hidden Scribe
address@hidden Reid, Brian
+In the 1970's at CMU, Brian Reid developed a program and format named
+Scribe to mark up documents for printing.  It used the @code{@@}
+character to introduce commands, as Texinfo does.  Much more
 consequentially, it strove to describe document contents rather than
 formatting, an idea wholeheartedly adopted by Texinfo.
 
@@ -1783,6 +1785,8 @@
 Brian Fox reimplemented the conversion program in C, now called
 @command{makeinfo}.
 
address@hidden Reimplementing in Perl
+
 @cindex Cons, Lionel
 @cindex Dumas, Patrice
 In 2012, the C @command{makeinfo} was itself replaced by a Perl
@@ -5230,8 +5234,8 @@
 
 @item
 By convention, node names are capitalized just as they would be for
-section or chapter titles---initial and significant words are
-capitalized; others are not.
+section or chapter titles.  In this manual, initial and significant
+words are capitalized; others are not.
 @end itemize
 
 
@@ -6776,11 +6780,12 @@
 which control the text that is displayed.  In HTML output, @code{@@uref}
 produces a link you can follow.
 
address@hidden@@url} is a synonym for @code{@@uref}.  Originally, @code{@@url}
address@hidden
address@hidden@@url} is a synonym for @code{@@uref}.  (Originally, @code{@@url}
 had the meaning of @code{@@indicateurl}
 (@pxref{indicateurl,,@code{@@indicateurl}}), but in actual practice it
 was misused the vast majority of the time.  So we've changed the
-meaning.
+meaning.)
 
 The second argument, if specified, is the text to display (the default
 is the url itself); in Info and DVI output, but not in HTML output, the
@@ -6793,6 +6798,7 @@
 third argument is given, the second argument is ignored.
 
 @cindex Line breaking, and urls
address@hidden Breakpoints within urls
 @TeX{} allows line breaking within urls at only a few characters
 (which are special in urls): @samp{&}, @samp{.}, @samp{#}, @samp{?},
 and @samp{/} (but not between @samp{/} characters).  A tiny amount of
@@ -16579,6 +16585,17 @@
 @command{texi2any}; we plead with anyone thinking of writing a program
 to parse Texinfo input to at least make use of these tests.  
 
address@hidden Examples of using @command{texi2any}
address@hidden Texinfo::Parser module
+The @command{texi2html} wrapper script (@pxref{texi2html}) provides a
+simple example of calling @command{texi2any} from a shell script; it's
+in @file{util/texi2html} in the Texinfo sources.  More
+consequentially, @command{texi-elements-by-size} is an example Perl
+script using the @code{Texinfo::Parser} module interface; it's in
address@hidden/texi-elements-by-size}.  (Its functionality may also be
+useful to authors; @pxref{texi-elements-by-size}.)
+
address@hidden Future of Texinfo implementations
 With the release of @command{texi2any} as the reference
 implementation, development of both the C implementation of
 @command{makeinfo} and @command{texi2html} has been halted.  Going
@@ -17819,8 +17836,8 @@
 
 @itemize @bullet
 @item Most blatantly, the command line options of @command{texi2html}
-are mostly now configuration variables.  A table of approximate
-equivalents is given below.
+are now configuration variables, for the most part.  A table of
+approximate equivalents is given below.
 
 @item The program-level customization API is very different in
 @command{texi2any}.
@@ -21354,7 +21371,7 @@
 @node Tips
 @appendix Tips and Hints
 
-Here are some tips for writing Texinfo documentation:@refill
+Here are some tips for writing Texinfo documentation:
 
 @cindex Tips
 @cindex Usage tips
@@ -21374,6 +21391,7 @@
 Include a copyright notice and copying permissions.
 @end itemize
 
+
 @subsubheading Index, Index, Index!
 
 Write many index entries, in different ways.
@@ -21385,7 +21403,7 @@
 way, an index entry points to the first page of a paragraph that is
 split across pages.
 
-Here are more hints we have found valuable:
+Here are more index-related hints we have found valuable:
 
 @itemize @bullet
 @item
@@ -21439,6 +21457,7 @@
 readers can look up the concept in different ways.)
 @end itemize
 
+
 @subsubheading Blank Lines
 
 @itemize @bullet
@@ -21446,13 +21465,12 @@
 Insert a blank line between a sectioning command and the first following
 sentence or paragraph, or between the indexing commands associated with
 the sectioning command and the first following sentence or paragraph, as
-shown in the tip on indexing.  Otherwise, a formatter may fold title and
-paragraph together.
+shown in the tip on indexing.  It makes the source easier to read.
 
 @item
 Always insert a blank line before an @code{@@table} command and after an
 @code{@@end table} command; but never insert a blank line after an
address@hidden@@table} command or before an @code{@@end table} command.
address@hidden@@table} command.
 
 @need 1000
 For example,
@@ -21483,6 +21501,7 @@
 same way.
 @end itemize
 
+
 @subsubheading Complete Phrases
 
 Complete phrases are easier to read than @dots{}
@@ -21499,6 +21518,7 @@
 ``You can set these variables:''.  The former expression sounds cut off.
 @end itemize
 
+
 @subsubheading Editions, Dates and Versions
 
 Include edition numbers, version numbers, and dates in the
@@ -21516,7 +21536,7 @@
 
 Definition commands are @code{@@deffn}, @code{@@defun},
 @code{@@defmac}, and the like, and enable you to write descriptions in
-a uniform address@hidden
+a uniform format.
 
 @itemize @bullet
 @item
@@ -21530,6 +21550,7 @@
 commands.
 @end itemize
 
+
 @subsubheading Capitalization
 
 @itemize @bullet
@@ -21544,9 +21565,10 @@
 Write @TeX{} using the @code{@@address@hidden@}} command.  Note the uppercase
 @samp{T} and @samp{X}.  This command causes the formatters to
 typeset the name according to the wishes of Donald Knuth, who wrote
address@hidden
address@hidden  (Likewise @code{@@address@hidden@}} for @LaTeX{}.)
 @end itemize
 
+
 @subsubheading Spaces
 
 Do not use spaces to format a Texinfo file, except inside of
@@ -21615,11 +21637,12 @@
 hyphens to two.
 @end itemize
 
+
 @subsubheading Periods Outside of Quotes
 
 Place periods and other punctuation marks @emph{outside} of quotations,
 unless the punctuation is part of the quotation.  This practice goes
-against publishing conventions in the United States, but enables the
+against some publishing conventions in the United States, but enables the
 reader to distinguish between the contents of the quotation and the
 whole passage.
 
@@ -21634,6 +21657,7 @@
 since @samp{au} does @emph{not} serve as an  abbreviation for
 @samp{author.} (with a period following the word).
 
+
 @subsubheading Introducing New Terms
 
 @itemize @bullet
@@ -21657,24 +21681,8 @@
 should expect to learn the meaning from this passage.
 @end itemize
 
address@hidden @@pxref
 
address@hidden !!! maybe include this in the tips on pxref
address@hidden
-By the way, it is okay to use pxref with something else in front of
-it within the parens, as long as the pxref is followed by the close
-paren, and the material inside the parens is not part of a larger
-sentence.  Also, you can use xref inside parens as part of a complete
-sentence so long as you terminate the cross reference with punctuation.
address@hidden ignore
-Absolutely never use @code{@@pxref} except in the special context for
-which it is designed: inside parentheses, with the closing parenthesis
-following immediately after the closing brace.  One formatter
-automatically inserts closing punctuation and the other does not.  This
-means that the output looks right both in printed output and in an Info
-file, but only when the command is used inside parentheses.
-
address@hidden Invoking from a Shell
address@hidden Program Invocation Nodes
 
 You can invoke programs such as Emacs, GCC, and @code{gawk} from a
 shell.  The documentation for each program should contain a section that
@@ -21689,7 +21697,7 @@
 @subsubheading ANSI C Syntax
 
 When you use @code{@@example} to describe a C function's calling
-conventions, use the ANSI C syntax, like this:@refill
+conventions, use the ANSI C syntax, like this:
 
 @example
 void dld_init (char *@@address@hidden@});
@@ -21698,16 +21706,16 @@
 @noindent
 And in the subsequent discussion, refer to the argument values by
 writing the same argument names, again highlighted with
address@hidden@@address@hidden
address@hidden@@var}.
 
 @need 800
-Avoid the obsolete style that looks like this:@refill
+Avoid the obsolete style that looks like this:
 
 @example
 #include <dld.h>
 
 dld_init (path)
-char *path;
+  char *path;
 @end example
 
 Also, it is best to avoid writing @code{#include} above the
@@ -21716,7 +21724,23 @@
 @code{#include} belongs near the declaration of the function.  Either
 state explicitly which header file holds the declaration or, better
 yet, name the header file used for a group of functions at the
-beginning of the section that describes the address@hidden
+beginning of the section that describes the functions.
+
address@hidden
address@hidden Node Length
+
+Keep nodes (sections) to a reasonable length, whatever reasonable
+might be in the given context.  Don't hesitate break up long nodes
+into subnodes and have an extensive tree structure; that's what it's
+there for.  Many times, readers will probably try to find a single
+specific point in the manual, using search, indexing, or just plain
+guessing, rather than reading the whole thing from beginning to end.
+
+You can use the @command{texi-elements-by-size} utility to see a list
+of all nodes (or sections) in the document, sorted by size (either
+lines or words), to find candidates for splitting.  It's in the
address@hidden/} subdirectory of the Texinfo sources.
+
 
 @subsubheading Bad Examples
 
@@ -21746,6 +21770,7 @@
 everyone's changes so they do not step on each other.
 @end quotation
 
+
 @subsubheading And Finally @dots{}
 
 @itemize @bullet
@@ -21892,7 +21917,7 @@
 Revision Control System}) or other version control systems, which
 expand it into a string such as:
 @example
-$Id: texinfo.txi,v 1.433 2012/04/14 00:21:06 karl Exp $
+$Id: texinfo.txi,v 1.434 2012/04/17 18:23:25 karl Exp $
 @end example
 (This is useful in all sources that use version control, not just manuals.)
 You may wish to include the @samp{$Id:} comment in the @code{@@copying}
@@ -22169,12 +22194,12 @@
 on both sides of the paper.
 
 By default, nothing is specified for the footing of a Texinfo file,
-so the footing remains address@hidden
+so the footing remains blank.
 
 The standard format for single-sided printing consists of a header
 line in which the left-hand part contains the name of the chapter, the
 central part is blank, and the right-hand part contains the page
address@hidden
+number.
 
 @need 950
 A single-sided page looks like this: