[6252] small doc/todo updates

[karl]

Revision: 6252
          http://svn.sv.gnu.org/viewvc/?view=rev&root=texinfo&revision=6252
Author:   karl
Date:     2015-05-06 17:37:57 +0000 (Wed, 06 May 2015)
Log Message:
-----------
small doc/todo updates

Modified Paths:
--------------
    trunk/ChangeLog
    trunk/README
    trunk/TODO
    trunk/doc/Makefile.am
    trunk/doc/texinfo.texi
    trunk/doc/version.texi
    trunk/texi2html/README.dev
    trunk/tp/README
    trunk/tp/TODO

Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog     2015-05-06 00:39:09 UTC (rev 6251)
+++ trunk/ChangeLog     2015-05-06 17:37:57 UTC (rev 6252)
@@ -1,3 +1,8 @@
+2015-05-06  Karl Berry  <address@hidden>
+
+       * doc/texinfo.texi (key): not using @key in indexes is an rms
+       edict (from many years ago, maybe he would revisit if any need).
+
 2015-05-06  Gavin Smith  <address@hidden>
 
        * tp/Texinfo/Parser.pm (parse_texi): Only use regex to look for

Modified: trunk/README
===================================================================
--- trunk/README        2015-05-06 00:39:09 UTC (rev 6251)
+++ trunk/README        2015-05-06 17:37:57 UTC (rev 6252)
@@ -36,9 +36,9 @@
 - then, for HTML, run: make -C doc html
   and you can start reading at doc/texinfo.html/index.html.
 - for PDF, if you have a working TeX, run: make -C doc pdf
-- for Info, you can read about the Info reader itself with:
+- for Info, you can read a tutorial on reading Info files:
  ./info/ginfo doc/info
-  and then read the Texinfo manual:
+  and/or read the Texinfo manual:
  ./info/ginfo doc/texinfo
 
 Texinfo mailing lists and archives:
@@ -51,11 +51,11 @@
 Bug reports:
 Please include enough information for the maintainers to reproduce the
 problem.  Generally speaking, that means:
-- the contents of all input files necessary to reproduce the bug (crucial!).
+- the contents of all input files needed to reproduce the bug (crucial!).
 - a statement of the problem and any samples of the erroneous output.
 - the version number of Texinfo and the program(s) involved (use --version).
 - hardware and operating system information (uname -a).
-- unusual options you gave to configure, if any (see config.status).
+- unusual options you gave to configure, if any (try ./config.status --help).
 - anything else that you think could be helpful.
 
 Patches are most welcome; if possible, please make them with diff -c and
@@ -107,7 +107,6 @@
                            sorted indices used by TeX when
                            typesetting a file for printing.
 
-
 Translation support:
   po/                      Strings of the programs.
   po_document/             Strings in generated Texinfo documents.
@@ -121,6 +120,9 @@
                              created by Autoconf.
   build-aux/               Common files.
 
+The util/ directory contains a few other scripts, e.g., examples of
+using makeinfo in various ways.  See util/README.
+
 Finally, the contrib/ directory contains additional files from users
 provided for your reading and/or hacking pleasure.  They aren't part of
 Texinfo proper or maintained by the Texinfo developers.

Modified: trunk/TODO
===================================================================
--- trunk/TODO  2015-05-06 00:39:09 UTC (rev 6251)
+++ trunk/TODO  2015-05-06 17:37:57 UTC (rev 6252)
@@ -11,38 +11,6 @@
   are permitted in any medium without royalty provided the copyright
   notice and this notice are preserved.
 
-* General:
-  - Monitor and improve the dir categories in existing manuals,
-    following the Free Software Directory categories.  Much mail to
-    developers has already been sent, what's needed now is to check new
-    releases and make sure they are using the right categories.
-    See the util/dir-example in the Texinfo distribution for our current
-    recommended categories.
-    For background, see the thread (which discusses a lot of other
-    issues too) at
-    http://lists.gnu.org/archive/html/emacs-devel/2002-10/msg00011.html
-    especially 
-      http://lists.gnu.org/archive/html/emacs-devel/2002-10/msg00090.html
-      http://lists.gnu.org/archive/html/emacs-devel/2002-10/msg00137.html
-  - Support installation of manuals in different languages, along these lines:
-    . support a LINGUAS file or variable saying which subdirs LL in the
-      source to descend into (under doc/).
-    . within each subdir LL, install the info files into $infodir/LL,
-      and run install-info on $infodir/LL/dir.
-    . info (both emacs and standalone) should read $infodir/$LANG/dir
-      as the first dir file, and likewise read info files first from
-      $infodir/$LANG, before falling back to $infodir.
-    . consider ways to avoid installing images in both places.
-      In fact, images probably need to be installed in a subdir
-      $infodir/MANUAL/ in the first place, to avoid conflicts of having
-      the same image name in different manuals.
-    For a test case, see texinfo cvs, with its one translated manual
-    (info-fr.texi).
-    From Wojciech Polak.
-  - Or even multibyte languages like Japanese, see msg:
-    http://lists.gnu.org/archive/html/bug-texinfo/2005-03/msg00000.html
-  - Support general reference card creation.
-
 * Language:
   - Remove the need for @if[not]tex at the beginning of the document.
   - Allow : in node names for info files, for names such as
@@ -89,10 +57,10 @@
   - Support the MediaWiki output format.
 
 * TeX:
-  - Use @ as the escape character, and Texinfo syntax generally, in the
-    table of contents and index files.
-  - Support input in any encoding and language, via ec or Latin Modern fonts.
-    Including Unicode, e.g., UTF-8.  (Some work has been done.)
+  - Index above @item allows page break.
+  - Table of contents is misaligned if there are 10 or more [sub]sections.
+  - @float captions should be typeset in a smaller font?
+  - Reset the scriptfonts and scriptscriptfonts when font size changes.
   - Reasonable way to change fonts from the default (some work has been
     done), to allow for PostScript fonts, for example.
   - @multitable: handle @hsep and @vsep.
@@ -100,8 +68,7 @@
   - @multitable: support a heading line concept (<thead> in HTML).
   - Introduce new command to change \bindingoffset.
   - Use marks to define a real @thissection.
-  - Table of contents is misaligned if there are 10 or more [sub]sections.
-  - Make accent commands implicitly use @dotless{i/j}.
+  - Include synctex support.
   - Include hyperlink \special's in the DVI output for xdvi, etc.
   - PDF: make each letter of the index (A, B, ...) a section in the TOC.
     From Carsten Dominik.
@@ -109,21 +76,14 @@
     pages, presumably after xpdf/gv support it.  Section 8.3.1 of the
     PDF reference.  From Werner Lemberg, texinfo-pretest mail of
     27 Feb 2006 22:55:13 +0100.
+  - Use @ as the escape character in index files by default,
+    after new texindex is deployed (2020?).
 
 * Doc:
-  - Improve the manuals.
-  - location of text before the information required to understand them:
-    * 2 Using Texinfo Mode: before the Texinfo language description
-    * 4.1 Printing Indices and Menus: before @node, @unnumbered and indices
-  - The Cross References node is very long and maybe should
-    start with the most general uses and proceed to special cases.
-  - Strange sentence in @node key:
-     As a convention in GNU manuals, @code{@@key} should not be used in
-     index entries.
-  - new section on doing dedication pages. See gawk.texi
+  - New section on doing dedication pages. See gawk.texi
     for an example of doing it in both the tex and info versions.
-  - use/distribute pod2texi generated documentation of the perl modules in 
-    tp generated in doc/tp_api.
+  - Use/distribute pod2texi generated documentation of the perl modules in 
+    tp generated in doc/tp_api -- when api is stable.
   - Documentation of the HTML customization is missing.
 
 * Info:
@@ -161,6 +121,18 @@
     @image (or other) files.  In subdirs.  Or something.
   - support info dir entries for other than the current info file name;
     see comments in menu_item_equal.
+  - Monitor and improve the dir categories in existing manuals,
+    following the Free Software Directory categories.  Much mail to
+    developers has already been sent, what's needed now is to check new
+    releases and make sure they are using the right categories.
+    See the util/dir-example in the Texinfo distribution for our current
+    recommended categories.
+    For background, see the thread (which discusses a lot of other
+    issues too) at
+    http://lists.gnu.org/archive/html/emacs-devel/2002-10/msg00011.html
+    especially 
+      http://lists.gnu.org/archive/html/emacs-devel/2002-10/msg00090.html
+      http://lists.gnu.org/archive/html/emacs-devel/2002-10/msg00137.html
 
 * texindex:
   - read source file (specified by new option) for @documentlanguage
@@ -171,7 +143,30 @@
   - generate txi-??.tex from .po's to make translators' jobs easier.
     From Akim and Karl E.
 
-Ideas that will not be implemented:
+* Ideas that will not be implemented:
+- Support general reference card creation.
+  [Reference cards are too different from normal Texinfo.]
+
+- Support installation of manuals in different languages, along these lines:
+  . support a LINGUAS file or variable saying which subdirs LL in the
+    source to descend into (under doc/).
+  . within each subdir LL, install the info files into $infodir/LL,
+    and run install-info on $infodir/LL/dir.
+  . info (both emacs and standalone) should read $infodir/$LANG/dir
+    as the first dir file, and likewise read info files first from
+    $infodir/$LANG, before falling back to $infodir.
+  . consider ways to avoid installing images in both places.
+    In fact, images probably need to be installed in a subdir
+    $infodir/MANUAL/ in the first place, to avoid conflicts of having
+    the same image name in different manuals.
+  For a test case, see texinfo cvs, with its one translated manual
+  (info-fr.texi).
+  From Wojciech Polak.
+  ... Except, in practice, people just name their manuals with a
+  suffix for the language, and that seems to work well enough.  There
+  aren't that many manuals even in English, let alone other languages,
+  and there are almost no manuals in multiple languages.
+
 - Process Texinfo files directly instead of converting to Info:
   ftp://ftp.cs.berkeley.edu/ucb/people/phelps/tcltk/tkman.tar.Z, which
   uses Tcl/Tk 8.0 from ftp.smli.com in the /pub/tcl directory.

Modified: trunk/doc/Makefile.am
===================================================================
--- trunk/doc/Makefile.am       2015-05-06 00:39:09 UTC (rev 6251)
+++ trunk/doc/Makefile.am       2015-05-06 17:37:57 UTC (rev 6252)
@@ -87,6 +87,8 @@
 gendocs_dir_url = /manual/
 gendocs_invoke = env $(gendocs_envvars) $(gendocs) --email $(gendocs_email) \
   --html '-c TOP_NODE_UP_URL=$(gendocs_dir_url)'
+# A nice side effect of using --html is to eliminate the fancy css default;
+# otherwise, we could use gendocs_template_min.
 #
 manual1 = info
 manual1_title = "GNU Info manual"

Modified: trunk/doc/texinfo.texi
===================================================================
--- trunk/doc/texinfo.texi      2015-05-06 00:39:09 UTC (rev 6251)
+++ trunk/doc/texinfo.texi      2015-05-06 17:37:57 UTC (rev 6252)
@@ -7550,6 +7550,7 @@
 example, write @samp{@@address@hidden@}} to produce @kbd{Meta-a} and
 @samp{@@address@hidden@}} to produce @key{META}.
 
address@hidden per rms.
 As a convention in GNU manuals, @code{@@key} should not be used in
 index entries.
 

Modified: trunk/doc/version.texi
===================================================================
--- trunk/doc/version.texi      2015-05-06 00:39:09 UTC (rev 6251)
+++ trunk/doc/version.texi      2015-05-06 17:37:57 UTC (rev 6252)
@@ -1,4 +1,4 @@
address@hidden UPDATED 3 May 2015
address@hidden UPDATED 6 May 2015
 @set UPDATED-MONTH May 2015
 @set EDITION 5.9.91
 @set VERSION 5.9.91

Modified: trunk/texi2html/README.dev
===================================================================
--- trunk/texi2html/README.dev  2015-05-06 00:39:09 UTC (rev 6251)
+++ trunk/texi2html/README.dev  2015-05-06 17:37:57 UTC (rev 6252)
@@ -1,12 +1,12 @@
 This README.dev file gives some information about developing texi2html.
 
-  Copyright 2010 Free Software Foundation, Inc.
+  Copyright 2010, 2015 Free Software Foundation, Inc.
 
   Copying and distribution of this file, with or without modification,
   are permitted in any medium without royalty provided the copyright
   notice and this notice are preserved.
 
-[xxx work in progress xxx]
+[incomplete]
 
 Customizing texi2html
 =====================

Modified: trunk/tp/README
===================================================================
--- trunk/tp/README     2015-05-06 00:39:09 UTC (rev 6251)
+++ trunk/tp/README     2015-05-06 17:37:57 UTC (rev 6252)
@@ -44,3 +44,11 @@
 describes the existing backends and other places to look.  To do a good
 job, expect to spend a lot of time making it do the right thing with the
 existing tests.
+
+tp builds a complicated parse tree.  It can output a lot of debug
+information about the tree, and what it's doing generally.  For example,
+these commands output the tree (in different forms):
+  makeinfo -c DUMP_TREE=1 -c TEXINFO_OUTPUT_FORMAT=parse document.texi
+  makeinfo -c TEXINFO_OUTPUT_FORMAT=debugtree document.texi
+In addition (or instead) setting the DEBUG configuration variable will
+dump more information about what it's doing.

Modified: trunk/tp/TODO
===================================================================
--- trunk/tp/TODO       2015-05-06 00:39:09 UTC (rev 6251)
+++ trunk/tp/TODO       2015-05-06 17:37:57 UTC (rev 6252)
@@ -1,6 +1,6 @@
 This is the todo list for the Texinfo::Parser implementation.
 
-  Copyright 2012, 2013 Free Software Foundation.
+  Copyright 2012, 2013, 2014, 2015 Free Software Foundation.
 
   Copying and distribution of this file, with or without modification,
   are permitted in any medium without royalty provided the copyright
@@ -413,4 +413,3 @@
 
 t/info_tests.t
  space_in_setfilename
-