Conditional processing and reuse Managing differences and commonalities

  • Slides: 22
Download presentation
Conditional processing and reuse Managing differences and commonalities in topics and maps June 21,

Conditional processing and reuse Managing differences and commonalities in topics and maps June 21, 2004 © 2004 IBM Corporation

Overview § Conditional processing – Metadata attributes – Filtering – Flagging § Content reuse

Overview § Conditional processing – Metadata attributes – Filtering – Flagging § Content reuse – conref attribute – Current and proposed rules § Substitution – Substituting common files – Manage volatility § Summary 2 DITA conditional processing and reuse © 2004 IBM Corporation

Conditional processing: input § Metadata attributes set in source: <p audience="administrator">Set the configuration options:

Conditional processing: input § Metadata attributes set in source: <p audience="administrator">Set the configuration options: <ul> <li product="extendedprod">Set foo to bar</li> <li product="basicprod extendedprod">Set your blink rate</li> <li>Do some other stuff</li> <li platform="unix">Do a special thing on Unix systems</li> </ul> </p> 3 DITA conditional processing and reuse © 2004 IBM Corporation

Conditional processing: output § Behavior set at build time (filter, flag): <prop att="platform" val="unix"

Conditional processing: output § Behavior set at build time (filter, flag): <prop att="platform" val="unix" action="flag" img="ngunix. gif" alt="Unix"/> <prop att="product" val="extendedprod" action="exclude"/> § Not supported in public package 4 DITA conditional processing and reuse © 2004 IBM Corporation

Filtering § You can filter based on: product platform audience otherprops § Filtering rules:

Filtering § You can filter based on: product platform audience otherprops § Filtering rules: If any one attribute has all values set to exclude, exclude the element An element may have several metadata attributes, each with several values. All the values in at least one of the attributes must be set to exclude, or the content still applies to a valid context. 5 DITA conditional processing and reuse © 2004 IBM Corporation

A note on filtering for media § No media attribute in topics, since they

A note on filtering for media § No media attribute in topics, since they are supposed to be medianeutral § Outputclass attribute provides semantic distinctions for processes to use, when specialization not yet available § Maps do have media attributes, since they often encode mediaspecific structures 6 DITA conditional processing and reuse © 2004 IBM Corporation

Flagging § You can flag based on: product platform audience otherprops rev § Flagging

Flagging § You can flag based on: product platform audience otherprops rev § Flagging rules: If any value of the specified attribute evaluates to flag, flag the element An element may have several metadata attributes, with several values in each. For each value set to flag, a flag is generated - unless the whole element is being excluded, thanks to one of its attributes evaluating to exclude. 7 DITA conditional processing and reuse © 2004 IBM Corporation

Content reuse § conref attribute on most elements in topic and map § Point

Content reuse § conref attribute on most elements in topic and map § Point from one element to another to copy the target's content: § <p conref="abc. dita#mytopic/mypara"/> §. . . § <p id="mypara">Here's the data to copy</p> § Target element has to be the same type (not just element name but class) and in a topic with the same domains (not just same content but same content rules) § Reuse from topic to topic (across types is ok as long as it's an element common to both) and from map to map 8 DITA conditional processing and reuse © 2004 IBM Corporation

Example: source content. dita: <topic id="content"> <title>Conref test: content</title> <body> <p id="oho">Putting an ID

Example: source content. dita: <topic id="content"> <title>Conref test: content</title> <body> <p id="oho">Putting an ID on an element makes it reusable. </p> </body> </topic> reference. dita: <topic id="reference"> <title>Conref test: reference</title> <body> <p conref="content. dita#content/oho"/> </body> </topic> 9 DITA conditional processing and reuse © 2004 IBM Corporation

Example: output 10 DITA conditional processing and reuse © 2004 IBM Corporation

Example: output 10 DITA conditional processing and reuse © 2004 IBM Corporation

Future enhancement possibilities § Better judging of domain matching Currently just compares domain attributes

Future enhancement possibilities § Better judging of domain matching Currently just compares domain attributes on content topic and referencing topic. Should be more intelligent: see if the content topic allows the same or fewer domains, compared to the referencing topic. § Metadata reuse across topics and maps Even though the same metadata elements exist in both map and topic, cannot conref from maps to topics or vice versa to share metadata. (You can get a lot of reuse out of map processing in general without conref reuse, however) § Generalization on the fly should be able to reuse a specialized element from one of its ancestors, and generalize the target at build time, eg <li conref="#mytask/mystep"/> <step id="mystep><cmd>Here's a step</cmd></step> 11 DITA conditional processing and reuse © 2004 IBM Corporation

A note about processing pipelines § Current public package does conref and output in

A note about processing pipelines § Current public package does conref and output in one pass § Works most of the time, except when there's an element in the conref'd content that requires information about the topic it's in § Examples: generated anchors, numbering of figures § When the content in the conref'd element gets processed, the template retrieves element from its real context, not its reusing context - can create problems § Doing it in two passes is more cumbersome but more reliable 12 DITA conditional processing and reuse © 2004 IBM Corporation

Content substitution § Use a common file for volatile elements like product name, user

Content substitution § Use a common file for volatile elements like product name, user interface labels § If your content ships with multiple products with minor variations in UI, maintain multiple copies of the common file: one per product § At build time, substitute the common file with the values you want 13 DITA conditional processing and reuse © 2004 IBM Corporation

Example § Source directory Maintain different directories for different products, single directory for shared

Example § Source directory Maintain different directories for different products, single directory for shared content product. Acommon. dita product. Bcommon. dita component. Xabc. dita, xyz. dita § Build directory: At build time, copy source files from component plus common file from a product directory: product. Acommon. dita, abc. dita, xyz. dita § Output directory: infocenterabc. html, xyz. html 14 DITA conditional processing and reuse © 2004 IBM Corporation

Some reuse strategies § If conditional processing in a topic gets too complicated, create

Some reuse strategies § If conditional processing in a topic gets too complicated, create multiple topics with shared content Let the map choose the right topic § If conditional processing in a map gets too complicated, create multiple maps with shared content Let the build process select the right map § Use common files for volatile phrase-level content Let each reusing context manage its own common file § Use predictable reuse patterns wherever possible Easier for people to pick up maintenance of your content § Avoid spaghetti conref and christmas-tree conditions Just because you can do something doesn't mean you should Think of those who will come after you 15 DITA conditional processing and reuse © 2004 IBM Corporation

Example: more differences than commonalities <topic id="abc"> <body> <p product="A">Here's what to do for

Example: more differences than commonalities <topic id="abc"> <body> <p product="A">Here's what to do for A</p> <p product="B">Here's what to do for B</p> <p product="C">Here's what to do for C</p> <p>And here's what applies to all of them</p> </body> </topic> 16 DITA conditional processing and reuse © 2004 IBM Corporation

Example: from filtering to sharing ------------------------------------<topic id="a"> <body> <p>Here's what to do for A</p>

Example: from filtering to sharing ------------------------------------<topic id="a"> <body> <p>Here's what to do for A</p> <p conref="shared. dita#shared/all"/> </body> </topic> ------------------------------------<topic id="b"> <body> <p>Here's what to do for B</p> <p conref="shared. dita#shared/all"/> </body> </topic> ------------------------------------<topic id="c"> <body> <p>Here's what to do for C</p> <p conref="shared. dita#shared/all"/> </body> </topic> ------------------------------------<topic id="shared"> <body> <p id="all">And here's what applies to all of them</p> </body> </topic> 17 DITA conditional processing and reuse © 2004 IBM Corporation

Example: with conditions moved into the map <map id="abcmap"> <topicref product="A" href="a. dita"/> <topicref

Example: with conditions moved into the map <map id="abcmap"> <topicref product="A" href="a. dita"/> <topicref product="B" href="b. dita"/> <topicref product="C" href="c. dita"/> </map> If map was mostly conditional content, next step would be to create separate maps for each product, and reuse by conref common branches. 18 DITA conditional processing and reuse © 2004 IBM Corporation

On the value of replacing conditions with conref The strategy of replacing complex conditions

On the value of replacing conditions with conref The strategy of replacing complex conditions with simple conref works well for cases where you are doing lots of filtering, and different teams are working on the same source. It separates concerns into separate files, so that each team can update their content without conflict with others. The strategy would not work well for flagging cases, and would be less necessary in a single-author environment. 19 DITA conditional processing and reuse © 2004 IBM Corporation

Fundamental principles § Keep content ignorant of how it is reused § Keep control

Fundamental principles § Keep content ignorant of how it is reused § Keep control of reuse in the hands of the reuser § Manage context separately from content whenever possible Conditional processing breaks that rule, so use it carefully § If maintenance of reuse costs more than it saves, just copy the content and maintain it twice 20 DITA conditional processing and reuse © 2004 IBM Corporation

Summary § Manage differences with metadata attributes § Manage commonalities with conref § Manage

Summary § Manage differences with metadata attributes § Manage commonalities with conref § Manage volatility with substitution § Don't overmanage 21 DITA conditional processing and reuse © 2004 IBM Corporation

Further reading § Conditional processing note from the DITA forum, replicated to the DITA

Further reading § Conditional processing note from the DITA forum, replicated to the DITA TC list: http: //lists. oasis-open. org/archives/dita/200406/msg 00032. html § SIGDOC paper on reuse by reference in DITA: http: //xml. coverpages. org/dita. html#Priestley-sigdoc 2001 22 DITA conditional processing and reuse © 2004 IBM Corporation

Conditional processing and reuse Managing differences and commonalitiesConditional processing and reuse Managing differences and commonalities
CONDITIONAL CLAUSES Conditional Sentences First Conditional Real ConditionalCONDITIONAL CLAUSES Conditional Sentences First Conditional Real Conditional
EEL 3801 Part V Conditional Processing Conditional ProcessingEEL 3801 Part V Conditional Processing Conditional Processing
Conditional Density Functions and Conditional Expected Values ConditionalConditional Density Functions and Conditional Expected Values Conditional
Conditional Jump Conditional Loop Instructions and Conditional StructuresConditional Jump Conditional Loop Instructions and Conditional Structures
THE CONDITIONAL C The conditional and conditional perfectTHE CONDITIONAL C The conditional and conditional perfect
FIRST CONDITIONAL First conditional We use first conditionalFIRST CONDITIONAL First conditional We use first conditional
Conditional Statements 1 Conditional Statement Definition A conditionalConditional Statements 1 Conditional Statement Definition A conditional
Nested conditional statements Nested conditional statements A conditionalNested conditional statements Nested conditional statements A conditional
CONDITIONAL SENTENCE Conditional Sentence Conditional sentences are sentencesCONDITIONAL SENTENCE Conditional Sentence Conditional sentences are sentences
Conditional Statements Conditional Statements A CONDITIONAL STATEMENT isConditional Statements Conditional Statements A CONDITIONAL STATEMENT is
Conditional 1 2 7 CONDITIONAL 1 CONDITIONAL 2Conditional 1 2 7 CONDITIONAL 1 CONDITIONAL 2
CONTROL STRUCTURES CONDITIONAL CONTROLS Conditional Control Conditional controlCONTROL STRUCTURES CONDITIONAL CONTROLS Conditional Control Conditional control
Conditional Sentences Conditional Sentences Structure A conditional sentenceConditional Sentences Conditional Sentences Structure A conditional sentence
Lesson Conditional Statements Conditional Statement Defn A conditionalLesson Conditional Statements Conditional Statement Defn A conditional
Types of conditional sentences Zero conditional First conditionalTypes of conditional sentences Zero conditional First conditional
Conditional Indicative tense I Conditional Indicative The conditionalConditional Indicative tense I Conditional Indicative The conditional
CONDITIONAL S CONDITIONAL S We use conditional sentencesCONDITIONAL S CONDITIONAL S We use conditional sentences
CONDITIONAL SENTENCES ZERO CONDITIONAL The Zero Conditional isCONDITIONAL SENTENCES ZERO CONDITIONAL The Zero Conditional is
Lesson Conditional Statements Conditional Statement Defn A conditionalLesson Conditional Statements Conditional Statement Defn A conditional
CONDITIONAL SENTENCES DWS Conditional Sentences 1 Conditional sentencesCONDITIONAL SENTENCES DWS Conditional Sentences 1 Conditional sentences