Inside the samples folder, you will find the following sub-folders:
conrefs
+reusing_topics_and_maps
+writing_for_reuse
+Inside the samples folder, you will find the following sub-folders:
conrefs
+reusing_topics_and_maps
+writing_for_reuse
+Inside the samples folder, you will find the following sub-folders:
conrefs
+reusing_topics_and_maps
+writing_for_reuse
+Inside the samples folder, you will find the following sub-folders:
conrefs
+reusing_topics_and_maps
+writing_for_reuse
+This lesson introduces relationship tables, then shows how to create a relationship + table, how to populate it, and how to use the collection-type and linking + attributes.
+Inside the samples folder, you will find the following sub-folders:
exercises
+samples
+Inside the samples folder, you will find the following sub-folders:
conrefs
+reusing_topics_and_maps
+writing_for_reuse
+For the healthiest ducks, we recommend using our feeds.
+All our duck feeds are composed of cracked corn, oats, rice, and milo seed.
+
All feeds are available in 5, 10, and 20 pound sacks.
+The Duck Database tables will handle most of your duck needs.
+If you have additional needs, consider using the custom table feature.
+For more information on the standard tables, see Appendix C.
+You need to be careful when filtering elements that have required children, or otherwise might result in invalid structure. If filtering removes required elements, - it will result in an invalid topic. For example, if you add filtering attributes to + it will result in an invalid topic. For example, if you add conditional attributes to all <li> elements in an unordered list (<ul>) and filtering removes them all, the empty <ul> element will be invalid. Other elements that have required children include <ol>, <sl>, <steps>, <substeps>, <properties>, diff --git a/en-us/course7_reuse_advanced/topics/lc_conditions_best_practices.dita b/en-us/course07-reuse_advanced/topics/lc_conditions_best_practices.dita similarity index 88% rename from en-us/course7_reuse_advanced/topics/lc_conditions_best_practices.dita rename to en-us/course07-reuse_advanced/topics/lc_conditions_best_practices.dita index 42e02f04..7bf271a6 100644 --- a/en-us/course7_reuse_advanced/topics/lc_conditions_best_practices.dita +++ b/en-us/course07-reuse_advanced/topics/lc_conditions_best_practices.dita @@ -24,7 +24,7 @@ poorly constructed—or even non-sensical—sentences.
Communicate your choices
Create a style guide or some other form of documentation so that everyone on your - team, organization, or company uses filtering attributes and values consistently.
+ team, organization, or company uses conditional attributes and values consistently.Make sure you have agreement on:
Consider specialization
-If the there are not enough filtering attributes for your needs, or if the names of +
If the there are not enough conditional attributes for your needs, or if the names of the attributes do not fit with how you are using them, consider using the DITA - specialization mechanisms to create additional filtering attributes.
+ specialization mechanisms to create additional conditional attributes. diff --git a/en-us/course07-reuse_advanced/topics/lc_conditions_ditaval.dita b/en-us/course07-reuse_advanced/topics/lc_conditions_ditaval.dita new file mode 100644 index 00000000..fc2008e6 --- /dev/null +++ b/en-us/course07-reuse_advanced/topics/lc_conditions_ditaval.dita @@ -0,0 +1,70 @@ + + + +When generating output from sources that use the conditional attributes, + you need to tell the output processor what to hide and what to show.
In most
+ output generators, you use a
The ditaval file is an XML file, but it is not + a DITA file (that is, it does not use the DITA doctypes or elements). In DITA 1.2, + the ditaval file is not included in DITA maps; the file path to your ditaval file is + passed to output generators using a command argument. (In DITA 1.3, you can use the + <ditavalref> element to include a ditaval file in a DITA map.)
The name of + your ditaval file is up to you, although it’s a good idea to use a filename that + indicates the file’s purpose. Typically you store the ditaval file along with your + maps, although it can reside anywhere that is accessible to your output generator. +
Typically you will have one ditaval file for each main map or bookmap + file.
The root element in the ditaval file is the <val> element; in a + typical file the <val> element contains one or more <props> + elements.
<val> + <prop att="platform" val="iphone" action="exclude" /> +</val>
This + example shows the basic form of a <prop> element.
Conditional filtering example
In this example DITA topic, the + second <p> element contains a sentence within a <ph> (phrase) element. The + product conditional attribute has the value + “wild_ducks".
<p>For the healthiest ducks, we recommend using our feeds.</p> +<p>All our duck feeds are composed of cracked corn, oats, rice, and milo seed. +<ph product="wild_ducks">Our wild duck feed also includes worm meal and fish meal. </ph> +</p> +<p>All feeds are available in 5, 10, and 20 pound sacks.</p> +
If + you generate output from this content without using a ditaval file, it looks like + this:
But if you use this ditaval file to filter out content where + product="wild_ducks":
<val> + <prop action="exclude" att="product" val="wild_ducks" /> +</val>
The + output looks like this:
For more information about ditaval files and how to use them for
+ filtering, see
DITA conditional filtering allows to choose what to show and hide in your DITA topics when they are processed for output.
-You mark DITA elements for filtering by adding special filtering attributes to - elements; the value you use with a filtering attribute is used to determine whether +
You mark DITA elements for filtering by adding special conditional attributes to + elements; the value you use with a conditional attribute is used to determine whether the element should be hidden (filtered out) or shown.
-The four basic filtering attributes and their suggested uses are:
The four basic conditional attributes and their suggested uses are:
The names of the attributes are defined in the DITA specification. They are a @@ -56,10 +56,10 @@ elements where platform has the value “iphone” and hide elements where platform has the value “android”. (How to hide and show content is described later in this lesson.)
-As with the attributes themselves, the values you use with each of the filtering +
As with the attributes themselves, the values you use with each of the conditional attributes are up to you to decide. You can use any characters you want for the - filtering attribute values, except for the space character. Case is important in the - filtering attribute values, so choose one form of capitalization and use it + conditional attribute values, except for the space character. Case is important in + the conditional attribute values, so choose one form of capitalization and use it consistently.
You can specify multiple values in these attributes; separate each value with one or more spaces.
@@ -67,12 +67,12 @@ team, company, or organization agree on the purpose of each of the attributes and the values to use with the attributes.Keep in mind that filtering of elements extends to DITA map elements, such as - <topicref> and <mapref>. This way, you can use filtering to remove entire - topics or chapters from your output.
+ <topicref> and <mapref>. This way, you can use conditional attributes and + filtering to remove entire topics or chapters from your output.In addition to filtering, you can use conditional attributes to flag (or + highlight) content that is intended for different readers or different products. You + can use any conditional attribute for flagging, and you can use the rev attribute to + indicate and flag a specific revision of your product or service.
Flagging + the conditional attributes
To use the conditional attributes for + flagging, you use the ditaval <prop> element with the action="flag" attribute. + This allows you to flag text with color, background color, text styles, and images + (depending on what is supported in your transforms and the output generator). For + example:
<prop att="platform" val="android" action="flag" color="purple"/>
The + <prop> element show here directs the output generator to use purple text on any + element in which the platform attribute contains the value “android”.
When + flagging, you can use these <prop> attributes to flag text:
The color and background attributes can use either a 6-digit hex color code + (such as "#0000FF") or a color name (aqua, black, blue, fuchsia, gray, green, lime, + maroon, navy, olive, purple, red, silver, teal, white, or yellow).
For + example, if you use this example (from the previous + topic):
With this ditaval file +
<val> + <prop action="flag" att="product" val="wild_ducks" color="red" style="underline"/> +</val>
The + output looks like this:
You can also specify images to place before and after the flagged element. Use + the <startflag> and <endflag> elements as children of a <prop + action="flag"> element. The imageref attribute indicates the path to the image to + use.
<prop att="platform" val="android" action="flag"> + <startflag imageref="images/android_icon.png"> + <alt-text>Android icon</alt-text> + </startflag> +</prop>
The + <startflag> and <endflag> elements can optionally contain an <alt-text> + element that contains alternate text for the image.
The rev + attribute
You use the rev attribute to indicate and flag a specific + revision of your product or service. The rev attribute is available on almost all + DITA elements. You use it just as you would a conditional + attribute:
<p rev="v2.1">If you have additional needs, consider using the custom table feature. </p>
The + values you use with the rev attribute are up to you and your organization. The + important thing is to be consistent in how you use the values.
As with the + conditional attributes you can specify multiple revision values in the rev + attribute; separate the values with one or more spaces. +
<p rev="v2.7 v2.8">The field is limited to 32 characters.</p>
Showing rev flagging in + output
You control the display of the rev attribute with the <revprop> + element in the ditaval file. You can apply styling just as with the <prop> + element (using the color, background color, and style attributes). You can also use + the <startflag> and <endflag> elements to add images before and after the + element marked with the rev attribute.
For example, if a DITA topic contains + this + content:
<p>The Duck Database tables will handle most of your duck needs.</p> +<p rev="2.1">If you have additional needs, consider using the custom table feature.</p> +<p>For more information on the standard tables, see Appendix C.</p> +
And + you generate output using a ditaval file + containing:
<val> + <revprop action="flag" val="2.1" backcolor="aqua"/> +</val>
The + output might look like this:
Depending on the format of your output and your output generator, you can also + use the <revprop> element to place change bars in the margins next to text marked + with a rev attribute. However, the capabilities and the syntax of the changebar + attribute vary depending on the output format and the output generator. If you need + to use this feature, it is best to review the documentation for your output + generator.
For more information about ditaval files and how to use them for
+ flagging, see
Some of the most commonly used elements in a concept topic include:
-<p>
-paragraph
-<ul>
-unordered list
-<ol>
-ordered list
-<note>
-admonition
-These elements were covered in the
<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> -<concept id="my_first_concept"> - <title>Wild duck species</title> - <conbody> --<p>North American wild ducks belong to one of the following categories:</p> - </conbody> -</concept>
Use the <p> element for any body text that does not need a more - specific element tag. As you will see in examples throughout this - course, we recommend using the <p> element to tag text inside - list items, notes, and table entries. <p> elements are needed for - list items that are several paragraphs long, and wrapping single - items in the <p> element keeps them all consistent.
-<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> -<concept id="my_first_concept"> - <title>Wild duck species</title> - <conbody> -... --<ul> -<li><p>Dabbling ducks</p></li> -<li><p>Diving ducks</p></li> -<li><p>Sea ducks</p></li> -<li><p>Whistling ducks</p></li> -<li><p>Swans and geese</p></li> -</ul> - </conbody> -</concept>
If you are using a DITA editor, the editor may insert an ID attribute - on the <ul> element for you automatically.
-<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> -<concept id="my_first_concept"> - <title>Wild duck species</title> - <conbody> -... --<p>The longest species of dabbling ducks in North America are:</p> -<ol> -<li><p>Northern pintail</p></li> -<li><p>Mallard</p></li> -<li><p>American black duck</p></li> -</ol> - </conbody> -</concept>
If you are using a DITA editor, the editor may insert an ID attribute - on the <ol> element for you automatically.
-Use the <ol> element only to show that the list items should - appear in a certain order, not to create step-by-step instructions. - For step-by-step instructions, use the task topic instead.
-<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> -<concept id="my_first_concept"> - <title>Wild duck species</title> - <conbody> -... --<note><p>Although the northern pintail is the longest dabbling duck, the mallard -is generally considered the largest because of its heavier body weight.</p></note> - </conbody> -</concept>
-Content strategy and business goals
-The issues to consider are:
-
Note: Ignoring content can have cost implications across the organization.
-To implement your project and improve your chances of success, we recommend following this sequence:
-DITA concept topics provide information about a particular subject.
-Concept topics help someone understand an idea or the purpose of an instruction. A concept topic may give background - or conceptual information about the subject in addition to essential - information.
-A typical concept topic will mostly contain paragraphs and lists. However, you can - use images, tables, and many other elements in a concept. You can also break a - concept into sections for additional clarity.
- -This lesson shows how to create a new concept topic and how to add commonly used - elements. With the exception of the <conbody> element, the elements presented in - this lesson and throughout the rest of the course are not specific to concepts and - can also be used in the other types of DITA topics (task and reference).
-This lesson covers basic use of these elements. For the full specifications for
- each element, see the
Concept topics contain basic DITA elements, such as paragraphs, lists, images, - tables, and many others. Most of these elements can be used in the other topic types - (task and reference), as well. The only exception is the <conbody> - element, which is specific to the concept topic type.
-At a minimum, the concept topic must contain a <concept> root element (with an id - attribute) that contains a <title> element.
-After the <title> element and an optional <shortdesc> or <abstract> element, - the <conbody> element contains the concept itself.
-The <conbody> element has an open content model. This means that the elements - contained in <conbody> are not required to follow a strict sequence. As long as - an element is allowed inside <conbody>, it can appear in any order. The - exceptions are the <section> and <example> elements, which can only be - followed by other <section> or <example> elements or a <conbodydiv> - element.
-Video:
If you are using a DITA-aware text editor, make sure you are in text - mode, rather than author or visual mode.
-You should see this:
-<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> -<concept id="my_first_concept"> -<title>xyz</title> -</concept>-
The first line (which begins with <?xml) is an XML - declaration, which is a standard part of all XML files.
-The DOCTYPE declaration on the second line identifies this file as a - concept topic.
-The third line is the opening tag of the <concept> element, which uses - the unique ID "my_first_concept".
-The <title> element on the fourth line contains the title of the - topic.
-The fifth line uses the closing tag </concept> to show where the - <concept> element ends.
-When working inside an element, insert the content between the - opening and closing tags.
-<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> -<concept id="my_first_concept"> --<title>Wild duck species</title> -</concept>
When adding an element after another element, insert the new element - after the closing tag of the first element.
-<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> -<concept id="my_first_concept"> - <title>Wild duck species</title> --<conbody> -</conbody> -</concept>
Download
Inside the samples folder, you will find the following folders corresponding to - lessons in this course: lesson1, lesson2, lesson3, and lesson4.
-In each lesson folder, you will find four DITA files:
-l_filename_start.dita: The empty sample file you will add content to as you - follow along with each lesson.
-l_filename.dita: The completed version of the sample file you can use - to check your work.
-l_filename_exercise_start.dita: The empty file you will add content to as - you complete the exercise at the end of each lesson.
-l_filename_exercise.dita: The completed version of the exercise file - you can use to check your work.
-Each lesson will instruct you on which files to use for the exercises. Save your file - as you complete each step to avoid losing your work.
-Create a local copy of each file to work in as you complete the lessons. That way, if - you reach a point where your working file doesn’t match the examples, or is broken - for any reason, you can make a fresh copy and resume your work or start over.
-In the instructions and examples, we show you the DITA code for each sample file.
- Most DITA editors have auto-complete or other similar features to guide you through
- the process of adding elements (for example, if you type the opening tag of an
- element, most DITA editors will automatically add the closing tag for you).
- Therefore, you will probably not need to create every piece of code from scratch as
- you work. Our demo videos were created in
Download
Inside the samples folder, you will find the following sub-folders:
-exercises
-samples
-Each lesson will instruct you on which folders and files to use for the samples and - exercises. Save your file as you complete each step to avoid losing your work.
-Create a local copy of each file to work in as you complete the lessons. That way, if - you reach a point where your working file doesn’t match the examples, or is broken - for any reason, you can make a fresh copy and resume your work or start over.
-In the instructions and examples, we show you the DITA code for each sample file.
- Most DITA editors have auto-complete or other similar features to guide you through
- the process of adding elements (for example, if you type the opening tag of an
- element, most DITA editors will automatically add the closing tag for you).
- Therefore, you will probably not need to create every piece of code from scratch as
- you work. Our demo videos were created in
When generating output from sources that use the filtering attributes, you need to - tell the output processor what to hide and what to show.
-In most output generators, you use a
The ditaval file is an XML file, but it is not a DITA file (that is, it does not use - the DITA doctypes or elements). In DITA 1.2, the ditaval file is not included in - DITA maps; the file path to your ditaval file is passed to output generators using a - command argument. (In DITA 1.3, you can use the <ditavalref> element to include a - ditaval file in a DITA map.)
-The name of your ditaval file is up to you, although it’s a good idea to use a - filename that indicates the file’s purpose. Typically you store the ditaval file - along with your maps, although it can reside anywhere that is accessible to your - output generator.
-Typically you will have one ditaval file for each main map or bookmap file.
-The root element in the ditaval file is the <val> element; in a typical file the - <val> element contains one or more <props> elements.
-<val> - <prop att="platform" val="iphone" action="exclude" /> -</val>-
This example shows the basic form of a <prop> element.
-Beyond filtering: flagging
-In addition to filtering (excluding) content, the <prop> element also allows you - to flag text with color, background color, text styles, and images (depending on - what is supported in your transforms and the output generator). For example:
-<prop att="platform" val="android" action="flag" color="purple"/>-
This <prop> element says to flag any element in which the platform attribute - contains the value “android”; to flag, all text in the element is output in the - color purple. When flagging, you can use these attributes to flag text:
-The color and background attributes can use either a 6-digit hex color code (such as - "#0000FF") or a color name (aqua, black, blue, fuchsia, gray, green, lime, maroon, - navy, olive, purple, red, silver, teal, white, or yellow).
-You can also specify images to place before and after the flagged element. Use the - <startflag> and <endflag> elements as children of a <prop action="flag"> - element. The imageref attribute indicates the path to the image to use.
-<prop att="platform" val="android" action="flag"> - <startflag imageref="images/android_icon.png"> - <alt-text>Android icon</alt-text> - </startflag> -</prop>-
The <startflag> and <endflag> elements can optionally contain an <alt-text> - element that contains alternate text for the image.
-For more information about ditaval files and how to use them for filtering or
- flagging, see
You can use the rev attribute to indicate elements that pertain to a particular - revision of your product or service.
-<p rev="v2.1">Use the key-table feature to speed access.</p>-
The values you use with the rev attribute are up to you and your organization. The - important thing is to be consistent in how you use the values.
-As with the filtering attributes you can specify multiple revision values in the rev - attribute; separate the values with one or more spaces.
-<p rev="v2.7 v2.8">The field is limited to 32 characters.</p>-
Showing rev in output
-You control the display of the rev attribute with the <revprop> element in the - ditaval file. You can apply styling just as with the <prop> element (color, - background color, and style). You can also use the <startflag> and <endflag> - elements to add images before and after the element marked with the rev attribute.
-<revprop action="flag" value="v2.1" color="red"/>-
Depending on the format of your output and your output generator, you can also use - the <revprop> element to place change bars in the margins next to text marked - with a rev attribute. However, the capabilities and the syntax of the changebar - attribute vary depending on the output format and the output generator. If you need - to use this feature, it’s best to review the documentation for your output - generator.
- -