branch master updated: Update DTD to have headings in most environments

[Patrice Dumas]

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

pertusus pushed a commit to branch master
in repository texinfo.

The following commit(s) were added to refs/heads/master by this push:
     new 9699291d8a Update DTD to have headings in most environments
9699291d8a is described below

commit 9699291d8a014708cf8325d1f1b690c27f69f9c9
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Sun Aug 21 00:32:00 2022 +0200

    Update DTD to have headings in most environments
    
    * util/texinfo.dtd: put %heading.cmds in %block.
    Remove %global.option.cmds, put index definition commands in
    %multiple.option.cmds, and @-command definitions commands
    such as alias in the newly added %define.cmds.  Move macro, rmacro
    and unmacro to %define.cmds.
    Rename %titlepage.cmds as %intitlepage.cmds.
    Add %block.cmds containing the block commands.
    Add %toplevelonly.content for @-commands appearing only in
    toplevel content, move listoffloats, copying and titlepage to
    %toplevelonly.content.
    
    * doc/texinfo.texi (The Body of the Document): remove the comment
    about @*heading needing to appear in main text, as it is not what
    is documented.
    (@code{@@unnumberedsec @@appendixsec @@heading}): remove @titlepage
    from context where @heading is pathological, as it should not be
    particularly problematic.
    (@code{@@listoffloats}): move @listoffloats outside of @display
    as @listoffloats should only appear in the main text.
---
 ChangeLog        | 24 +++++++++++++++++
 doc/texinfo.texi | 12 +++------
 util/texinfo.dtd | 79 +++++++++++++++++++++++++++++++-------------------------
 3 files changed, 71 insertions(+), 44 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 29773c4ade..17f266539b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,27 @@
+2022-08-20  Patrice Dumas  <pertusus@free.fr>
+
+       Update DTD to have headings in most environments
+
+       * util/texinfo.dtd: put %heading.cmds in %block.
+       Remove %global.option.cmds, put index definition commands in
+       %multiple.option.cmds, and @-command definitions commands
+       such as alias in the newly added %define.cmds.  Move macro, rmacro
+       and unmacro to %define.cmds.
+       Rename %titlepage.cmds as %intitlepage.cmds.
+       Add %block.cmds containing the block commands.
+       Add %toplevelonly.content for @-commands appearing only in
+       toplevel content, move listoffloats, copying and titlepage to
+       %toplevelonly.content.
+
+       * doc/texinfo.texi (The Body of the Document): remove the comment
+       about @*heading needing to appear in main text, as it is not what
+       is documented.
+       (@code{@@unnumberedsec @@appendixsec @@heading}): remove @titlepage
+       from context where @heading is pathological, as it should not be
+       particularly problematic.
+       (@code{@@listoffloats}): move @listoffloats outside of @display
+       as @listoffloats should only appear in the main text.
+
 2022-08-20  Gavin Smith  <gavinsmith0123@gmail.com>
 
        Fix texinfo.tex for XeTeX
diff --git a/doc/texinfo.texi b/doc/texinfo.texi
index b96cf22d37..4eb9becce9 100644
--- a/doc/texinfo.texi
+++ b/doc/texinfo.texi
@@ -2737,11 +2737,6 @@ for the chapter.
 
 Here is what the contents of this chapter will look like:
 
-@c NOTE the following construct is not valid, @*heading commands
-@c should only appear in main text, not within a block @-command,
-@c here @quotation.  The Texinfo XML output is not valid, but other
-@c than that, the output is good, so it is not a real issue.
-
 @sp 1
 @need 700
 @quotation
@@ -4029,8 +4024,7 @@ You may use the @code{@@heading} command (almost) 
anywhere for a
 section-style heading that will not appear in the table of contents.
 The @code{@@heading}-series commands can appear inside most
 environments, for example, though pathological and useless locations
-such as inside @code{@@titlepage}, as an argument to another command,
-etc., are not allowed.
+such as an argument to another command, etc., are not allowed.
 
 @end table
 
@@ -8053,14 +8047,14 @@ Here's an example:
 looks like, given the example figure earlier in this chapter (the Info
 output is formatted as a menu):
 
-@display
 @ifinfo
+@display
 *      Figure 12.1:      fig:ex1.
+@end display
 @end ifinfo
 @ifnotinfo
 @listoffloats Figure
 @end ifnotinfo
-@end display
 
 Without any argument, @code{@@listoffloats} generates a list of floats
 for which no float type was specified, i.e., no first argument to the
diff --git a/util/texinfo.dtd b/util/texinfo.dtd
index 175cd7fde5..85f426d938 100644
--- a/util/texinfo.dtd
+++ b/util/texinfo.dtd
@@ -25,6 +25,9 @@
                             | shorttitlepage">
 <!ENTITY % variable.cmds "set | clear">
 
+<!-- @-commands definition commands -->
+<!ENTITY % define.cmds "definfoenclose | alias | macro | rmacro | unmacro">
+
 <!-- Unique options -->
 <!ENTITY % unique.option.cmds "novalidate | setcontentsaftertitlepage 
    | setshortcontentsaftertitlepage | documentencoding 
@@ -37,26 +40,22 @@
    | everyheading | everyfooting | evenheading | evenfooting | oddheading
    | oddfooting | smallbook | cropmarks">
 
-<!-- Global options in the main text -->
-<!ENTITY % global.option.cmds "synindex | syncodeindex
-  | defindex | defcodeindex | definfoenclose | alias">
-
 <!-- Options -->
 <!ENTITY % multiple.option.cmds "frenchspacing | documentlanguage 
     | %variable.cmds; | kbdinputstyle | paragraphindent 
     | firstparagraphindent | urefbreakstyle | xrefautomaticsectiontitle
     | deftypefnnewline
     | codequoteundirected | codequotebacktick | raisesections
-    | lowersections | clickstyle">
+    | lowersections | clickstyle
+    | synindex | syncodeindex | defindex | defcodeindex">
 
-<!ENTITY % option.cmds "%unique.option.cmds; | %global.option.cmds; 
-               | %multiple.option.cmds;">
+<!ENTITY % option.cmds "%unique.option.cmds; | %multiple.option.cmds;">
 
 <!-- ToC -->
 <!ENTITY % toc "contents | shortcontents | summarycontents">
 
-<!-- Title page -->
-<!ENTITY % titlepage.cmds "author | title | subtitle">
+<!-- In title page -->
+<!ENTITY % intitlepage.cmds "author | title | subtitle">
 
 <!-- index entry commands -->
 <!ENTITY % indexentry.cmds "cindex | findex | kindex | pindex | tindex
@@ -68,40 +67,42 @@
       | defspec | defvar | defopt | deftypefun | deftypevar 
       | defivar | deftypeivar | defmethod | deftypemethod">
 
-<!ENTITY % raw.cmds "html | tex | latex | docbook | xml | macro | rmacro | 
ignore">
+<!ENTITY % raw.cmds "html | tex | latex | docbook | xml | ignore">
 
 <!-- Commands that appear everywhere, both with block and in paragraphs -->
 <!-- include is in general absent, since it is replaced, but it is
      present if the file was not found -->
 <!ENTITY % ubiquitous.cmds "sp | anchor | indent | noindent | %raw.cmds; 
-                 | %option.cmds; | errormsg | unmacro | include
+                 | %define.cmds; | %option.cmds; | errormsg | include
                  | %indexentry.cmds; | refill | quote-arg | allow-recursion">
 
-<!-- Block -->
-<!ENTITY % block "menu | para | pre | quotation | smallquotation
+<!-- Block commands -->
+<!ENTITY % block.cmds "menu | para | pre | quotation | smallquotation
                   | indentedblock | smallindentedblock
                   | example | smallexample | lisp | smalllisp
                   | cartouche | float | format | smallformat
-                  | display | smalldisplay | copying | titlepage
+                  | display | smalldisplay
                   | raggedright | flushleft | flushright
-                  | itemize | enumerate | titlefont | center | group
+                  | itemize | enumerate | group
                   | table | vtable | ftable | multitable | displaymath
-                  | image
-                  | %def.cmds; 
+                  | %def.cmds; | verbatim">
+
+<!-- Headings -->
+<!ENTITY % heading.cmds "majorheading | chapheading | heading | subheading
+                     | subsubheading">
+
+<!-- Block content, as opposed to Inline content -->
+<!ENTITY % block  "%block.cmds; | verbatiminclude
+                  | %heading.cmds;
                   | %ubiquitous.cmds;
-                  | verbatim | verbatiminclude | insertcopying | page | need
-                  | vskip
-                  | listoffloats">
+                  | image | titlefont | center
+                  | insertcopying | page | need | vskip">
 
 <!-- API definition line -->
 <!ENTITY % definition.args "defcategory | deffunction | defvariable | defparam
                           | defdelimiter | deftype | defparamtype | defdatatype
                           | defclass | defclassvar | defoperation">
 
-<!-- Headings -->
-<!ENTITY % heading.cmds "majorheading | chapheading | heading | subheading
-                     | subsubheading">
-
 <!-- Language codes -->
 <!ENTITY % languagecodes 
"aa|ab|af|am|ar|as|ay|az|ba|be|bg|bh|bi|bn|bo|br|ca|co|cs|cy|da|de|dz|el|en|eo|es|et|eu|fa|fi|fj|fo|fr|fy|ga|gd|gl|gn|gu|ha|he|hi|hr|hu|hy|ia|id|ie|ik|is|it|iu|ja|jw|ka|kk|kl|km|kn|ko|ks|ku|ky|la|ln|lo|lt|lv|mg|mi|mk|ml|mn|mo|mr|ms|mt|my|na|ne|nl|no|oc|om|or|pa|pl|ps|pt|qu|rm|rn|ro|ru|rw|sa|sd|sg|sh|si|sk|sl|sm|sn|so|sq|sr|ss|st|su|sv|sw|ta|te|tg|th|ti|tk|tl|tn|to|tr|ts|tt|tw|ug|uk|ur|uz|vi|vo|wo|xh|yi|yo|za|zh|zu">
 
@@ -118,10 +119,11 @@
 <!ENTITY % section.all "%section.level1; | %section.level2; | %section.level3;
                         | %section.level4;">
 
+<!ENTITY % toplevelonly.content "%toc; | copying | titlepage
+                             | printindex | listoffloats">
 
 <!-- toplevel content, not in copying nor footnote -->
-<!ENTITY % main.content "%block; | %toc; | node | %heading.cmds; 
-                         | printindex">
+<!ENTITY % main.content "%block; | %toplevelonly.content; | node">
 
 <!ENTITY % section.level0.content "(%main.content;
                                    | %section.level1;
@@ -151,7 +153,7 @@
 <!ENTITY % Inline.footnote "footnote">
 <!ENTITY % Inline.markup "code | command | env | file | option | samp | verb
                           | dfn | cite | key | kbd | var | acronym | abbr
-                          | indicateurl | w | asis | sub | sup "> 
+                          | indicateurl | w | asis | sub | sup ">
 <!ENTITY % Inline.math "math | dmn">
 <!ENTITY % Inline.reference "xref | ref | pxref | inforef ">
 <!ENTITY % Inline.hyperreference "email | uref | url">
@@ -166,6 +168,14 @@
 <!ENTITY % Inline.linetext "%Inline.linesimpletext; | %Inline.reference;
                             | %Inline.footnote;">
 <!ENTITY % Inline.line "%Inline.linetext; | image">
+<!-- %Inline.line; appears on @vtable item, so it must be valid in
+     indexterm generated for such item.  In that context seealso,
+     seeentry and sortas are not valid.
+     In index commands (@cindex...) indexterm, however, footnotes and
+     cross-reference are not valid, so %Inline.linesimpletext;, for example,
+     would have been better than %Inline.line;.
+     It is not possible to have different contents in different contexts
+     in the DTD, so we use the contents for all the contexts -->
 <!ENTITY % Inline.indexentryline "%Inline.line; | seealso | seeentry | sortas">
 <!ENTITY % Inline.fullline "%Inline.line; | titlefont | anchor">
 
@@ -180,8 +190,8 @@
            "%Inline.line; | %ubiquitous.cmds;">
 
 <!-- in raw (everything except sectioning commands) -->
-<!ENTITY % Raw.content "#PCDATA | %titlepage.cmds; | %block; | %heading.cmds; 
-           | %Inline.linetext; | exdent | %toc; | printindex 
+<!ENTITY % Raw.content "#PCDATA | %intitlepage.cmds; | %block;
+           | %Inline.linetext; | exdent | %toplevelonly.content;
            | %metainformation;">
 
 <!-- arguments/attribute values. Many are missing -->
@@ -198,11 +208,10 @@
 <!ENTITY % bracketedattr
   "bracketed (%onoff;) #IMPLIED">
 <!-- block commands that have spaces also have endspaces -->
-<!-- this is also used for commands without arguments 
+<!-- this is also used for commands without arguments
      when they have a @comment on their line -->
-<!ENTITY % spacesblockattr 
-          "%spacesattr; 
-           endspaces CDATA #IMPLIED">
+<!ENTITY % spacesblockattr
+          "%spacesattr; endspaces CDATA #IMPLIED">
 
 <!-- ELEMENTS -->
 
@@ -433,12 +442,12 @@
           %lineattr;>
 
 <!-- Titlepage and copying -->
-<!ELEMENT copying    (%block; | %heading.cmds;)*>
+<!ELEMENT copying    (%block;)*>
 <!ATTLIST copying
           %spacesblockattr;>
 <!ELEMENT insertcopying EMPTY>
 
-<!ELEMENT titlepage  (%titlepage.cmds; | %block; | %heading.cmds;)*>
+<!ELEMENT titlepage  (%intitlepage.cmds; | %block;)*>
 <!ATTLIST titlepage
           %spacesblockattr;>
 <!ELEMENT author     (#PCDATA | %Inline.line;)*>