bug#72761: issues with Flymake online documentation

[Lester Longley via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

[-- Attachment #1: Type: text/plain, Size: 7706 bytes --]

Good morning.

The following difference seems like it could be relevant.

As an aside, I have found it more informative to download the .html files
and manually inspect them, rather than to look at Chrome's Elements tree,
since that itself seems to get confused by what appears to me to be a list
started w/ <table> but ended w/ </ul>.

In summary, I think that the translation of the @multitable is itself fine,
but that the prior presence of @itemize @bullet ... , with its mismatch
<table> ... </ul>, confuses Chrome. and causes it to (not) render the table
(from @multitable) properly.

----------------------------------------------------------------------------------------

(a) in the (shorter)
https://www.gnu.org/software/emacs/manual/html_node/flymake/Starting-Flymake.html
:
<ul> starts, and </ul> closes, the list, and this documentation "node"
renders fine.

      <p>Syntax checks happen &ldquo;on-the-fly&rdquo;.  Each check is
started whenever:
      </p>

OK:   <ul class="itemize mark-bullet">
        <li><code class="code">flymake-mode</code> is started, unless
          <code class="code">flymake-start-on-flymake-mode</code> is <code
class="code">nil</code>;

        </li><li>the buffer is saved, unless <code
class="code">flymake-start-on-save-buffer</code> is
               <code class="code">nil</code>;

             </li><li>some changes were made to the buffer more than <code
class="code">0.5</code> seconds ago

                       (the delay is configurable in <code
class="code">flymake-no-changes-timeout</code>).

                  </li><li>When the user invokes the command <code
class="code">flymake-start</code>.
OK:                    </li></ul>

----------------------------------------------------------------------------------------

(b) however, in the (longer & problematic) (mono)
https://www.gnu.org/software/emacs/manual/html_mono/flymake.html

          <p>Syntax checks happen &ldquo;on-the-fly&rdquo;.  Each check is
started whenever:
          </p>
BAD:       <table style="float:left" width="100%">
            <li> <code>flymake-mode</code> is started, unless
              <code>flymake-start-on-flymake-mode</code> is
<code>nil</code>;

            </li><li> the buffer is saved, unless
<code>flymake-start-on-save-buffer</code> is
                   <code>nil</code>;

                 </li><li> some changes were made to the buffer more than
<code>0.5</code> seconds ago

               (the delay is configurable in
<code>flymake-no-changes-timeout</code>).

                      </li><li> When the user invokes the command
<code>flymake-start</code>.
 OK:                       </li></ul>
----------------------------------------------------------------------------------------

I *guess* that this latter "unclosed" <table> is what causes trouble
further down in this file, even though (a new,  matching) <table> &
</table> match up there.
(I haven't yet figured out how to rebuild the manuals to do more direct
experiments/isolation.)
----------------------------------------------------------------------------------------

          <p>The following statuses are defined:
          </p>
OK:          <table>
            <tr><td width="25%">[<var>nerrors</var> <var>nwarnings</var>
...]</td><td width="75%">Normal operation. <var>nerrors</var> and
<var>nwarnings</var> are, respectively,


        the total number of errors and warnings found during the last buffer


        check, for all backends. They may be followed by other totals for


        other types of diagnostics (see <a
href="#Flymake-error-types">Customizing Flymake error types</a>).</td></tr>
            <tr><td width="25%"><code>Wait</code></td><td width="75%">Some
Flymake backends haven&rsquo;t reported since the last time they

                            where questioned.  It is reasonable to assume
that this is a temporary

                            delay and Flymake will resume normal operation
soon.</td></tr>
            <tr><td width="25%"><code>!</code></td><td width="75%">All the
configured Flymake backends have disabled themselves: Flymake
                                                                   cannot
annotate the buffer and action from the user is needed to

 investigate and remedy the situation (see <a
href="#Troubleshooting">Troubleshooting</a>).</td></tr>
            <tr><td width="25%"><code>?</code></td><td width="75%">There
are no applicable Flymake backends for this buffer, thus Flymake
                                                                   cannot
annotate it.  To fix this, a user may look to extending Flymake
                                                                   and add
a new backend (see <a href="#Extending-Flymake">Extending
Flymake</a>).</td></tr>
 OK:         </table>

----------------------------------------------------------------------------------------

-Lester

On Fri, Aug 23, 2024 at 3:06 AM Eli Zaretskii <eliz@gnu.org> wrote:

> > From: Lester Longley <lester@ieee.org>
> > Date: Thu, 22 Aug 2024 17:01:37 -0400
> > Cc: 72761@debbugs.gnu.org
> >
> > Re: the second issue, the problem seems to start here, with this: <table
> style="float:left" width="100%">
> > element (see PROBLEM below), which
> > (a) seems out of place
> > (b) is never closed w/ "</table>, as best I can see (as per inspection
> of saved output from curl
> > "https://www.gnu.org/software/emacs/manual/html_mono/flymake.html")
> > Instead, this "<table>" seems to be closed with a mismatched "</ul>"
>
> No, there _is_ a </table>, see below, where I copied the "page source"
> from my browser.
>
> > I am unfamiliar w/ Texinfo, but I nonetheless don't see any "obvious"
> reason that a <table> element should be
> > emitted at the above location, based on the below excerpt from
> >
> https://git.savannah.gnu.org/cgit/emacs.git/tree/doc/misc/flymake.texi?h=emacs-29#n115
> (I'm just guessing on
> > the corresponding version of this file currently used for the online
> documentation)
>
> No, that table is the translation of @multitable.
>
>   <p>The following statuses are defined:
>   </p>
>   <table>
>   <tr><td width="25%">[<var>nerrors</var> <var>nwarnings</var>
> ...]</td><td width="75%">Normal operation. <var>nerrors</var> and
> <var>nwarnings</var> are, respectively,
>   the total number of errors and warnings found during the last buffer
>   check, for all backends. They may be followed by other totals for
>   other types of diagnostics (see <a
> href="#Flymake-error-types">Customizing Flymake error types</a>).</td></tr>
>   <tr><td width="25%"><code>Wait</code></td><td width="75%">Some Flymake
> backends haven&rsquo;t reported since the last time they
>   where questioned.  It is reasonable to assume that this is a temporary
>   delay and Flymake will resume normal operation soon.</td></tr>
>   <tr><td width="25%"><code>!</code></td><td width="75%">All the
> configured Flymake backends have disabled themselves: Flymake
>   cannot annotate the buffer and action from the user is needed to
>   investigate and remedy the situation (see <a
> href="#Troubleshooting">Troubleshooting</a>).</td></tr>
>   <tr><td width="25%"><code>?</code></td><td width="75%">There are no
> applicable Flymake backends for this buffer, thus Flymake
>   cannot annotate it.  To fix this, a user may look to extending Flymake
>   and add a new backend (see <a href="#Extending-Flymake">Extending
> Flymake</a>).</td></tr>
>   </table>
>
> I guess I will ask the Texinfo developers to take a look.
>
> Thanks.
>

[-- Attachment #2: Type: text/html, Size: 12179 bytes --]