Subject: bug#72761: issues with Flymake online documentation

From: Eli Zaretskii <[email-masked]>
Date: Sun, 25 Aug 2024 15:48:15 +0300

> From: Lester Longley <[email-masked]>
> Date: Fri, 23 Aug 2024 03:40:13 -0400
> Cc: [email-masked]
> 
> 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>

Thanks, I've now fixed the relevant HTML page, and also modified the
script we use to produce HTML manuals to not perform this kind of
"editing" of HTML produced by makeinfo.