SpringSaLaD help pages exist but are unreachable: four TOC entries are commented out

[jcschaff]

Four finished SpringSaLaD help pages ship in the source but cannot be reached from the in-app help, because their <tocitem> entries in TOC.xml are commented out.

Part of #1729.

The pages

Target	Title	File
SpringSaLaDTheory	Introduction to SpringSaLaD Modeling	topics/ch_10/RuleBasedChapter/SpringSaLaDTheory.xml
LangevinApp	SpringSaLaD Application	topics/ch_10/RuleBasedChapter/LangevinApp.xml
SSSpeciesSpecifications	SpringSaLaD Species	topics/ch_3/BioModelApplications/Specifications/SSSpeciesSpecifications.xml
SSReactionsSpecifications	SpringSaLaD Reactions	topics/ch_3/BioModelApplications/Specifications/SSReactionsSpecifications.xml

They read as finished content — LangevinApp.xml has an introduction, the compartment/geometry limitations, and an image reference.

Where they are hidden

vcell-client/UserDocumentation/originalXML/TOC.xml:

<tocitem target="NFSimApp" text="Network-Free Application"/>
<!--    <tocitem target="SpringSaLaDTheory" text="Introduction to SpringSaLaD Modeling"/>
        <tocitem target="LangevinApp" text="SpringSaLaD Application"/> -->

plus two more under Specifications (SSSpeciesSpecifications, SSReactionsSpecifications).

DocumentCompiler reports all four on every build:

ERROR: Document page 'LangevinApp' not referenced in either table of contents or from another document

This looks deliberate, which is why it needs a decision rather than a patch

They were commented out by 98c61c236f (Dan Vasilescu, 2024-07-02, "Documentation: Batch simulation help") — the same commit that authored two of them. That reads as gating content ahead of the feature's public release, not as an accident. SpringSaLaD has shipped since, so the gate has probably outlived its purpose, but the author should confirm none of the content is still provisional.

@danv61 — is any of this still considered unfinished?

Verified fix

Uncommenting the four entries is the whole change. Confirmed by running org.vcell.documentation.DocumentCompiler over the doc source: all four pages render to HTML and their "not referenced" errors disappear. No other page is affected.

Two pre-existing problems are not touched by this and remain: WarningsList and SimResultsDataRange are also orphaned, and four images exceed the compiler's 500,000-byte limit (VCellMain.png is 1.4 MB).

Gotcha for whoever does it

The build-documentation Maven profile activates only when target/classes/vcellDoc is missing, so a plain rebuild silently skips the help build and doc changes appear to have no effect. Delete that directory, or run DocumentCompiler directly:

java -cp "<vcell-client classes>:<deps>" org.vcell.documentation.DocumentCompiler \
     vcell-client/UserDocumentation/originalXML /tmp/vcellDoc

Also note TOC.xml is CRLF — patch it without rewriting line endings.

🤖 Generated with Claude Code

https://claude.ai/code/session_019HAnpFxkzf9LmxBayDSANf