Skip to content

[ASL Reference] fixed HTML (hevea-related) warnings#1900

Open
Roman-Manevich wants to merge 2 commits into
masterfrom
aslref-hevea-warnings
Open

[ASL Reference] fixed HTML (hevea-related) warnings#1900
Roman-Manevich wants to merge 2 commits into
masterfrom
aslref-hevea-warnings

Conversation

@Roman-Manevich

@Roman-Manevich Roman-Manevich commented Jul 7, 2026

Copy link
Copy Markdown
Collaborator

This PR is AI-assisted.

  • the Makefile now catches HeVeA and hacha warnings and then fails the build.

ASL Reference HTML Warning Cleanup

  • First-pass undefined labels, citations, and fixpoint warnings.
    Example warning: ./introduction.tex:140: Warning: Undefined label: 'chap:Specifications'.
    Cause: the first hevea -fix0 pass runs before bibhva and before HeVeA
    has enough information to reach a cross-reference fixpoint. Undefined labels,
    undefined citations, and rerun/fixpoint messages are therefore expected during
    this bootstrap pass.
    Fix: pass -s to this first HeVeA invocation in asllib/doc/Makefile. This
    silences only the bootstrap pass; later unsilenced output is still used to
    catch warnings that survive reference convergence.

  • Post-bibliography citation and fixpoint warnings.
    Example warning: ./LexicalStructure.tex:436: Warning: Undefined citation: 'ASU86'.
    Cause: bibhva makes bibliography entries available after the first HeVeA
    pass. The next HeVeA pass is therefore the first pass that can consume the
    generated bibliography data, resolve citations, and update HeVeA's own
    cross-reference state. If that pass is also the final unsilenced pass, HeVeA
    reports transient undefined-citation and changed-label warnings even though a
    subsequent pass would resolve them.
    Fix: add one silent hevea -fix0 -s pass immediately after bibhva in
    asllib/doc/Makefile. This lets HeVeA absorb the bibliography/citation state
    before the final unsilenced hevea -fix pass, so the visible final pass
    starts from stable references.

  • Broken CannotOverapproximate and CannotUnderapproximate anchors.
    Example warning: ASL.html:27550: Warning, cannot find anchor: constant-CannotOverapproximate.
    Cause: macros.hva linked these HTML-only macro definitions to
    constant-CannotOverapproximate and constant-CannotUnderapproximate, but
    the generated HTML anchors are type-CannotOverapproximate and
    type-CannotUnderapproximate.
    Fix: update the two macros.hva links to use the generated type-* anchors.

  • Unused \commonprefixline and \commonsuffixline overrides.
    Example warning: ./ASLmacros.tex:329: Warning: Ignoring (re-)definition of '\commonprefixline' by \newcommand.
    Cause: these macros were no longer used in the TeX sources, but definitions
    remained in both ASLmacros.tex and macros.hva. HeVeA still processed those
    unused definitions and reported redefinition warnings.
    Fix: remove the unused definitions from both files.

  • Rule-list aux writes.
    Example warning: ./TypeAttributes.tex:9: Warning: Command not found: \immediate.
    Cause: ASLmacros.tex records rule-list entries with
    \immediate\write\@auxout{...\unexpanded{...}}, which HeVeA does not
    support. In HTML builds this produced command warnings, leaked raw
    \ASLRuleListEntry... text into generated pages, and left rule-list outlines
    saying "Run LaTeX again".
    Fix: override the HTML-only rule-recording macros in macros.hva so they
    write equivalent \ASLRuleListEntry commands through HeVeA's .haux
    mechanism with \@auxdowrite, instead of using TeX's aux stream. Also
    override \ASLRuleListEntry for HTML to accumulate entries with HeVeA token
    registers (\newtokens/\addtokens) rather than LaTeX's unsupported
    \g@addto@macro; install that override before HeVeA reads .haux. The
    generated outlines now contain linked rule entries, the "Run LaTeX again"
    placeholders are gone, and the aux-write warnings are suppressed.

  • Parse-tree warning suppression.
    Example warning: ./Syntax.tex:845: Warning: Command not found: \adjustbox.
    Cause: Syntax.tex uses adjustbox and qtree's \Tree, which HeVeA does
    not understand. Without HTML-specific handling, HeVeA reports unknown-command
    warnings and emits visible raw text such as max width=... alongside the raw
    qtree bracket syntax.
    Fix: define a one-argument no-op adjustbox environment in macros.hva so
    the width option is consumed instead of rendered as text, and define \Tree
    as a no-op so HeVeA stops warning about it. This keeps the source TeX
    unchanged and avoids special encodings for individual trees in Syntax.tex.
    This PR intentionally only suppresses the HeVeA warnings; it does not attempt
    to implement qtree rendering in HTML, so the generated HTML still shows the
    raw qtree bracket syntax.

  • Unsupported math primitives.
    Example warning: ./Semantics.tex:284: Warning: Command not found: \mathchoice.
    Cause: some ASL macros use TeX primitives that HeVeA does not support,
    including \mathchoice, \mathaccent, and \Big. The affected forms
    include \parallelgraphs and \disjointunion.
    Fix: add HTML-only replacements in macros.hva after ASLmacros.tex has
    loaded. \parallelgraphs keeps its hyperlink but renders the list parallel
    operator as a larger ASCII ||, avoiding \mathchoice and \Big;
    \disjointunion keeps its hyperlink but renders as a larger Unicode multiset
    union, avoiding \mathaccent. Representative definition and rule-use sites
    were visually inspected in the generated HTML, and the larger operator
    rendering was accepted.

  • HTML macro override warnings.
    Example warning: ./ASLmacros.tex:25: Warning: Ignoring (re-)definition of '\mathhypertarget' by \newcommand.
    Cause: macros.hva intentionally defines HTML-specific versions of macros
    that are also defined in ASLmacros.tex, so HeVeA reports redefinition
    warnings when ASLmacros.tex later defines the same names.
    Fix: for body-use overrides that can be changed entirely within macros.hva,
    define private \my@... implementations and install them with
    \AtBeginDocument after ASLmacros.tex has loaded. This removes the
    redefinition warnings for \reverseeqdef, \ordered, \orderedctrl,
    \ordereddata, \orderedpo, \Ignore, \Option, \derivesinline,
    \anycharacter, \CannotOverapproximate, and \CannotUnderapproximate.
    For early-load helpers that must exist while ASLmacros.tex is being read
    (\mathhypertarget, \texthypertarget, and \lightyellow), change the
    shared TeX definitions to \providecommand. The PDF build still defines
    those helpers when no HTML override exists, while HeVeA keeps the definitions
    from macros.hva without reporting redefinition warnings.

  • HeVeA comment package status output.
    Example output: Exclude comment 'comment'.
    Cause: ASLmacros.tex loaded the LaTeX comment package, but the ASL
    document sources do not use comment environments or any
    includecomment/excludecomment/specialcomment commands. HeVeA's
    comment.hva defines the default comment environment by calling
    \excludecomment, and that shim emits this status line once per HeVeA
    invocation. This is not a Warning: line, but it still added noise to the
    captured HTML build messages.
    Fix: since the package was confirmed unused, remove
    \usepackage{comment} from ASLmacros.tex. The HTML build no longer loads
    comment.hva, so the status output disappears. The PDF build was rebuilt and
    spot-checked after the removal.

  • \implies \renewcommand warning.
    Example warning: ./ASLmacros.tex:508: Warning: Defining '\implies' by \renewcommand.
    Cause: ASLmacros.tex redefined LaTeX's built-in \implies with
    \renewcommand to add a hyperlink to the ASL implication definition. HeVeA
    renders the macro correctly but warns about this \renewcommand.
    Fix: keep the same linked \Rightarrow expansion, but define it with \def
    instead of \renewcommand. The generated HTML was checked at the implication
    definition and a generated rule use to confirm the linked rendering is
    unchanged. The PDF rendering was also inspected and accepted.

  • Incomplete enumitem.hva shim.
    Example warning: ./ASLmacros.tex:143: Warning: Command not found: \setlistdepth.
    Cause: ASLmacros.tex loads enumitem to configure deeply nested inline
    itemize lists. HeVeA finds the local enumitem.hva package shim, which
    already ignores \renewlist and \setlist, but the shim did not define
    \setlistdepth. HeVeA therefore treated \setlistdepth{20} as an unknown
    command and emitted a warning.
    Fix: add a one-argument no-op definition to enumitem.hva:
    \newcommand{\setlistdepth}[1]{}. This matches the existing shim strategy:
    keep the LaTeX list customization for PDF output, while letting HeVeA ignore
    enumitem-specific list setup that it does not need to render the HTML.

  • \not\derives.
    Example warning: ./Syntax.tex:867: Warning: Cannot apply '\not' to '\derives'.
    Cause: Syntax.tex uses \not\derives, and HeVeA cannot apply \not to
    the custom \derives macro.
    Fix: define HeVeA's internal negated form of \derives in macros.hva,
    rendering \not\derives as -/->. This suppresses the warning while
    producing a negated derivation arrow closer in width to the normal
    \longrightarrow-based \derives rendering.

  • Negative \vspace.
    Example warning: ./Syntax.tex:394: Warning: \vspace with arg '-\baselineskip'.
    Cause: Syntax.tex used \vspace*{-\baselineskip}, which HeVeA reports as a
    spacing warning.
    Fix: remove the spacing command from Syntax.tex; visual inspection showed
    no meaningful difference in the surrounding grammar display.

  • frontmatter/mainmatter macros.
    warning: ./ASLReference.tex:30: Warning: Command not found: \frontmatter
    ./ASLReference.tex:33: Warning: Command not found: \mainmatter`
    Fix: defined no-op shims

@Roman-Manevich Roman-Manevich requested a review from hrutvik July 7, 2026 01:31
@Roman-Manevich Roman-Manevich marked this pull request as ready for review July 7, 2026 01:33
Comment thread asllib/doc/Makefile
@Roman-Manevich Roman-Manevich force-pushed the aslref-hevea-warnings branch from fcebab1 to 08c0af1 Compare July 8, 2026 14:01
@Roman-Manevich Roman-Manevich requested a review from hrutvik July 8, 2026 14:03
Comment thread asllib/doc/Makefile
@Roman-Manevich Roman-Manevich requested a review from hrutvik July 8, 2026 15:38
@Roman-Manevich Roman-Manevich marked this pull request as draft July 10, 2026 09:55
@Roman-Manevich Roman-Manevich force-pushed the aslref-hevea-warnings branch from 08c0af1 to 9fde3f6 Compare July 10, 2026 10:28
@Roman-Manevich Roman-Manevich marked this pull request as ready for review July 10, 2026 10:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants