Conversation
jmarrec
added
Defect
template_chunked.html
- Line 97-101: Replaced the non-functional <form> search with a styled button that opens a Bootstrap modal, showing a Ctrl K keyboard hint
- Lines 134-152: Added a Bootstrap modal with search input, results list, empty state, and hint text
- Lines 226-227: Added Fuse.js v7.1.0 via CDN (defer)
- Lines 291-413: Added the search engine JavaScript:
- Fetches search-index.json and builds a Fuse index on page load
- Ctrl+K / Cmd+K and / keyboard shortcuts to open
- 150ms debounced fuzzy search, top 20 results
- Match highlighting using <mark> tags
- Arrow key navigation + Enter to select
- Modal clears state on close
style.css (new section before scrollable navbar)
- Search trigger button styling with kbd shortcut hint
- Modal body max-height for scrollability
- Search result items with active border highlight
- Match <mark> styling with warning-colored background
…h requires serving from a server like python http or npx serve)
Replaces deprecated `\rm` with `\mathrm` in mathematical expressions across the documentation. pandoc to html didn't like \rm
Replace verbose `\raisebox` and `\mathord` constructs for fractions with the standard `\frac` command. This improves the readability and semantic correctness of the LaTeX source, facilitating better maintainability and consistent rendering across documentation tools.
Replace verbose `\mathord` constructs for fractions with the standard `\frac` command. This improves the readability and semantic correctness of the LaTeX source, facilitating better maintainability and consistent rendering across documentation tools, especially for HTML conversion.
Replace non-standard math symbol commands (`\rlap{--}`, `\smallint`) with standard LaTeX (`\overline`, `\int`), use `\textrm` for upright text within math mode instead of `\textup` or `\textnormal`, and remove extraneous manual spacing (`\kern 1pt`, `\;`). This improves semantic correctness, readability, and consistent rendering across documentation tools, particularly for HTML conversion.
All 4 PDFs (engineering-reference, input-output-reference, external-interfaces-application-guide, output-details-and-examples) compiled with zero errors.
## Session summary
Starting from the `html_docs` CMake wiring, this turned into a full sweep of every pandoc math-rendering warning across the doc set. Final state: **0 warnings**, all touched PDFs verified to still compile cleanly in `xelatex`.
Fixes applied, roughly in the order tackled:
- `\rm{...}` / `{\rm X}` / `\bf{...}` (legacy plain-TeX font switches) → `\mathrm{}`/`\mathbf{}`/`\textrm{}`/`\textbf{}` depending on math vs. text context — caught and corrected a regression where blind `\mathrm` substitution broke 4 text-mode usages (`\mathrm` only works in math mode).
- `{\mathop{\rm X}\nolimits}` → `\operatorname{X}` (20 files).
- `\medmuskip`/`\thinmuskip`/etc. register hacks inside `\begin{equation}` → moved outside into an enclosing `{...}` group (14 occurrences, 6 files).
- Diagonal-fraction Word artifacts (`\raise...\hbox{}...\vphantom{}...\lower...\hbox{}` and the bare `\mathord{\left/{\vphantom{}}\right.}` variant) → `\frac{}{}`, including nested cases handled via iterative passes (93 occurrences total); one doubly-nested fraction-of-fractions in `generators.tex` hand-rewritten.
- `\textnormal`/`\textup`/`\textsubscript`/`\smallint` → `\textrm{}`/`_{\text{}}`/`\int` (mode-checked, one text-mode `\textsubscript` correctly left alone).
- `{\kern Npt}` spacing hacks → removed (60 occurrences, 8 files).
- `\rlap{--} \dot V` (ASME volumetric-flow notation) → `\overline{\dot V}` (16 occurrences, 2 files).
- `\emph{}` inside math → `\textit{}`, scoped only to math contexts via a context-tracking scanner (137 occurrences, 3 files) — left thousands of legitimate prose `\emph` untouched.
- Stray `\\` artifacts left inside subscripts/superscripts from Word conversion → removed (28+ occurrences across ~12 files), carefully excluding legitimate `\substack{...\\...}` line breaks.
- `\genfrac{}{}{0pt}{2}{A}{B}` → `\substack{A\\B}` (3 occurrences).
- A genuinely obscure pandoc parser quirk: any equation ending in a single bare token immediately before `\label{}` fails to parse — fixed by wrapping that trailing token in `{}` (12 equations, isolated via bisection since it wasn't documented anywhere).
- A `\footnote{}` embedded inside a math `array` environment (invalid placement) — relocated the footnote to the explanatory prose sentence preceding the equation.
The CMake/HTML-build wiring itself (from earlier in the session) is unaffected by any of this — `BUILD_HTML_DOCS=ON` still produces `html/index.html` + one subdirectory per doc, each with its own chunked pages, search index, and styling, matching the PDF pipeline's structure.
…lename https://github.com/jmarrec/EnergyPlus/actions/runs/27832002956/job/82370826883 Run actions/upload-artifact@v7 With the provided path, there will be 1377 files uploaded Artifact name is valid! Root directory input is valid! Error: The path for one of the files in artifact is not valid: /input-output-reference/1.4-sec:api-usage.html. Contains the following character: Colon : Invalid characters include: Double quote ", Colon :, Less than <, Greater than >, Vertical bar |, Asterisk *, Question mark ?, Carriage return \r, Line feed \n The following characters are not allowed in files that are uploaded due to limitations with certain file systems such as NTFS. To maintain file system agnostic behavior, these characters are intentionally not allowed to prevent potential problems with downloads on different file systems.
367a856 fixed the same, but it was pre-rebase. - **`\begin{array}{*{20}{c}}`** (Word's repeated-column macro, unsupported by pandoc's texmath parser) → replaced with a literal `\begin{array}{ccc}` (max columns needed across all occurrences was 3) in: - `doc/engineering-reference/.../window-calculation-module.tex` - `doc/engineering-reference/.../radiant-system-models.tex` - `doc/engineering-reference/.../zone-equipment-and-zone-forced-air-units.tex` - `doc/input-output-reference/.../group-location-climate-weather-file-access.tex` - **`\rm{...}`** (legacy plain-TeX font switch, same class of fix as `367a85622c`) → `\mathrm{...}` in `doc/input-output-reference/.../group-internal-gains-people-lights-other.tex` - **`\min\!\Bigl(...\Bigr)`** → pandoc's texmath doesn't support `\Bigl`/`\Bigr`; changed to `\bigl`/`\bigr` (matching the `\bigl`/`\bigr` already used elsewhere in the same file) in `doc/engineering-reference/.../ice-thermal-storage.tex` These are all new equations that came in from `develop` during the rebase — none of these files were touched by the original `367a85622c` fixup commit, so they'd never gone through that pass. A from-scratch rebuild of `output-details-and-examples`, `engineering-reference`, and `input-output-reference` now completes with 0 warnings.
…nce Makefile target to test locally the full site
Contributor
|
Can we clean up the main page? 
Seems like the "We are going to start ..." and "The following guides are built separately ..." texts are confusing and can be removed? It's also confusing to have "Contents" and "User Guides". Maybe it should be "API Guides" and "User Guides"? Or perhaps they should be combined into a single "Contents"? I also think the API guides should come below the I/O & Engineering Ref guides, since the latter are surely the most common guides that a user is looking for. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Pull request overview
Description of the purpose of this PR
Add targets to build the latex documentation as HTML via pandoc, and hook it to readthedocs.
A version targeting this branch was added to RTD to demo the changes:
https://energyplus.readthedocs.io/en/html_doc/
(it's hidden from the version picker and search results on purpose)
Pull Request Author
Reviewer