Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add warning about 2 titles to example topic #931

Merged
merged 1 commit into from
Jul 2, 2024
Merged

Add warning about 2 titles to example topic #931

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 19 additions & 1 deletion specification/common/reuse-w-lwdita/reuse-example.dita
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,25 @@
<title><xmlelement>example</xmlelement></title>
<shortdesc id="shortdesc" platform="dita lwdita">An example illustrates
the subject of the topic or a portion of the topic.</shortdesc>
<refbody><!--<section id="usage-information"><title>Usage information</title><p platform="dita">Use <xmlelement>example</xmlelement> to contain both sample code (or similar artifacts) and the discussion that illustrates the sample. For example, a topic about programming code could use the <xmlelement>example</xmlelement> element to contain both the sample code and the text that describes the code.</p><p platform="lwdita">Use the example component to contain both sample code (or similar artifacts) and the discussion that illustrates the sample. For example, a topic about programming code could use the example component to contain both the sample code and the text that describes the code.</p></section>-->
<refbody>
<section id="usage-information">
<title>Usage information</title>
<p>For maximum flexibility in creating specializations, examples allow
plain text as well as phrase and block level elements. Because of the way XML grammars are
defined within a DTD, any element that allows plain text cannot restrict the order or
frequency of other elements. As a result, the <xmlelement>example</xmlelement> element
allows <xmlelement>title</xmlelement> to appear anywhere as a child of
<xmlelement>example</xmlelement>. However, the intent of the specification is that
<xmlelement>title</xmlelement> only be used once in any <xmlelement>example</xmlelement>,
and when used, that it precede any other text or element content.</p>
</section>
<section id="rendering-expectations">
<title>Rendering expectations</title>
<p platform="dita" outputclass="errorcondition">Processors <term outputclass="RFC-2119"
>SHOULD</term> treat the presence of more than one <xmlelement>title</xmlelement> element
in a <xmlelement>example</xmlelement> element as an error.</p>
<!--<p platform="lwdita" outputclass="errorcondition">Processors <term outputclass="RFC-2119">SHOULD</term> treat the presence of more than one title component in an example component as an error.</p>-->
</section>
<section id="attributes">
<title>Attributes</title>
<p conkeyref="reuse-attributes/only-universal" platform="dita"/>
Expand Down
2 changes: 2 additions & 0 deletions specification/langRef/base/example.dita
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@
</keywords>
</metadata></prolog>
<refbody>
<section conkeyref="reuse-example/usage-information" id="usage-information"/>
<section conkeyref="reuse-example/rendering-expectations" id="rendering-expectations"/>
<section conkeyref="reuse-example/attributes" id="attributes"/>
<example id="example" otherprops="examples"><title>Example</title>
<p>The following code sample shows an <xmlelement>example</xmlelement> element that contains a
Expand Down
Loading