Merge pull request #7119 from NotMyFault/docs/master/jelly-escape

Don't escape special chars in Jelly doc
jenkinsci · Sep 21, 2022 · d25704c · d25704c
2 parents f703f90 + da68b89
commit d25704c
Show file tree

Hide file tree

Showing 54 changed files with 299 additions and 237 deletions.
diff --git a/core/src/main/resources/hudson/model/AbstractItem/delete.jelly b/core/src/main/resources/hudson/model/AbstractItem/delete.jelly
@@ -24,8 +24,9 @@ THE SOFTWARE.
 
 <?jelly escape-by-default='true'?>
 <j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:l="/lib/layout" xmlns:f="/lib/form">
-	<st:documentation>
-		Deprecated. Instead use a &lt;l:confirmationLink/> directly to /job/*/doDelete.
+	<st:documentation> <![CDATA[
+		Deprecated. Instead use a <l:confirmationLink/> directly to /job/*/doDelete.
+	]]>
 	</st:documentation>
   <l:layout>
 		<st:include page="sidepanel.jelly" />

diff --git a/core/src/main/resources/hudson/model/AbstractProject/makeDisabled.jelly b/core/src/main/resources/hudson/model/AbstractProject/makeDisabled.jelly
@@ -1,7 +1,8 @@
 <?jelly escape-by-default='true'?>
 <j:jelly xmlns:j="jelly:core" xmlns:p="/lib/hudson/project" xmlns:st="jelly:stapler">
-    <st:documentation>
-        Deprecated but kept for compatibility. Use &lt;p:makeDisabled/>.
+    <st:documentation> <![CDATA[
+        Deprecated but kept for compatibility. Use <p:makeDisabled/>.
+    ]]>
     </st:documentation>
     <p:makeDisabled/>
 </j:jelly>
diff --git a/core/src/main/resources/hudson/security/HudsonPrivateSecurityRealm/_entryForm.jelly b/core/src/main/resources/hudson/security/HudsonPrivateSecurityRealm/_entryForm.jelly
@@ -29,8 +29,9 @@ THE SOFTWARE.
     <st:attribute name="it" use="required" type="hudson.security.HudsonPrivateSecurityRealm">
       Context where the page is loaded.
     </st:attribute>
-    <st:attribute name="title" use="required">
-      Title of the HTML page. Rendered in the page content inside a &lt;h1>.
+    <st:attribute name="title" use="required"> <![CDATA[
+      Title of the HTML page. Rendered in the page content inside a <h1>.
+    ]]>
     </st:attribute>
     <st:attribute name="action" use="required">
       The method to call from within the HudsonPrivateSecurityRealm.

diff --git a/core/src/main/resources/hudson/security/HudsonPrivateSecurityRealm/_entryFormPage.jelly b/core/src/main/resources/hudson/security/HudsonPrivateSecurityRealm/_entryFormPage.jelly
@@ -29,9 +29,10 @@ THE SOFTWARE.
     <st:attribute name="host" use="required" type="hudson.security.HudsonPrivateSecurityRealm">
       Corresponds to the "it" of Jelly, meaning the context where the page is loaded.
     </st:attribute>
-    <st:attribute name="title" use="required">
+    <st:attribute name="title" use="required"> <![CDATA[
       Title of the HTML page. 
-      Rendered into &lt;title> tag, in the page content inside a &lt;h1> and as the label of the submit button.
+      Rendered into <title> tag, in the page content inside a <h1> and as the label of the submit button.
+      ]]>
     </st:attribute>
     <st:attribute name="action" use="required">
       The method to call from within the HudsonPrivateSecurityRealm.

diff --git a/core/src/main/resources/lib/form/breadcrumb-config-outline.jelly b/core/src/main/resources/lib/form/breadcrumb-config-outline.jelly
@@ -22,10 +22,11 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 -->
 <?jelly escape-by-default='true'?>
-<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define" xmlns:l="/lib/layout" xmlns:i="jelly:fmt" xmlns:x="jelly:xml">
-  <st:documentation>
+<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:l="/lib/layout">
+  <st:documentation> <![CDATA[
     Adds one more in-page breadcrumb that jumps to sections in the page.
-    Put this tag right before &lt;l:main-panel>
+    Put this tag right before <l:main-panel>
+    ]]>
     <st:attribute name="title">
       Optional title for this breadcrumb
     </st:attribute>

diff --git a/core/src/main/resources/lib/form/checkbox.jelly b/core/src/main/resources/lib/form/checkbox.jelly
@@ -23,9 +23,10 @@ THE SOFTWARE.
 -->
 
 <?jelly escape-by-default='true'?>
-<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define" xmlns:l="/lib/layout" xmlns:t="/lib/hudson" xmlns:f="/lib/form">
-  <st:documentation>
-    &lt;input type="checkbox"> tag that takes true/false for @checked, which is more Jelly friendly.
+<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:f="/lib/form">
+  <st:documentation> <![CDATA[
+    <input type="checkbox"> tag that takes true/false for @checked, which is more Jelly friendly.
+    ]]>
 
     <st:attribute name="name" />
     <st:attribute name="checked" />
@@ -37,7 +38,7 @@ THE SOFTWARE.
       and none otherwise, making the subset selection easier.
     </st:attribute>
     <st:attribute name="default">
-      The default value of the check box, in case both @checked and @instance are null.
+      The default value of the checkbox, in case both @checked and @instance are null.
       If this attribute is unspecified or null, it defaults to unchecked, otherwise checked.
     </st:attribute>
     <st:attribute name="id" />
@@ -50,12 +51,13 @@ THE SOFTWARE.
     </st:attribute>
     <st:attribute name="class" />
     <st:attribute name="negative" />
-    <st:attribute name="readonly" deprecated="true">
+    <st:attribute name="readonly" deprecated="true"> <![CDATA[
       If set to true, this will take precedence over the onclick attribute and prevent the state of the checkbox from being changed.
 
       Note: if you want an actual read only checkbox then add:
-      &lt;j:set var="readOnlyMode" value="true"/&gt; inside your entry tag
+      <j:set var="readOnlyMode" value="true"/> inside your entry tag
       See https://www.jenkins.io/doc/developer/views/read-only/#enabling-read-only-view-support
+      ]]>
     </st:attribute>
     <st:attribute name="field">
       Used for databinding. TBD.

diff --git a/core/src/main/resources/lib/form/class-entry.jelly b/core/src/main/resources/lib/form/class-entry.jelly
@@ -22,10 +22,9 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 -->
 <?jelly escape-by-default='true'?>
-<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define"
-         xmlns:l="/lib/layout" xmlns:t="/lib/hudson" xmlns:f="/lib/form">
-  <st:documentation>
-    Invisible &lt;f:entry> type for embedding a descriptor's $class field.
+<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:f="/lib/form">
+  <st:documentation> <![CDATA[
+    Invisible <f:entry> type for embedding a descriptor's $class field.
 
     Most of the time a Descriptor has an unique class name that we can use to instantiate the right Describable
     class, so we use the '$class' to represent that to clarify the intent.
@@ -35,6 +34,7 @@ THE SOFTWARE.
     readers we do not put non-unique '$class'.
 
     See Descriptor.newInstancesFromHeteroList for how the reader side is handled.
+    ]]>
 
     <st:attribute name="clazz">
       The describable class that we are instantiating via structured form submission.

diff --git a/core/src/main/resources/lib/form/combobox.jelly b/core/src/main/resources/lib/form/combobox.jelly
@@ -24,24 +24,27 @@ THE SOFTWARE.
 
 <!-- Tomcat doesn't like us using the attribute called 'class' -->
 <?jelly escape-by-default='true'?>
-<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define" xmlns:l="/lib/layout" xmlns:t="/lib/hudson" xmlns:f="/lib/form">
-  <st:documentation>
+<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:f="/lib/form">
+  <st:documentation> <![CDATA[
     Editable drop-down combo box that supports the data binding and AJAX updates.
     Your descriptor should have the 'doFillXyzItems' method, which returns a ComboBoxModel
     representation of the items in your combo box, and your instance field should
     hold the current value.
 
-    For a read only input set &lt;j:set var="readOnlyMode" value="true"/&gt; inside your entry tag
+    For a read only input set <j:set var="readOnlyMode" value="true"/> inside your entry tag
     See https://www.jenkins.io/doc/developer/views/read-only/#enabling-read-only-view-support
-    <st:attribute name="name">
-      This becomes @name of the &lt;input> tag.
+    ]]>
+    <st:attribute name="name"> <![CDATA[
+      This becomes @name of the <input> tag.
       If @field is specified, this value is inferred from it.
+    ]]>
     </st:attribute>
-    <st:attribute name="value">
-      The initial value of the field. This becomes the @value of the &lt;input> tag.
+    <st:attribute name="value"> <![CDATA[
+      The initial value of the field. This becomes the @value of the <input> tag.
       If @field is specified, the current property from the "instance" object
       will be set as the initial value automatically,
       which is the recommended approach.
+    ]]>
     </st:attribute>
     <st:attribute name="default">
       The default value of the combo box, in case both @value and 'instance[field]' are null.

diff --git a/core/src/main/resources/lib/form/descriptorList.jelly b/core/src/main/resources/lib/form/descriptorList.jelly
@@ -37,26 +37,29 @@ THE SOFTWARE.
     <st:attribute name="descriptors" use="required">
       hudson.model.Descriptor collection whose configuration page is rendered.
     </st:attribute>
-    <st:attribute name="instances">
-      Map&lt;Descriptor,Describable> that defines current instances of those descriptors.
+    <st:attribute name="instances"> <![CDATA[
+      Map<Descriptor,Describable> that defines current instances of those descriptors.
       These are used to fill initial values. Other classes that define the get(Descriptor)
       method works fine, too, such as DescribableList.
+    ]]>
     </st:attribute>
-    <st:attribute name="field">
-      Either @field or @instances are required (or @field may be inherited from the ancestor &lt;entry> element).
+    <st:attribute name="field"> <![CDATA[
+      Either @field or @instances are required (or @field may be inherited from the ancestor <entry> element).
       If field is specified, instances are assumed to be instance[field].
 
       When this attribute is specified, JSON structure is properly set up so that the databinding
       can set the field (or pass this collection as a constructor parameter of the same name.
 
       This is more modern way of doing databinding, and thus preferred approach.
+    ]]>
     </st:attribute>
     <st:attribute name="targetType">
       the type for which descriptors will be configured.
       default to ${it.class}
     </st:attribute>
-    <st:attribute name="forceRowSet">
-      If specified, instead of a sequence of &lt;f:optionalBlock>s, draw a sequence of &lt;rowSet>s.
+    <st:attribute name="forceRowSet"> <![CDATA[
+      If specified, instead of a sequence of <f:optionalBlock>s, draw a sequence of <rowSet>s.
+    ]]>
     </st:attribute>
   </st:documentation>
 

diff --git a/core/src/main/resources/lib/form/dropdownDescriptorSelector.jelly b/core/src/main/resources/lib/form/dropdownDescriptorSelector.jelly
@@ -22,11 +22,12 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 -->
 <?jelly escape-by-default='true'?>
-<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define" xmlns:l="/lib/layout" xmlns:t="/lib/hudson" xmlns:f="/lib/form">
-  <st:documentation>
-    Renders a single &lt;select> control for choosing a Describable.
+<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define" xmlns:l="/lib/layout" xmlns:f="/lib/form">
+  <st:documentation> <![CDATA[
+    Renders a single <select> control for choosing a Describable.
     Depending on the currently selected value, its config.jelly will be
-    rendered below &lt;select>, allowing the user to configure Describable.
+    rendered below <select>, allowing the user to configure Describable.
+    ]]>
 
     <st:attribute name="field" use="required">
       Form field name. Used for databinding.

diff --git a/core/src/main/resources/lib/form/dropdownList.jelly b/core/src/main/resources/lib/form/dropdownList.jelly
@@ -26,15 +26,17 @@ THE SOFTWARE.
   <st:documentation>
     Foldable block expanded when the corresponding item is selected in the drop-down list.
 
-    <st:attribute name="title">
+    <st:attribute name="title"> <![CDATA[
       Human readable title text of this drop-down listbox.
-      Shown in the same position as &lt;f:entry title="..." />
+      Shown in the same position as <f:entry title="..." />
+    ]]>
     </st:attribute>
     <st:attribute name="name" use="required">
       name of the drop-down list.
     </st:attribute>
-    <st:attribute name="help">
-      Path to the inline help. See &lt;f:entry help="..." />
+    <st:attribute name="help"> <![CDATA[
+      Path to the inline help. See <f:entry help="..." />
+    ]]>
     </st:attribute>
   </st:documentation>
 

diff --git a/core/src/main/resources/lib/form/dropdownListBlock.jelly b/core/src/main/resources/lib/form/dropdownListBlock.jelly
@@ -22,12 +22,13 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 -->
 <?jelly escape-by-default='true'?>
-<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define" xmlns:l="/lib/layout" xmlns:t="/lib/hudson" xmlns:f="/lib/form">
+<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define" xmlns:l="/lib/layout" xmlns:f="/lib/form">
   <st:documentation>
     Foldable block expanded when the corresponding item is selected in the drop-down list.
 
-    <st:attribute name="value" use="required">
-      value of the list item. set to &lt;option value="...">
+    <st:attribute name="value" use="required"> <![CDATA[
+      value of the list item. set to <option value="...">
+    ]]>
     </st:attribute>
     <st:attribute name="title" use="required">
       human readable text displayed for this list item.
@@ -39,9 +40,10 @@ THE SOFTWARE.
       provide hint for stapler data binding.
       typically set to ${descriptor.clazz.name} if dropdownList is for a list of descriptors.
     </st:attribute>
-    <st:attribute name="lazy">
+    <st:attribute name="lazy"> <![CDATA[
       If specified, the content of the dropdownListBlock will be rendered lazily when it first becomes visible.
-      The attribute value must be the variables to be captured. See the @capture of &lt;renderOnDemand> tag.
+      The attribute value must be the variables to be captured. See the @capture of <renderOnDemand> tag.
+    ]]>
     </st:attribute>
   </st:documentation>
   <j:choose>

diff --git a/core/src/main/resources/lib/form/editableComboBox.jelly b/core/src/main/resources/lib/form/editableComboBox.jelly
@@ -24,15 +24,16 @@ THE SOFTWARE.
 
 <!-- Tomcat doesn't like us using the attribute called 'class' -->
 <?jelly escape-by-default='true'?>
-<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define" xmlns:l="/lib/layout" xmlns:t="/lib/hudson" xmlns:f="/lib/form">
+<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define" xmlns:f="/lib/form">
   <st:documentation>
     Editable drop-down combo box. Deprecated as of 1.356. Use f:combobox and databinding instead.
 
     <st:attribute name="clazz">
       Additional CSS classes that the control gets.
     </st:attribute>
-    <st:attribute name="items">
-      List of possible values. Either this or nested &lt;f:editableComboBoxValue/>s are required.
+    <st:attribute name="items"> <![CDATA[
+      List of possible values. Either this or nested <f:editableComboBoxValue/>s are required.
+    ]]>
     </st:attribute>
     <st:attribute name="field">
       Used for databinding.

diff --git a/core/src/main/resources/lib/form/editableComboBoxValue.jelly b/core/src/main/resources/lib/form/editableComboBoxValue.jelly
@@ -24,9 +24,10 @@ THE SOFTWARE.
 
 <?jelly escape-by-default='true'?>
 <j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler">
-  <st:documentation>
-    Used inside &lt;f:editableComboBox/> to specify one value of a combobox.
+  <st:documentation> <![CDATA[
+    Used inside <f:editableComboBox/> to specify one value of a combobox.
     Normally one would use multiple values.
+    ]]>
     <st:attribute name="value" use="required" />
   </st:documentation>
   <div value="${value}"/>

diff --git a/core/src/main/resources/lib/form/entry.jelly b/core/src/main/resources/lib/form/entry.jelly
@@ -23,13 +23,13 @@ THE SOFTWARE.
 -->
 
 <?jelly escape-by-default='true'?>
-<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define" xmlns:l="/lib/layout" xmlns:t="/lib/hudson" xmlns:f="/lib/form">
-  <st:documentation>
-    An entry of the &lt;f:form>, which is one logical row (that consists of
-    several &lt;TR> tags.
+<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define" xmlns:f="/lib/form">
+  <st:documentation> <![CDATA[
+    An entry of the <f:form>, which is one logical row (that consists of
+    several <TR> tags.
 
     One entry normally host one control.
-
+    ]]>
     <st:attribute name="title">
       Name of the entry. Think of this like a label for the control.
 
@@ -54,14 +54,15 @@ THE SOFTWARE.
     <st:attribute name="class">
       Classes to apply to the form item
     </st:attribute>
-    <st:attribute name="help">
+    <st:attribute name="help"> <![CDATA[
       URL to the HTML page. When this attribute is specified, the entry gets
       a (?) icon on the right, and if the user clicks it, the contents of the
       given URL is rendered as a box below the entry.
 
-      The URL should return an HTML document wrapped in a &lt;div> tag.
+      The URL should return an HTML document wrapped in a <div> tag.
       The URL is interpreted to be rooted at the context path of Hudson,
       so it's normally something like "/plugin/foobar/help/abc.html".
+        ]]>
     </st:attribute>
   </st:documentation>
   <j:if test="${attrs.help==null and attrs.field!=null}">

diff --git a/core/src/main/resources/lib/form/enum.jelly b/core/src/main/resources/lib/form/enum.jelly
@@ -23,12 +23,12 @@ THE SOFTWARE.
 -->
 
 <?jelly escape-by-default='true'?>
-<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define" xmlns:l="/lib/layout" xmlns:t="/lib/hudson" xmlns:f="/lib/form">
-  <st:documentation>
-    Binds an enum field to a &lt;select> element.
+<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define" xmlns:f="/lib/form">
+  <st:documentation> <![CDATA[
+    Binds an enum field to a <select> element.
     The body of this tag is evaluated for each enum value,
     which is passed as 'it'.
-
+    ]]>
     <st:attribute name="field">
       Used for databinding. TBD.
     </st:attribute>

diff --git a/core/src/main/resources/lib/form/enumSet.jelly b/core/src/main/resources/lib/form/enumSet.jelly
@@ -23,10 +23,11 @@ THE SOFTWARE.
 -->
 
 <?jelly escape-by-default='true'?>
-<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define" xmlns:l="/lib/layout" xmlns:t="/lib/hudson" xmlns:f="/lib/form">
-  <st:documentation>
+<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:f="/lib/form">
+  <st:documentation> <![CDATA[
     Binds a set of Enum to a list of checkboxes, each with the label taken from enum Enum.toString()
-    Should be used inside an &lt;f:entry field='...'> element.
+    Should be used inside an <f:entry field='...'> element.
+    ]]>
     <st:attribute name="field" implicit="true">
       Used for databinding.
     </st:attribute>
@@ -39,4 +40,4 @@ THE SOFTWARE.
       </div>
     </j:forEach>
   </div>
-</j:jelly>
+</j:jelly>