[SOLR-14889] improve templated variable escaping in ref-guide _config.yml

• Type: Task
• Status: Closed
• Priority: Major
• Resolution: Fixed
• Fix Version/s: 9.0
• Component/s: documentation
• Assignee: Chris M. Hostetter
• Reporter: Chris M. Hostetter
• Created: 22/Sep/20 17:18
• Updated: 12/May/22 00:26
• Resolved: 29/Sep/20 18:11

Description

SOLR-14824 ran into windows failures when we switching from using a hardcoded "relative" path to the solrRootPath  to using groovy/project variables to get the path.  the reason for the failures was that the path us used as a variable tempted into _config.yml.template to build the _config.yml file, but on windows the path seperater of '\' was being parsed by jekyll/YAML as a string escape character.

(This wasn't a problem we ran into before, even on windows, prior to the SOLR-14824 changes, because the hardcoded relative path only used '/' delimiters, which (j)ruby was happy to work with, even on windows.

As Uwe pointed out when hotfixing this...

Problem was that backslashes are used to escape strings, but windows paths also have those. Fix was to add StringEscapeUtils, but I don't like this too much. Maybe we find a better solution to make special characters in those properties escaped correctly when used in strings inside templates.

...the current fix of using StringEscapeUtils.escapeJava - only for this one variable – doesn't really protect other variables that might have special charactes in them down the road, and while "escapeJava" work ok for the "\" issue, it isn't neccessarily consistent with all YAML escapse, which could lead to even weird bugs/cofusion down the road.

Issue Links

• is related to: SOLR-14824 Simplify set of Ref Guide build parameters