├── Artefact └── .gitkeep ├── Authoring_Concepts ├── c_About_the_Style_Guide.dita ├── c_Acknowledgements.dita ├── c_Challenges_for_New_DITA_Authors.dita ├── c_Conditions_Filtering_Variants_and_ditaval.dita ├── c_Constraints.dita ├── c_Content_or_Form.dita ├── c_DITA_Features.dita ├── c_Distinction_between_Format_and_Style.dita ├── c_Generalisation.dita ├── c_Information_Types.dita ├── c_Inheritance.dita ├── c_Introduction_to_DITA.dita ├── c_Introduction_to_the_Separation_of_Content.dita ├── c_Minimalism.dita ├── c_Modularity.dita ├── c_OASIS_and_the_DITA_TC.dita ├── c_Role_of_Best_Practice_Guide.dita ├── c_Specialisation.dita ├── c_Techniques.dita ├── c_The_A_in_DITA.dita ├── c_The_History_of_DITA.dita ├── c_Topic_Based_Authoring.dita ├── c_Use_of_Class_Attribute.dita ├── c_What_is_Structured_Authoring.dita ├── c_Where_DITA_Fits_In.dita ├── obsolete_c_A_Definition_of_DITA.dita ├── obsolete_c_Design_Patterns.dita └── obsolete_c_The_Style_Guide_Cascade.dita ├── Content_Reuse ├── c_Advanced_conref_Principles.dita ├── c_Conref_Element_Must_Be_Valid.dita ├── c_Conref_Push.dita ├── c_Conref_of_Siblings.dita ├── c_Content_Reference.dita ├── c_Content_Reuse_Definition.dita ├── c_Embedded_Topics.dita ├── c_Indirect_Content_Referencing.dita ├── c_Management_of_conrefs.dita ├── c_Nested_Conrefs.dita ├── c_Organising_Reuse_Elements.dita ├── c_Organising_Variables.dita ├── c_Re-use_Guidelines.dita ├── c_Re-use_Practices.dita ├── c_Reuse_Maturity_Model.dita ├── c_Reusing_Content_in_Different_Element.dita ├── c_Using_Entities_for_Variables.dita ├── c_Variables.dita ├── c_Variables_Using_keydef.dita ├── c_Variables_in_DITA.dita ├── c_Writing_For_Reuse.dita ├── c_dita_use_conref_target_Value.dita ├── c_where_to_store_conref_targets.dita ├── obsolete_c_Linking_Dangers_with_Content_Reuse.dita ├── obsolete_c_Reuse_Matrix.dita ├── obsolete_c_Transclusion.dita └── winant_generated_ditamap.ditamap ├── Cross_Referencing ├── c_Avoiding_Cross_References.dita ├── c_Conditions_in_Cross_References.dita ├── c_Controlling_Related_Links.dita ├── c_Cross-references_Sample_Topic.dita ├── c_Cross-referencing_Elements_in_a_Topic.dita ├── c_Cross-referencing_Topics_and_External_Resources.dita ├── c_Cross-referencing_a_Transcluded_Element.dita ├── c_Cross_References_in_Titles.dita ├── c_Cross_Referencing_Figures.dita ├── c_Cross_Referencing_Tables.dita ├── c_Indirection_with_keyref.dita ├── c_Links_to_Glossary_Terms.dita ├── c_Links_to_non-DITA_Resources.dita ├── c_Managing_Cross-references.dita ├── c_Referencing_Page_Number.dita ├── c_Referencing_Step_Numbers.dita ├── c_Referencing_ditamap.dita ├── c_Referencing_through_href_attribute.dita ├── c_Related_Links_Section.dita ├── c_Scope_Attribute.dita ├── c_Structure_of_related_links_Element.dita ├── c_The_desc_Element_in_Links.dita ├── c_The_importance_Attribute_and_Related_Links.dita ├── c_The_linkinfo_Element.dita ├── c_The_xref_Element.dita ├── c_Types_of_CrossReferences.dita └── obsolete_c_Unlinked_Text_in_Related_Links.dita ├── Documentation_Process ├── c_Avoiding_Special_Characters_in_File_Names.dita ├── c_Content_Management_Systems.dita ├── c_DITA_File_Extensions.dita ├── c_DITA_Publishing_Process.dita ├── c_File_Name_Case.dita ├── c_File_Naming_Conventions.dita ├── c_File_and_Folder_Structure.dita ├── c_Front_Matter_Page_Numbering.dita ├── c_Help2_from_DITA_Source.dita ├── c_Legacy_Content.dita ├── c_Pre_Publish_Review.dita ├── c_Restricting_Authors.dita ├── c_Selecting_File_Names.dita ├── c_Specialisation_Naming_Conventions.dita ├── c_Structured_Authoring_Process.dita ├── c_Working_in_a_Team.dita └── obsolete_c_Information_in_Multiple_Languages.dita ├── Graphics_and_Figures ├── Future_Topics │ └── c_Syntax_Diagrams.dita ├── c_Callouts.dita ├── c_Different_Graphics_for_Different_Outputs.dita ├── c_Figure_Titles.dita ├── c_Figures_Containing_Tables.dita ├── c_Figures_or_Images.dita ├── c_Image_Alignment_and_Placement.dita ├── c_Image_File_Management.dita ├── c_Image_File_Types.dita ├── c_Image_Maps_in_DITA.dita ├── c_Localising_Graphics.dita ├── c_Multimedia_in_Topics.dita ├── c_WAI_Compliance.dita ├── obsolete_c_Image_Map_Dilemma.dita ├── obsolete_c_Issues_with_Graphics.dita ├── obsolete_c_SVG_Tips.dita └── obsolete_c_Screen_Captures.dita ├── LICENSE ├── Language_and_Punctuation ├── c_Avoiding_Writing_for_Output.dita ├── c_Case_in_Titles.dita ├── c_Conditions_in_Titles.dita ├── c_Crafting_Paragraphs.dita ├── c_Glue_Text.dita ├── c_Line_Breaks_in_Titles.dita ├── c_Nested_Quotations.dita ├── c_Punctuation_in_Lists.dita ├── c_Quotation_Marks.dita ├── c_Stem_Sentences_in_Task_Topics.dita ├── c_Titles_and_Headings.dita ├── c_Transitional_Information_in_Prerequisites.dita ├── c_Varieties_of_English.dita ├── c_Where_Titles_Are_Used.dita ├── c_Writing_Meaningful_Titles.dita └── obsolete_c_Avoiding_Transitions_in_Topics.dita ├── Maps ├── c_Anatomy_of_ditamap.dita ├── c_Breadcrumbs.dita ├── c_Chunk_Attribute.dita ├── c_Collection_Type_Example_Choice.dita ├── c_Collection_Type_Example_Family.dita ├── c_Collection_Type_Example_Sequence.dita ├── c_Collection_Type_Example_Unordered.dita ├── c_Collection_Type_Examples.dita ├── c_Collection_Types.dita ├── c_Controlling_Default_Page.dita ├── c_DITA_Map_Files.dita ├── c_DITA_Map_Vocabulary.dita ├── c_Dangling_Topicrefs.dita ├── c_Embedded_Maps.dita ├── c_Excluding_Map_Topics_from_TOC.dita ├── c_Generated_Relationship_Links.dita ├── c_Hierarchical_Linking_Relationships.dita ├── c_Inheritance_in_ditamaps.dita ├── c_Labels_for_reltable_Links.dita ├── c_Link_Text_for_Relationship_Tables.dita ├── c_Linking_Attributes.dita ├── c_Linking_Relationships.dita ├── c_Nesting_bookmaps_Within_ditmaps.dita ├── c_Non-DITA_Topic_References.dita ├── c_Output_Styling.dita ├── c_Publication_Defined.dita ├── c_Relationship_Between_Hierarchy_and_reltable.dita ├── c_Sample_ditamap_File.dita ├── c_Sample_reltable.dita ├── c_Storing_Relationship_Table_Maps_Separately.dita ├── c_Structuring_a_TOC.dita ├── c_The_topicref_Element.dita ├── c_Topic_Based_Architecture_Needs_TOC.dita ├── c_Topic_Manifest.dita ├── c_Types_of_Relationship_Tables.dita ├── c_Understanding_Relationship_Tables.dita ├── c_Using_Topicheads_in_a_Map.dita ├── c_Working_with_Map_Files.dita ├── c_bookmap_application.dita ├── c_bookmap_example.dita ├── c_copy-to_Attribute.dita ├── c_glossref.dita ├── c_navref_Element.dita ├── c_topicref_href_attribute.dita ├── obsolete_c_Design_Patterns.dita ├── obsolete_c_Excluding_Topics_from_Output_TOC.dita ├── obsolete_c_External_topicrefs.dita ├── obsolete_c_Generated_Topic_Content.dita ├── obsolete_c_Many_ditamaps.dita ├── obsolete_c_Organising_Relationship_Tables.dita └── obsolete_c_The_scope_attribute.dita ├── Metadata_Conditional ├── c_Attributes_with_multiple_values.dita ├── c_Author_and_Publisher_Metadata.dita ├── c_Conditional_Processing_Concepts.dita ├── c_Conditional_Processing_Dangers.dita ├── c_Conditional_Processing_at_Topic_Level.dita ├── c_Controlled_Attribute_Values.dita ├── c_Conventions_for_otherprops.dita ├── c_Critical_Dates.dita ├── c_Filtering_Composite_Topics.dita ├── c_Filtering_and_Flagging.dita ├── c_Filtering_ditamaps.dita ├── c_Include_Exclude_Conditions.dita ├── c_Index_See_SeeAlso.dita ├── c_Indexing.dita ├── c_Limiting_Conditions.dita ├── c_Managing_Metadata.dita ├── c_Markup_Print_NonPrint_Metadata.dita ├── c_Nesting_Index_Entries.dita ├── c_Other_Metadata.dita ├── c_Placement_of_Index_Terms.dita ├── c_Re-using_Index_Entries.dita ├── c_Select_Attributes.dita ├── c_Styling_Issues_with_Conditions.dita ├── c_The_importance_Attribute.dita ├── c_The_outputclass_Attribute.dita ├── c_The_props_Attribute.dita ├── c_The_source_Element.dita ├── c_The_status_attribute.dita └── c_Transclusions_vs_Conditions.dita ├── README.md ├── Sample_Topics ├── t_Exemplar_-_Task_Topic.dita ├── t_Exemplar_-_Task_Topic_Configuring_Source_Addresses.dita └── t_mirage_engine_failure.dita ├── Syntax_and_Markup ├── c_Abstracts.dita ├── c_Apparently_Duplicate_Semantic_Elements.dita ├── c_Attaching_Data_to_Content.dita ├── c_Body_Elements.dita ├── c_Choice_Lists.dita ├── c_Choice_Tables.dita ├── c_Choosing_a_List_Type.dita ├── c_Code_Blocks.dita ├── c_Complex_Command_References.dita ├── c_Complex_Nested_Tasks.dita ├── c_Controlling_Enumeration_Type.dita ├── c_Controlling_Look-and-Feel_of_the_Output.dita ├── c_Dates.dita ├── c_Definition_Lists_vs_Tables.dita ├── c_Domain_Elements.dita ├── c_Footnotes.dita ├── c_Formatting_in_shortdesc.dita ├── c_Guidelines_for_Crafting_Short_Descriptions.dita ├── c_Hacks.dita ├── c_ID_Attributes.dita ├── c_Images_within_Steps.dita ├── c_Keeping_Connected_Blocks_Together.dita ├── c_Keystrokes.dita ├── c_Keywords.dita ├── c_Legal_Aspects_of_Trademarks.dita ├── c_Limiting_User_Interface_Buttons.dita ├── c_List_of_Domains.dita ├── c_Lists.dita ├── c_Lists_within_Paragraphs.dita ├── c_Making_shortdesc_Mandatory.dita ├── c_Map_Elements.dita ├── c_Mark-up_Concepts.dita ├── c_Marking_up_Mark-up_Languages.dita ├── c_Multiple_Titles_in_a_Section.dita ├── c_Nested_Tables.dita ├── c_Non_Breaking_Spaces.dita ├── c_Notes_in_Steps.dita ├── c_One_Steps_per_Topic.dita ├── c_Organisation_of_DITA_Elements.dita ├── c_Other_Domains.dita ├── c_Paragraphs.dita ├── c_Paragraphs_Inside_Tables.dita ├── c_Paragraphs_in_Reference_Topics.dita ├── c_Paragraphs_within_List_Items.dita ├── c_Paragraphs_within_Notes.dita ├── c_Parameter_Lists.dita ├── c_Parameter_or_Variable.dita ├── c_Phrases.dita ├── c_Phrases_and_Blocks.dita ├── c_Phrases_in_Different_Languages.dita ├── c_Poetry_Dialogue_Text_Fragments.dita ├── c_Procedures.dita ├── c_Program_Script_and_Routine_Names.dita ├── c_Programming_Domain.dita ├── c_Prolog_Elements.dita ├── c_Purpose_of_Short_Descriptions.dita ├── c_Required_Cleanup.dita ├── c_Required_and_Optional_Steps.dita ├── c_Row_Headers.dita ├── c_Semantics_in_Steps.dita ├── c_Sentence_Syntax_in_prereq.dita ├── c_Separating_Procedures_Into_Granular_Steps.dita ├── c_Short_Descriptions.dita ├── c_Short_Descriptions_in_ditamap.dita ├── c_Single_Step_Procedure.dita ├── c_Software_Domain.dita ├── c_Special_Characters_and_Dates.dita ├── c_Specialisation_Elements.dita ├── c_Steps_and_Steps_Informal.dita ├── c_Sub_Steps.dita ├── c_Tables.dita ├── c_The_coderef_Element.dita ├── c_The_command_Element.dita ├── c_The_systemoutput_Element.dita ├── c_The_text_Element.dita ├── c_Topic_Elements.dita ├── c_Topic_Preview_via_shortdesc.dita ├── c_Two_Tasks_on_One_Task_Topic.dita ├── c_Types_of_Tables.dita ├── c_Typographical_Domain.dita ├── c_Use_of_Class_Attribute.dita ├── c_User_Interface_Domain.dita ├── c_User_Interface_Text.dita ├── c_Utilities_Domain.dita ├── c_Working_with_Tables.dita ├── c_refcols_keycol.dita ├── duplicated_c_Phrases_and_Blocks.dita ├── obsolete_c_Semantics_of_Lists.dita ├── obsolete_c_Using_Term_Element_for_Definitions.dita ├── r_Typography_Domain_Elements.dita ├── r_Utilities_Domain_Elements.dita ├── r_metadata_domain_elements.dita ├── r_programming_domain_elements.dita ├── r_software_domain_elements.dita └── r_userinterface_domain_elements.dita ├── Topics_and_Information_Types ├── c_Avoiding_Hierarchy_in_Topics.dita ├── c_Avoiding_Links_in_Topics.dita ├── c_Concept.dita ├── c_Constraints_on_Specialisation.dita ├── c_Content_Models_and_Info_Types.dita ├── c_Difference_between_Processes_Procedures_and_Tasks.dita ├── c_Disambiguation_Topics.dita ├── c_General_Tasks.dita ├── c_Glossaries.dita ├── c_Granularity_One_File_per_Topic.dita ├── c_How_Chunking_Works.dita ├── c_How_Detailed_should_a_Topic_be.dita ├── c_Identifying_the_Information_Type.dita ├── c_Information_Types_Explained.dita ├── c_Official_Specialisations.dita ├── c_Reference.dita ├── c_Specialising_Information_Types.dita ├── c_Structuring_Reference_Data.dita ├── c_Stub_Topics.dita ├── c_Task.dita ├── c_To_Specialise.dita ├── c_Topic_Proto.dita ├── c_Types_of_Specialisation.dita ├── c_Using_Ditabase.dita ├── c_Using_sectiondiv_and_bodydiv_Elements.dita ├── c_What_is_a_Topic.dita ├── c_Working_with_Topics.dita ├── obsolete_c_Common_Specialisations.dita ├── obsolete_c_FAQ_Topics.dita ├── obsolete_c_Other_Approaches_to_Information_Types.dita ├── obsolete_c_Sample_Content_Model.dita ├── obsolete_c_Topic_Type_Specialisation.dita ├── obsolete_c_What_if_the_Content_Model_Does_Not_Fit.dita └── obsolete_c_Writing_Task_Topics.dita ├── artefact_collections.ditamap ├── artefact_concepts.ditamap ├── artefact_crossreferencing.ditamap ├── artefact_graphics.ditamap ├── artefact_infotypes.ditamap ├── artefact_introduction.ditamap ├── artefact_langref_reltable.ditamap ├── artefact_language.ditamap ├── artefact_metadata.ditamap ├── artefact_mstp_reltable.ditamap ├── artefact_process.ditamap ├── artefact_reuse.ditamap ├── artefact_syntax.ditamap ├── artefact_test.ditamap ├── c_Content_Re-use.dita ├── c_Conventions_(Not_Included_in_Output).dita ├── c_Cross-referencing.dita ├── c_DITA_Authoring_Concepts.dita ├── c_Language_and_Punctuation.dita ├── c_Syntax_and_Markup.dita ├── c_The_DITA_Publishing_Process.dita ├── c_Topics_and_Information_Types.dita ├── c_Types_of_Metadata.dita ├── c_Working_with_Graphics_and_Figures.dita ├── conref ├── c_Constraints_in_DITA_1_2.dita ├── conref_source.dita ├── conref_source_email.dita ├── conref_source_footnotes.dita ├── conref_source_index.ditamap ├── conref_source_metadata.dita ├── conref_source_references.dita ├── en-US_conref_source.dita ├── en-US_conref_source_metadata.dita └── temp.txt ├── ditastyle_oxygen.ditamap ├── foreword.dita └── images ├── BlockDiagram_DITA_within_XML.gif ├── BlockDiagram_DITA_within_XML.svg ├── BlockDiagram_DITA_within_XML.vsd ├── DITA_Workflow.gif ├── DITA_workflow.svg ├── ace.swf ├── bookmap_specialisation.svg ├── breadcrumbs.png ├── breadcrumbs.psp ├── callout_key_ej25_turbo.jpg ├── callout_text_ej25_turbo.jpg ├── choicetable_example.png ├── collection_links_html.gif ├── collection_links_pdf.gif ├── collection_type_choice.gif ├── collection_type_family.gif ├── collection_type_sequence.gif ├── collection_type_unordered.gif ├── conref_folder_structure.png ├── conref_organisation_table.png ├── content_form_example1.png ├── content_form_example2.png ├── content_form_example3.png ├── darwin.jpg ├── darwin_library_of_congress.jpg ├── design_patterns_1.gif ├── design_patterns_2.gif ├── design_patterns_3.gif ├── dl_vs_table.png ├── eclipse_help_map_structure.png ├── ej25_turbo_engine_WRX.jpg ├── embedded_maps.gif ├── evolution.gif ├── evolution.png ├── evolution.svg ├── evolution.vsd ├── figure_example_result.png ├── generated_links_example.png ├── generated_links_example1.gif ├── html_help_map_structure.png ├── hughes_stub_topic_example1.jpg ├── hughes_stub_topic_example2.jpg ├── index_multilevel.png ├── index_seealso.png ├── indirection_schematic.png ├── indirection_schematic.svg ├── indirection_schematic.vsd ├── info_type_content_model.gif ├── info_type_content_model.png ├── info_type_content_model.svg ├── info_type_specialisation.gif ├── info_type_specialisation.svg ├── information_types.vsd ├── information_types_dita_1_2.svg ├── information_types_taskmodel.svg ├── list_types_1.png ├── nested_conref_schematic.svg ├── nested_conref_schematic.vsd ├── network_address.png ├── note_in_step_rendered.png ├── parallel_vs_embedded_lists.png ├── parallel_vs_embedded_lists.vsd ├── prereq_required_links.png ├── process_levels_idoinfotech-com.jpg ├── process_levels_idoinfotech-com.png ├── processes_vs_procedures.vsd ├── processes_vs_procedures_1.png ├── processes_vs_procedures_1.svg ├── restricting_tags_xmetal.png ├── sample_button.png ├── screen_capture_field_example.png ├── shortdesc_example1.png ├── shortdesc_example2.png ├── shortdesc_example3.png ├── sl_vs_ul.png ├── sl_vs_ul.png.bak ├── specialisation_schematic.gif ├── specialisation_schematic.svg ├── step_importance_attribute_rendered.png ├── stub_topic_example.png ├── style_guide_cascade.jpg ├── task_topic_steps_structure.png ├── task_topic_steps_structure_rendered.png ├── test.svg ├── title_usage.png ├── toc_example.gif ├── xsl_in_publishing.bak.svg ├── xsl_in_publishing.svg ├── xsl_in_publishing.vsd └── ~$$parallel_vs_embedded_lists.~vsd /Artefact/.gitkeep: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /Authoring_Concepts/c_DITA_Features.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | DITA features 5 | DITA incorporates features designed to improve the quality and 6 | efficiency of documentation. 7 | 8 | Tony 9 | SelfDITAfeatures 10 | 11 | 12 |

DITA's features include: 13 |

47 |

48 |
49 |
50 | -------------------------------------------------------------------------------- /Authoring_Concepts/c_Information_Types.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | Information typing 6 | Information typing is a methodology which underpins 7 | DITA. Information is structured by topics with content models appropriate to 8 | the nature of the content. The three base DITA information types are concept, 9 | task and reference. 10 | 11 | information 13 | types 14 | 15 | 16 |

18 |

19 |

Information typing is also used in other methodologies such as 20 | . 22 |

23 |
24 |
25 | -------------------------------------------------------------------------------- /Authoring_Concepts/c_Modularity.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Modularity 5 | DITA enables modular document development. Not only can topics be 6 | re-used, but any group of topics or elements can be treated as a modular 7 | document component. 8 | 9 | Tony 10 | Selfmodulardocumentsarchitecturemodularassemblycontent 11 | assemblytopic-based 12 | authoring 13 | 14 | 15 |

Modularity is the technique of building large complex things in smaller, 16 | self-contained pieces. Modular furniture is a good example of modularity in 17 | practice. Instead of being one large piece, a modular couch may be four pieces 18 | that can be arranged in different ways to form different couch configurations. 19 |

20 |

Creation of a manual can also be 21 | . 23 | Instead of being constructed as one piece, a large manual may be designed as a 24 | collection of different modules, and those modules can be arranged into 25 | different configurations to create different manuals. Modular manuals are 26 | easier to maintain, and can be produced more efficiently. A ditamap referencing 27 | a group of topics can be embedded within another ditamap, just as a set of 28 | elements within a single topic can be re-used in many different topics. 29 |

30 |

XML technologies (such as 31 | XPath) make modularity technically easy to implement. DITA 32 | can take advantage of such complementary XML technologies. 33 |

34 |
35 |
36 | -------------------------------------------------------------------------------- /Authoring_Concepts/c_The_A_in_DITA.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | The A in DITA 5 | DITA provides a standardised architectural framework for creating 6 | and maintaining content. 7 | 8 | Tony 9 | Selfarchitectureopen 10 | standardinformation 11 | architectureRockley, Manning, et 12 | al 13 | 14 | 15 |

DITA can be described as an approach to information architecture. That's 16 | why there's an A for Architecture in DITA! 17 |

18 |

A great definition of architecture in the DITA context can be found in 19 | the book 20 | DITA 101: 21 | An open 22 | content standard that defines a common structure for content that promotes the 23 | consistent creation, sharing, and re-use of content. 24 | 25 |

26 |

This definition is great because it highlights the facts that: 27 |

37 |

38 |
39 |
40 | -------------------------------------------------------------------------------- /Authoring_Concepts/c_Use_of_Class_Attribute.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Use of Class Attribute 5 | The class attribute in DITA is not analogous to the class element 6 | in HTML. DITA's class element is used for specialisation, and should not be set 7 | by authors. 8 | 9 | Tony 10 | Selfclassattributesclassoutputclassspecialisationinheritance 11 | 12 | 13 |

All DITA elements have a 14 | class attribute, but as a DITA author, you should never 15 | change this attribute. In fact, most DITA editors will hide it from you. The 16 | DITA 17 | class attribute is not the same as the HTML 18 | class attribute. (DITA's 19 | outputclass attribute is the closest match to HTML 20 | class.) 21 |

22 |

All DITA based processors use the 23 | class attribute to determine how an element should be 24 | processed, rather than by using the element name itself. This is because 25 | specialisation may make the element name unfamiliar to the processor, but the 26 | class will indicate the element's inheritance, and therefore how it should be 27 | handled. 28 |

29 |
30 |
31 | -------------------------------------------------------------------------------- /Authoring_Concepts/c_Where_DITA_Fits_In.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Where DITA fits... 5 | DITA is technically defined as an XML application, and is 6 | therefore built on XML language standards. XML itself is based on other 7 | character representation rules. DITA can also be used in conjunction with 8 | related standards and technologies. 9 | 10 | XHTMLXMLS1000DDocBookSGMLUnicodebase 12 | content modelDITADITAframework 14 | 15 | 16 | 17 | DITA in relation to other standards and technologies 18 | Diagram: 19 | ComTech/Quadralay Presentation (Webinar), Jen Linton and Andrew 20 | VanConas 21 | 24 | 25 | Block diagram showing where DITA fits in a world of standards and 26 | technologies 27 | 28 | 29 | 30 | 31 | -------------------------------------------------------------------------------- /Authoring_Concepts/obsolete_c_A_Definition_of_DITA.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | A Definition of DITA 5 | DITA can be defined an open standard for creating, sharing and 6 | re-using content. 7 | 8 | Tony 9 | SelfDITAdefinitionRockley, 10 | Manning, et al 11 | 12 | 13 |

Just as they provided a good definition of what architecture means in 14 | the DITA context, 15 | Rockley, Manning et al follow up with a lovely, succinct 16 | definition of DITA. 17 |

18 | DITA is an open content 19 | standard that defines a common structure for content that promotes the 20 | consistent creation, sharing, and reuse of content. 21 | 22 |
23 |
24 | -------------------------------------------------------------------------------- /Content_Reuse/c_Advanced_conref_Principles.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Advanced conref principles 5 | 6 |

The features and capabilities of content referencing was extended in 7 | DITA 1.2, making it possible to conref multiple elements at the one time, to 8 | indirectly reference content, and to 9 | push content from the source element. 10 |

11 |
12 |
13 | -------------------------------------------------------------------------------- /Content_Reuse/c_Organising_Reuse_Elements.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | <ph 5 | conref="../../conref/conref_source.dita#topic_E1642C5A86C44BCE86FECD98EBAA3C89/var_Organising_InitCap"><?xm-replace_text Phrase?></ph> 6 | re-use topics and elements 7 | 8 |

Re-use of content is easier for the author to accomplish if the elements 9 | to be re-used are carefully 10 | 12 | in predictable locations. 13 |

14 |
15 |
16 | -------------------------------------------------------------------------------- /Content_Reuse/c_Re-use_Practices.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Re-use practices 6 | 7 |

To best take advantage of content re-use, you should adopt practices to 8 | reduce the impediments, increase the opportunities for re-use, and to make the 9 | process of re-using easier. 10 |

11 |
12 |
13 | -------------------------------------------------------------------------------- /Content_Reuse/c_Variables.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Variables 6 | 7 |

Variables are often used phrases (such as product names) 8 | that are re-used by replacing the value of the variable at the time the 9 | information is published. 10 |

11 |
12 |
13 | -------------------------------------------------------------------------------- /Content_Reuse/obsolete_c_Linking_Dangers_with_Content_Reuse.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Problems with links in re-used content 5 | 6 |

There is a danger in including links (xref elements) 7 | within the text of a topic. This potential problem did not exist in many 8 | earlier authoring environments. But with comprehensive content re-use, the 9 | eventual context of a topic is unknown to the author. Including a link creates 10 | a dependency on the link target. If the source topic is used in a collection 11 | (or information set) that does not include the target, the link will be broken. 12 | 13 |

14 |

The solution to this problem in DITA is map-based linking. Links can be 15 | automatically generated at the bottom of each topic, with the links based on 16 | either the structure of the hierarchy of 17 | topicrefs in the ditamap, or instructions in a 18 | relationship table in the map. 19 |

20 |
21 |
22 | -------------------------------------------------------------------------------- /Content_Reuse/obsolete_c_Transclusion.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Transclusion 5 | 6 |

An old OASIS News story from 2002, titled 7 | The Holy Grail of Content Reuse: IBM's DITA XML, 8 | summarises conrefs well, and also introduces 9 | the idea of 10 | transclusion. 11 |

12 | 13 |

DITA design focuses upon the "topic" as a conceptual unit of 14 | authoring. Larger documents can be created by aggregating topic units. A 15 | "content referencing" (conref) mechanism may be used at the mark-up level to 16 | combine several topics into a single document, or to share content among 17 | topics. 18 |

19 |

The DITA design has a unified content reuse mechanism by which an 20 | element can replace itself with the content of a like element elsewhere, either 21 | in the current topic or in a separate topic that shares the same content 22 | models. The distinction between reusable content and reusing content, which is 23 | enshrined in the file entity scheme, disappears: Any element with an ID, in any 24 | DITA topic, is reusable by conref. 25 |

26 |

DITA's conref 'transclusion' mechanism is similar to the SGML conref 27 | mechanism, which uses an empty element as a reference to a complete element 28 | elsewhere. However, DITA requires that at least a minimal content model for the 29 | referencing element be present, and performs checks during processing to ensure 30 | that the replacement element is valid in its new context. This mechanism goes 31 | beyond standard XInclude, in that content can be incorporated only when it is 32 | equivalent: If there is a mismatch between the reusing and reused element 33 | types, the conref is not resolved. It also goes beyond standard entity reuse, 34 | in that it allows the reused content to be in a valid XML file with a DTD. The 35 | net result is that reused content gets validated at authoring time, rather than 36 | at reuse time, catching problems at their source. 37 |

38 |
39 |
40 |
41 | -------------------------------------------------------------------------------- /Content_Reuse/winant_generated_ditamap.ditamap: -------------------------------------------------------------------------------- 1 |  2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | -------------------------------------------------------------------------------- /Cross_Referencing/c_Cross-referencing_Elements_in_a_Topic.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Cross-referencing elements in a topic 6 | Cross-references to elements within topics such as figures and 7 | tables allow a reader to easily navigate through a document, whether it is in a 8 | page layout format or a hypertext format. The 9 | xref element is always used for cross-referencing elements 10 | within a topic. 11 | 12 | 13 | 14 | 15 | -------------------------------------------------------------------------------- /Cross_Referencing/c_Cross-referencing_Topics_and_External_Resources.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | Cross-referencing topics and external resources 6 | Cross-references are commonly made to other DITA topics in a 7 | collection, and to information resources outside the collection. These external 8 | targets can be any type of electronic resource that can be addressed through a 9 | URI, including e-mail addresses, documents on a network file server, and Web 10 | content. 11 | 12 | 13 | 14 | 15 | -------------------------------------------------------------------------------- /Cross_Referencing/c_Cross_References_in_Titles.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Cross-references in titles 5 | You should not use cross-reference elements within topic titles. 6 | 7 | Tony 8 | Selfcross-referencesin 9 | titletitle 10 | elementelementstitlexreftopic 11 | titleexemplartip 12 | 13 | 14 |

The 15 | title element cannot directly contain an 16 | xref element, primarily because titles are used in many 17 | different presentational contexts, some of which do not support child elements. 18 | For example, the 19 | title element of a DITA topic may become the 20 | title element in the 21 | head section of an output XHTML file, which must be plain 22 | text. Likewise, the title element of a DITA topic may be used as the basis for 23 | link text in its parent topic. 24 |

25 |

Including child elements in titles therefore reduces the opportunities 26 | for re-use, increases the risk of a transformation error caused by 27 | mis-interpretation of the mark-up, and complicates what should be a simple 28 | semantic element. 29 |

30 |

However, it 31 | is technically possible to embed 32 | xref or other child elements within a 33 | title element by nesting them within an (allowed) 34 | ph element. While the 35 | title element cannot contain 36 | xref elements, it 37 | can contain 38 | ph elements, and 39 | ph elements can contain 40 | xref elements. 41 |

42 | Carefully weigh up the implications before using this 43 | workaround. 44 | 45 |
46 |
47 | -------------------------------------------------------------------------------- /Cross_Referencing/c_Managing_Cross-references.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Managing cross-references 6 | 7 | 8 | 9 |

10 |

11 |
12 |
13 | -------------------------------------------------------------------------------- /Cross_Referencing/c_Scope_Attribute.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Linking in a new window 5 | The 6 | scope attribute of the cross-reference (xref) 7 | is used to nominate whether the target topic, file or other resource is 8 | external to the DITA source topics. Some publishing tools (such as the DITA 9 | Open Toolkit) will generate cross-references with an 10 | external scope attribute as hyperlinks that will 11 | open the target in a new window. 12 | 13 | Tony Selfxref 14 | elementelementsxrefscope 15 | attributeattributesscopecross-referenceswindowsopen 16 | link targets in 17 | newlinks 18 | 19 | 20 |

If a topic being referenced in an 21 | xref is external to the document content, the 22 | xref element's 23 | scope attribute should be set to 24 | external to semantically identify this 25 | relationship. 26 |

27 |

If you want a cross-referenced Web or external 28 | resource to open in a new window, code the 29 | xref as in the example: 30 | <xref href="..../somefile.html" format="html" scope="external" /> 31 |

32 | Opening external target resources in a new window is a processing 33 | function, and is therefore dependent upon the publishing tool used and its 34 | configuration. This 35 | 37 | is not part of the DITA standard itself. 38 | 39 |
40 |
41 | -------------------------------------------------------------------------------- /Cross_Referencing/c_The_desc_Element_in_Links.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | The 6 | <synph>desc</synph> element in links 7 | Descriptive metadata can be added to 8 | link elements in the 9 | related-links section. 10 | 11 | Tony Selfdesc 12 | elementrelated-links 13 | elementsdescelementsdesclink 14 | 15 | 16 |

The 17 | desc element inside the 18 | link element holds a description of the link target. The 19 | desc content is not rendered as content, but will 20 | typically appear as tooltip text in online outputs. 21 |

22 |
23 |
24 | -------------------------------------------------------------------------------- /Cross_Referencing/c_The_importance_Attribute_and_Related_Links.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | The 6 | <synph>importance</synph> attribute and related links 7 | Setting the 8 | importance attribute of a 9 | link element in the 10 | related-links section in a task topic to 11 | will result in the link appearing in the 12 | pre-requisites section of the topic. 13 | 14 | Tony 15 | Selfattributesimportanceimportance 16 | attributeelementsprereqprereq 17 | element 18 | 19 | 20 |

When writing a task topic, you will often include a pre-requisites 21 | (prereq) element. In some cases, pre-requisites for the task 22 | will include other procedures, described in separate topics. Logically, these 23 | pre-requisite task topics should be linked to in the 24 | prereq block. 25 |

26 |

Rather than including a link to an associated topic in an 27 | xref element in the 28 | prereq block, you should create a 29 | link element in the 30 | related-links section, and then set the 31 | importance attribute of the 32 | link element to 33 | . In typical output processing, this will result 34 | in the link being rendered at the end of the 35 | prereq block. 36 |

37 |
38 |
39 | -------------------------------------------------------------------------------- /Cross_Referencing/c_The_linkinfo_Element.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | The 5 | <synph>linkinfo</synph> element 6 | The 7 | linkinfo element can be used to add a block of descriptive 8 | text to a link list. 9 | 10 | Tony Selflinkinfo 11 | elementelementslinkinfolinklistrelated-links 12 | elementslinkinfo 13 | 14 | 15 |

The 16 | linkinfo element can be used within the ordered link list 17 | (linklist) element to provide an explanation of the purpose of 18 | the list of links. The 19 | linkinfo block typically appears after the list of links 20 | in the output reading format. 21 |

22 |

When used in conjunction with a 23 | title element also within the 24 | linklist, you can create a brief description of a process 25 | in the 26 | related-links section. However, you should always prefer 27 | creating small task topics, or stub topics with generated links to 28 | child tasks. 29 |

30 |

31 | Maybe add example? 32 | 33 |

34 |
35 |
36 | -------------------------------------------------------------------------------- /Cross_Referencing/obsolete_c_Unlinked_Text_in_Related_Links.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Unlinked Text in Links 6 | 7 | 8 | 9 |

Do not include any unlinked text in the related links 10 | linklist element; it should contain only 11 | link elements. 12 |

13 |

14 | The schema prevents this anyway? Furphy? 15 | 16 | This topic was Related Links Groups 17 | 18 |

19 |
21 | Rationale 22 |

Answering a question about whether additional text is allowed within 23 | the 24 | link element but outside the child 25 | linktext element: 26 |

27 | 29 |

Having text like that plays havoc with localization anyway, so it 30 | was just too much trouble to even try. 31 |

32 |

Go with relationship tables. Remember that you can use multiple 33 | relationship tables, if that makes them easier for you to work with. 34 |

35 |
36 |
37 |
38 |
39 | -------------------------------------------------------------------------------- /Documentation_Process/c_File_Naming_Conventions.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | File and folder naming conventions 5 | Using an 6 | , 8 | well-documented file naming and folder structure convention will improve the 9 | usability of the authoring process for DITA authors, especially those working 10 | in a team. 11 | 12 | file 14 | namingconventionsfolder 15 | namesdirectory names 16 | 17 | 18 |

Use descriptive folder and file names. Use 19 | .dita as the file extension for topic files, and 20 | .ditamap for ditamap files. File names are 21 | case-sensitive, and lower case file names are preferred. Prefix topic names 22 | with a letter corresponding to their information type. 23 |

24 |
25 |
26 | -------------------------------------------------------------------------------- /Documentation_Process/c_Help2_from_DITA_Source.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Microsoft Help 2 from DITA Source 5 | 6 |

If you need to create Microsoft Visual Studio Help 2 output, the best 7 | approach is to create an HTML Help (.chm) file through the DITA Open Toolkit 8 | normally, and then use a tool such as HelpWare FAR to convert the .chm file to 9 | .hxs format. 10 |

11 |

13 | 14 |

15 |
16 |
17 | -------------------------------------------------------------------------------- /Documentation_Process/c_Legacy_Content.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Legacy Content 6 | 7 | 8 | legacy 9 | content 10 | 11 | 12 |

13 |

14 |
16 | Rationale 17 |

Referring to the US Government's 18 | Open Government Directive: 19 | 21 | 22 |

    23 |
  • Firstly, all Web 24 | content must be analyzed to discover what content the agency has and where it 25 | is stored. 26 |
  • 27 |
  • Secondly, it must be 28 | enhanced to improve on the condition of the content 29 |
  • 30 |
  • Thirdly, it must be 31 | standardized to ensure content can be re-used 32 |
  • 33 |
  • Fourthly, it needs to 34 | be findable, by being located within the Information Architecture in a suitable 35 | repository 36 |
  • 37 |
  • And lastly, it needs 38 | to be monitored and maintained in real time against the organization's quality 39 | policies to ensure the quality standards that have been established continue to 40 | be met 41 |
  • 42 |
43 | 44 |

45 |
46 |
47 |
48 | -------------------------------------------------------------------------------- /Documentation_Process/c_Structured_Authoring_Process.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Structured authoring documentation stages 5 | The documentation process within a DITA workflow can be separated 6 | into stages of building, associating, and publishing. 7 | 8 | Tony 9 | Selfdocumentation 10 | processstages of the documentation 11 | process 12 | 13 | 14 |

The process of creating, producing and delivering a document in DITA's 15 | modular, structured authoring environment can be divided into three different 16 | stages: 17 |

18 | 19 |
Building 20 |
21 |
Building is the authoring process, normally undertaken by a writer. 22 | 23 |
24 |
25 | 26 |
Associating 27 |
28 |
Associating is the drawing together of the topics into collections 29 | (such as books and Web sites), normally undertaken by the 30 | information architects. A bundle of independent topics 31 | only becomes a book when the topics are associated, or linked, to each other 32 | through the ditamap. 33 |
34 |
35 | 36 |
Publishing 37 |
38 |
Publishing is the generation of the output collections of topics. 39 | The output might be a Word document, a PDF document, a CHM file, a collection 40 | of HTML files, or even a collection of XML files. 41 |
42 |
43 |
44 |

45 | Building and associating are independent, and are not 46 | sequential stages. 47 | 48 |
49 |
50 | -------------------------------------------------------------------------------- /Documentation_Process/c_Working_in_a_Team.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Unit testing in a team 5 | A process where multiple authors are working on a large repository 6 | of topics can make it difficult to manage the quality and consistency of the 7 | content. 8 | Unit testing is a technique to identify validation errors 9 | earlier in the documentation process. 10 | 11 | Tony Selfunit 12 | testingteamdocumentation 13 | processworking in a 14 | team 15 | 16 | 17 |

When a team of authors is working on the same collection of topics, 18 | particularly when the collection is very large, it is sometimes difficult to 19 | identify a problem with the build. For example, a topic referenced in the 20 | master ditamap may be invalid; finding that invalid topic in 21 | a large collection will be difficult. 22 |

23 |

Some information architects provide each author with a ditamap of that 24 | author's topics. Before the author submits the final set of topics, the ditamap 25 | must successfully and cleanly build as a unit. The author's ditamap can be 26 | discarded after testing if it is not otherwise used for publishing. 27 |

28 |

This unit testing approach allows any issues to be addressed in a 29 | smaller, quicker to build, environment. 30 |

31 |
32 |
33 | -------------------------------------------------------------------------------- /Graphics_and_Figures/Future_Topics/c_Syntax_Diagrams.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Syntax Diagrams 6 | 7 | 8 | 9 |

10 | 11 | 12 | Syntax Diagram of some 13 | sortkeyword=(a*b) 14 | First bracket is sep, closing is delim 15 | 16 | 17 | 18 |

19 |
21 | Rationale 22 |

http://wiki.oasis-open.org/dita/SyntaxDiagram 23 |

24 |
25 |
26 |
27 | -------------------------------------------------------------------------------- /Graphics_and_Figures/obsolete_c_Image_Map_Dilemma.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | Image Map Dilemma

Image maps can be defined in DITA, but rather than being content, image maps contain presentational information. (In theory, DITA should only contain content, and not any presentational form information.)

-------------------------------------------------------------------------------- /Graphics_and_Figures/obsolete_c_SVG_Tips.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | SVG Tips

Make sure you SVG editor is fully W3C SVG compliant. You will have fewer problems in Inkscape (an open source dedicated SVG editor) than you might have in a commercial tool such as Illustrator. Microsoft Visio also seems to provide compliant SVG output.

You should also try to draw your images in the size in which you wish to render the in the output.

-------------------------------------------------------------------------------- /Graphics_and_Figures/obsolete_c_Screen_Captures.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | Screen Captures

Refer to http://www.thecontentwrangler.com/article/do_screen_captures_still_makes_sense/

Summary:

  1. Ask yourself, will users still be successful in performing their intended task and find the information useful, without the presence of one or more screen captures? Do one of the following:
    1. If yes to #1, do not include the screen capture(s).
    2. If no to #1, make improvements to the surrounding prose (and possibly the application UI). Then proceed to #1
-------------------------------------------------------------------------------- /Language_and_Punctuation/c_Avoiding_Writing_for_Output.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Avoiding writing for output 5 | Do not include formatting information in your DITA content topics. 6 | 7 | 8 | Tony Selfseparation 9 | of content and 10 | formagnosticpresentation 11 | 12 | 13 |

If you find that you are deliberately coding your DITA topics in such a 14 | way as to achieve a particular output effect, you are without doubt taking the 15 | wrong path. DITA topics must be delivery-agnostic; they must be free of as much 16 | context (how the information is going to be used, presented or sequenced) as 17 | possible. 18 |

19 |
20 |
21 | -------------------------------------------------------------------------------- /Language_and_Punctuation/c_Line_Breaks_in_Titles.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Line breaks in titles 5 | There is no line break element or equivalent in DITA. 6 | 7 | Tony Selfline 8 | breaksseparation of content and 9 | formworkarounds 10 | 11 | 12 |

Line breaks are formatting constructs, so in general, DITA mark-up 13 | doesn't provide for them. However, it's not quite so clear cut. Despite working 14 | to the ideal that content should be separated from form, DITA does provide for 15 | a good deal of form mark-up. 16 |

17 |

Table column widths can be specified in DITA, even though that's form. 18 | Image sizes can be specified in DITA, and that too is form. 19 |

20 |

It is possible to use these loopholes in the separation of content and 21 | form to make possible things such as line breaks in titles. For example, a 22 | workaround is to place a one pixel by one pixel image within the title, and set 23 | the image element's placement attribute to break. This will cause, in most 24 | outputs, the title to be displayed with text before the image displayed on a 25 | different line to text following. 26 |

27 |

You must avoid the temptation to use such workarounds 28 | in an attempt to introduce form into DITA content. 29 |

30 |
31 |
32 | -------------------------------------------------------------------------------- /Language_and_Punctuation/obsolete_c_Avoiding_Transitions_in_Topics.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Avoiding Transitions in Topics 6 | 7 | 8 | 9 |

Avoid including transitional text in topics. 10 |

11 |

Transitional text is text that leads the reader to a following topic, or 12 | connects the topic to a previous topic. Examples of transitional text include: 13 | As we saw previously... and 14 | This processed is explained later.... In DITA, topics should be 15 | designed to be context-agnostic, so that a topic can be re-used in different 16 | publications or outputs, in different sequences. Transitional text reduces 17 | re-use opportunities. 18 |

19 |

20 | This could be merged with similar topics on glue text 21 | 22 |

23 |
24 |
25 | -------------------------------------------------------------------------------- /Maps/c_Breadcrumbs.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 6 | Breadcrumbs 7 | Breadcrumb trails are navigation tools used in some online 8 | document formats, and can be automatically generated from DITA source. 9 | 10 | Tony 11 | SelfbreadcrumbsnavigationEclipse 12 | Help 13 | 14 | 15 |

A feature of some document delivery formats, notably Eclipse Help, is 16 | the 17 | breadcrumb trail. 18 | Breadcrumbs provide the user with the position of the 19 | currently displayed topic in the TOC hierarchy through links to parent and 20 | other ancestor topics. 21 |

22 |

Breadcrumbs are derived entirely from the TOC structure, 23 | and do not need to be separately defined in the DITA source. 24 |

25 | 26 | TOC hierarchy used to derive breadcrumb trail in Eclipse Help 27 | output 30 | Screen capture showing how TOC hierarchy is used to create a 31 | breadcrumb trail at the top of a topic 32 | 33 | 34 |
35 |
36 | -------------------------------------------------------------------------------- /Maps/c_Collection_Type_Example_Choice.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Collection type example: 5 | <option>choice</option> 6 | 7 | 8 | Example of 9 | <option>choice</option> collection type 12 | Example of choice collection type 13 | 14 | 15 | 16 | 17 | -------------------------------------------------------------------------------- /Maps/c_Collection_Type_Example_Family.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Collection type example: 5 | <option>family</option> 6 | 7 | 8 | Example of 9 | <option>family</option> collection type 12 | Example of family collection type 13 | 14 | 15 | 16 | 17 | -------------------------------------------------------------------------------- /Maps/c_Collection_Type_Example_Sequence.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Collection type example: 5 | <option>sequence</option> 6 | 7 | 8 | Example of 9 | <option>sequence</option> collection type 12 | Example of sequence collection type 13 | 14 | 15 | 16 | 17 | -------------------------------------------------------------------------------- /Maps/c_Collection_Type_Example_Unordered.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Collection type example: 5 | <option>unordered</option> 6 | 7 | 8 | Example of 9 | <option>unordered</option> collection type 13 | Example of unordered collection type 14 | 15 | 16 | 17 | 18 | -------------------------------------------------------------------------------- /Maps/c_Collection_Type_Examples.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Collection type examples 5 | The effect of the 6 | collection-type attribute on the output publication is well 7 | illustrated with examples of the results of the use of different types. 8 | 9 | collection-type 10 | attributeexamplesgenerated 11 | linksexamplesreltableexamples 12 | of links 13 | 14 | 15 |
17 | Future enhancements 18 |

Change the examples in this group of topics to 19 | 21 | examples from subaru_repository.ditamap. 22 |

23 |
24 |
25 |
26 | -------------------------------------------------------------------------------- /Maps/c_DITA_Map_Files.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | DITA map files 5 | 6 | Hic sunt dracones (Here be dragons!) 8 | 9 | 10 | 11 | -------------------------------------------------------------------------------- /Maps/c_DITA_Map_Vocabulary.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | DITA map vocabulary 6 | 7 |

DITA includes a range of elements and attributes to manage references in 8 | ditamaps, and to govern the way the references are treated during the 9 | publishing process. 10 |

11 |
12 |
13 | -------------------------------------------------------------------------------- /Maps/c_Generated_Relationship_Links.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Generated relationship links 5 | Cross-reference links based on the relationships defined in the 6 | hierarchy and reltable sections of the ditamap can be automatically generated 7 | and added to the bottom of output topics, in both hypertext and paged media 8 | outputs. Most publishing tools support this DITA feature. 9 | 10 | Tony Selfgenerated 11 | linksautomatically-generated 12 | linksrelationship 13 | linksreltableexamplesgenerated 14 | relationship links 15 | 16 | 17 |

When a ditamap is 18 | processed (transformed into a reading format), particularly 19 | to a hypertext format, cross-referencing links can be automatically generated. 20 | For example, the samples following show some automatically generated related 21 | topics links. 22 |

23 | 24 | Generated links in HTML output 27 | Collection Links in HTML output 28 | 29 | 30 | 31 | Generated links in PDF output 34 | Collection links in PDF output 35 | 36 | 37 |
38 |
39 | -------------------------------------------------------------------------------- /Maps/c_Hierarchical_Linking_Relationships.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | Hierarchical linking relationships 6 | The hierarchical relationship of topic references in the ditamap 7 | can be used to generate links from parent topics to child topics, from child 8 | topics to parent topics, and between child topics. 9 | 10 | Tony 11 | Selfditamaphierarchygenerated 12 | linkslinksgenerated from 13 | ditamaphierarchical 14 | linksparent-child 15 | links 16 | 17 | 18 |

The hierarchy of topic references in the ditamap controls not only the 19 | sequence of topics in the output and/or the TOC, but also influences 20 | automatically-generated navigation links and generated summary content in 21 | parent topics in some output formats. 22 |

23 |

DITA permits you to adjust the basis on which the automatic navigation 24 | links are generated through the 25 | collection-type attribute of the 26 | topicref element. 27 |

28 |

Which collection type to use is dependent on the nature of the content. 29 | However, if in doubt, leave the default, which provides links to any child 30 | topics, and a link back from child to parent. This ensures that all topics in a 31 | hypertext output such as HTML can be traversed using links alone. 32 |

33 |
34 |
35 | -------------------------------------------------------------------------------- /Maps/c_Link_Text_for_Relationship_Tables.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Link text for 5 | <synph>reltable</synph> related topic links 6 | To control the text displayed in links automatically-generated 7 | from the relationship table, a 8 | linktext element must be added to the 9 | topicmeta for the 10 | topicref. 11 | 12 | Tony Selflinktext 13 | elementrelationship 14 | tablelinktextnavtitletopicmetaelementslinktextnavtitle 15 | attributeattributesnavtitle 16 | 17 | 18 |

By default, the link text used for generated links will be the title of 19 | the target topic. 20 |

21 |

If you want the link generated by a reltable to have a different title 22 | to the title of the linked topic itself, you may think the technique would be 23 | to use a 24 | navtitle attribute in the 25 | topicref element. However, that doesn't work! 26 |

27 |

The technique to use is to add a 28 | topicmeta element to the 29 | topicref, and include a 30 | linktext element containing the name of the link text. The 31 | following example shows the technique. 32 | 33 | <reltable> 34 | ... 35 | <topicref href="foo.xml"> 36 | <topicmeta> 37 | <linktext>Replacement text</linktext> 38 | </topicmeta> 39 | </topicref> 40 | ... 41 | </reltable> 42 |

43 |

44 | 45 | 46 | -------------------------------------------------------------------------------- /Maps/c_Linking_Relationships.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | Linking relationships 6 | DITA encourages the linking relationships to be stored outside the 7 | topic content. Links can be generated from topic hierarchies, relationship 8 | tables, and 9 | related-links section links. 10 | 11 | 12 | Tony Selflinking 13 | relationshipsrelationship 14 | tablecollection-type 15 | attributeattributescollection-typelinking 16 | 17 | 18 |

One of the most powerful features of DITA is the automatic generation of 19 | cross-reference links in the output. This feature allows greater content 20 | re-use, as it removes linking context from topics and moves it to the map. 21 |

22 |

Cross-reference links at the bottom of output topics are generated by 23 | hierarchical relationships defined in the ditamap, non-hierarchical 24 | relationships defined in the 25 | reltable section of the ditamap, and links defined in the 26 | related-topic section of the individual topic. 27 |

28 |

Of course, how links are generated will ultimately be up to the 29 | publishing engine you use. 30 |

31 |

The 32 | collection-type and 33 | linking attributes (of the topicref and relcell elements) 34 | allow you to fine-tune the way in which links are generated. 35 |

36 |
37 |
38 | -------------------------------------------------------------------------------- /Maps/c_Nesting_bookmaps_Within_ditmaps.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Nesting bookmaps within ditamaps 5 | For complex collection structures, only use bookmap at the top 6 | level. Any nested maps should be ditamaps. 7 | 8 | nested 9 | ditamapsmapsnestedbookmapmap 10 | structure 11 | 12 | 13 |

You should not nest bookmaps within ditamaps, as the 14 | structure will cause confusion for both processing software and for 15 | documentation authors. 16 |

17 |

If you need to re-use content from a bookmap inside a 18 | ditamap, then a lower-level ditamap should be nested in the bookmap, and that 19 | lower level ditamap re-used in the main ditamap. In fact, except for small 20 | documents, you should aim to have the top-level bookmap contain only map 21 | references, and no topic references. 22 |

23 |
25 | Rationale 26 | Now that 28 | <bookmap has been provided, my sense is that it should be thought of as 29 | hierarchically above <map>, and this usage of referencing <bookmap> 30 | from <map> should be prohibited or at least cautioned against, not least 31 | because of the issues you're raising. 32 | 33 |
34 |
35 |
36 | -------------------------------------------------------------------------------- /Maps/c_Output_Styling.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Heading levels and ditamaps 5 | The topic hierarchy in the ditamap is used to generate heading 6 | levels and styles in page layout outputs. 7 | 8 | Tony 9 | Selfheadingslevelsheadingsstylesstylesheadingtopic 10 | hierarchyheading 11 | styles 12 | 13 | 14 |

In DITA, each topic is written as a standalone chunk of content. The 15 | style in which a topic title, for example, is eventually presented to the user 16 | is determined by the position of the topic in the relevant ditamap. 17 |

18 |

For example, if a topic called 19 | About SD Cards is located at: 20 | Camera Model 700 > Storing Pictures > Memory > About SD Cardsthen its heading style in RTF output might be 21 | Heading 4. 22 |

23 |

If that same topic is re-used in a different ditamap, located at: 24 | Taking Pictures > Storing > About SD Cardsthen its heading style in RTF output might be 25 | Heading 3. The topic is identical, but its 26 | presentation is appropriate to the output context. 27 |

28 |

And it gets better! Topic titles can be different in different ditamaps. 29 | 30 |

31 |
32 |
33 | -------------------------------------------------------------------------------- /Maps/c_Sample_reltable.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Sample relationship table 5 | A sample relationship table illustrates how 6 | topicref elements are used within 7 | reltable, 8 | relrow, and 9 | relcell elements to create a matrix of linking relationships 10 | between the referenced topics. 11 | 12 | Tony 13 | Selfsamplesditamapreltableditamapsample 14 | codereltablesample 15 | codemap filesample 16 | coderelationship tablesample 17 | code 18 | 19 | 20 | <reltable> 21 | <relheader> 22 | <relcolspec type="concept"/> 23 | <relcolspec type="task"/> 24 | <relcolspec type="reference"/> 25 | </relheader> 26 | <relrow> 27 | <relcell> 28 | <topicref href="concepts/about_produce.dita"/> 29 | </relcell> 30 | <relcell> 31 | <topicref href="tasks/choosing_produce.dita"/> 32 | </relcell> 33 | <relcell> 34 | <topicref href="reference/produce.dita"/> 35 | </relcell> 36 | </relrow> 37 | <relrow> 38 | <relcell> 39 | <topicgroup collection-type="family"> 40 | <topicref href="concepts/about_cannedgoods.dita"/> 41 | <topicref href="concepts/about_foodstorage.dita"/> 42 | </topicgroup> 43 | </relcell> 44 | <relcell> 45 | <topicref href="tasks/buying_cannedgoods.dita"/> 46 | </relcell> 47 | <relcell> 48 | <topicref href="reference/cannedgoods.dita"/> 49 | </relcell> 50 | </relrow> 51 |

52 | Replace this with heather example 53 | 54 |

55 |
56 |
57 | -------------------------------------------------------------------------------- /Maps/c_Topic_Manifest.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | Topic manifest 6 | Any topics referenced anywhere in the ditamap will be processed 7 | into the output publication. 8 | 9 | Tony Selftopicref 10 | elementprint 11 | attributeattributesprintmanifestpicking 12 | listditamapmap 13 | 14 | 15 |

Topics to be included in the output are referenced through 16 | topicref elements in the ditamap. The 17 | topicref elements (and 18 | 20 | of 21 | topicref) are used both in the hierarchy and the 22 | relationship table sections of the map. If a ditamap includes an embedded map 23 | (a 24 | topicref referencing a ditamap rather than a DITA topic), 25 | then topics referenced by 26 | topicref elements in the embedded map will also be 27 | included in the output. 28 |

29 |

Simplistically, any topic referenced in the ditamap will be included in 30 | the output. An exception is for topics with the 31 | topicref element's 32 | print attribute set to 33 | ; these topics will not be included in page layout 34 | outputs (such as PDF). 35 |

36 |
37 |
38 | -------------------------------------------------------------------------------- /Maps/c_bookmap_example.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Sample bookmap file 5 | A sample bookmap illustrates how different semantic elements are 6 | arranged to form the structure of a conventional, printed book. 7 | 8 | Tony Selfsample 9 | bookmapbookmapsample 10 | codemap filesample 11 | code 12 | 13 | 14 | <bookmap id="taskbook"> 15 | <booktitle> 16 | <mainbooktitle>Product tasks</mainbooktitle> 17 | <booktitlealt>Tasks and what they do</booktitlealt> 18 | </booktitle> 19 | <bookmeta> 20 | <author>John Doe</author> 21 | <bookrights> 22 | <copyrfirst> 23 | <year>2006</year> 24 | </copyrfirst> 25 | <bookowner> 26 | <person href="janedoe.dita">Jane Doe</person> 27 | </bookowner> 28 | </bookrights> 29 | </bookmeta> 30 | <frontmatter> 31 | <preface/> 32 | </frontmatter> 33 | <chapter format="ditamap" href="installing.ditamap"/> 34 | <chapter href="configuring.dita"/> 35 | <chapter href="maintaining.dita"> 36 | <topicref href="maintainstorage.dita"/> 37 | <topicref href="maintainserver.dita"/> 38 | <topicref href="maintaindatabase.dita"/> 39 | </chapter> 40 | <appendix href="task_appendix.dita"/> 41 | </bookmap> 42 | 43 | 44 | -------------------------------------------------------------------------------- /Maps/obsolete_c_Excluding_Topics_from_Output_TOC.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | Excluding Topics from the Output Table of Contents

If a topic is to be included in the output file (eg, a CHM file) it must be nominated in the ditamap. The ditamap is used as the basis for the Table of Contents in many output types. To exclude a topic from the output table of contents, the relevant ditamap topicref must have its toc attribute set to no.

-------------------------------------------------------------------------------- /Maps/obsolete_c_Generated_Topic_Content.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Stub (or Summary) Topics with Generated Content 6 | 7 | 8 | 9 |

10 | Describe stub or disambiguation topics that use generated 11 | child topic short descriptions. Show how collection-type attribute affects the 12 | way these child topics are listed. Refer to Swinburne DITA strategy if 13 | necessary, or use the Collection Type Examples parent node from this Maps 14 | chapter. Screen captures of the different results would be useful. Perhaps move 15 | some content from discussion of 16 | shortdesc in the Exegesis. 17 | 18 | There is a reference to generated summary content in 19 | (stub) parent topics in Hierarchical Linking Relationships. 20 | 21 |

22 |
23 |
24 | -------------------------------------------------------------------------------- /Maps/obsolete_c_Many_ditamaps.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Many ditamaps for same content repository 5 | 6 | 7 | 8 |

Topic-level content reuse is simple to understand. 9 |

10 |

A ditamap is an ingredient list of a collection. More than one ditamap 11 | can reference the same topic. 12 |

13 |

So if you have a repository of DITA content topics covering how to use a 14 | range of cameras from the same manufacturer, we could create a ditamap for the 15 | Model 400 User Guide, another ditamap for the 16 | Model 700 User Guide, and another for the 17 | Model 700 Administrator's Guide. Some topics might be common 18 | to all ditamaps, while others might be unique to one. 19 |

20 |
21 |
22 | -------------------------------------------------------------------------------- /Maps/obsolete_c_Organising_Relationship_Tables.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | <ph xml:lang="en-AU">Organising</ph> Relationship Tables 6 | 7 | 8 | 9 |

10 | Talk about nesting relationship tables, and having 11 | multiple relationship tables. Also, storing reltables in separate maps from the 12 | hierarchy. Diagram would help. This might become an essay (probably not as big 13 | as a paper). 14 | 15 | Mention that in task-oriented documentation, the task 16 | should be the focal point for reltable design. The reltable can be started with 17 | a row for each task topic, and then concept and reference topicrefs added as 18 | required. 19 | 20 |

21 |
23 | Rationale 24 |

http://dita.xml.org/improving-relationships-relationship-tables 25 |

26 |
27 |
28 |
29 | -------------------------------------------------------------------------------- /Metadata_Conditional/c_Conditional_Processing_Dangers.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Conditional processing dangers 5 | Any filtering conditions that apply must still result in valid 6 | DITA mark-up. 7 | 8 | Tony 9 | Selffilteringconditional 10 | processingdangersWeb only 11 | contentprint only 12 | content 13 | 14 | 15 |

When using filtering in single-sourcing, you must be careful to ensure 16 | that a conditional processing rule doesn't result in invalid DITA. Filtering 17 | must not result in a required element being removed during processing. 18 |

19 |

For example, in the following snippet, if a condition of 20 | exclude web_only and exclude print_only was set, there would be no 21 | steps in the task, and the topic would be invalid. (The 22 | steps element requires at least one child 23 | step element.) 24 |

25 | 26 | <task id="myTopic"> 27 | <title>Making a Warranty Claim</title> 28 | <taskbody> 29 | <context>...</context> 30 | <steps> 31 | <step otherprops="web_only">...</step> 32 | <step otherprops="print_only">...</step> 33 | </steps> 34 | <result>...</result> 35 | </taskbody> 36 | </task> 37 |
38 |
39 | -------------------------------------------------------------------------------- /Metadata_Conditional/c_Conventions_for_otherprops.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Conventions for the 5 | <synph>otherprops</synph> attribute 6 | By using a convention for recording values in the 7 | otherprops attribute, you can extend the amount of metadata 8 | stored. 9 | 10 | Tony Selfotherprops 11 | attributemetadata 12 | attributesconventionsattributesotherpropsconventionsattributes 13 | 14 | 15 |

The 16 | otherprops attribute can be used for storing any other 17 | metadata information that does not otherwise fit into the standard condition 18 | attributes (audience, 19 | platform, and 20 | product). 21 |

22 |

To extend the functionality of the 23 | otherprops attribute, a naming convention can be used that 24 | a processor can interpret and action. For example, settings of 25 | otherprops="Market(Australia)" and 26 | otherprops="Publication(Symmetry)" would allow the same 27 | attribute to be used for a number of functions. In this example, a processor 28 | could differentiate between 29 | Market and 30 | Publication. 31 |

32 |
33 |
34 | -------------------------------------------------------------------------------- /Metadata_Conditional/c_Filtering_Composite_Topics.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Filtering composite (<term>ditabase</term>) topics 5 | Care must be taken when applying conditions to composite topics, 6 | as filtering a nested topic through the 7 | topicref element will not necessarily result in the topic 8 | being excluded. 9 | 10 | Tony 11 | Selfditabasecomposite 12 | topicsfilteringcomposite (ditabase) 13 | topicsconditional processingin 14 | composite (ditabase) topics 15 | 16 | 17 |

Although you should avoid the use of composite topics in any case, there 18 | are some complications when filtering such content. 19 |

20 |

If you have a ditamap 21 | topicref element with a condition attribute pointing to a 22 | topic within a composite topic file, then excluding elements with that 23 | attribute in the build process will not result in the (nested) topic being 24 | excluded from the output, unless that (nested) topic also has the condition 25 | attribute. The processor will include the entire composite topic if any topic 26 | within that composite topic is included in the published output. 27 |

28 |

Even if the chunking feature is used to split the composite DITA topic 29 | into multiple HTML topics, for example, the entire contents of the DITA topic 30 | will be output unless condition attributes are applied within the topic. 31 |

32 |
33 |
34 | -------------------------------------------------------------------------------- /Metadata_Conditional/c_Filtering_and_Flagging.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Filtering and flagging 6 | Content marked with metadata attributes can be conditionally 7 | processed so that the content is filtered (excluded) or flagged (highlighted) 8 | in the published output. 9 | 10 | 11 | 12 | 13 | -------------------------------------------------------------------------------- /Metadata_Conditional/c_Filtering_ditamaps.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | Filtering ditamaps 6 | When filtering a nested ditamap, you should apply the condition 7 | attribute to the reference (topicref or 8 | mapref element) to the nested ditamap, rather than to the 9 | map element. 10 | 11 | Tony Selfmapref 12 | elementtopicref elementmap 13 | elementconditional 14 | processingmetadata 15 | attributesselect 16 | attributescondition 17 | attributesfilteringditamapselementsmapmapreftopicref 18 | 19 | 20 |

It is possible in DITA, and often good practice, to have nested 21 | ditamaps. Although it does depend on circumstance, it is generally better 22 | practice to apply conditions to the 23 | topicref or 24 | mapref element, rather than the 25 | map element of the nested ditamap. 26 |

27 |

The reason for this, and a point that should always be considered when 28 | deciding on a filtering strategy, is the reduced processing load during 29 | generation of the output. If the processor has to read in a topic, or a nested 30 | map, only to find it's not needed in the current build because of the filtering 31 | metadata, it is an inefficient model. It is much better for the exclusion to be 32 | notified to the processor before having to load the file. 33 |

34 |
35 |
36 | -------------------------------------------------------------------------------- /Metadata_Conditional/c_Indexing.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Indexing 5 | DITA incorporates powerful features for indexing, including 6 | multi-level indexing, and 7 | see and 8 | see-also redirection. Index entries can be applied in the ditamap, 9 | in the topic prolog, and inline within the topic content. 10 | 11 | Tony 12 | Selfindexes 13 | 14 | 15 |

The indexing features in DITA are built around three elements: 16 | indexterm, 17 | index-see, and 18 | index-see-also. These elements can technically be placed 19 | at almost any point in the body of a topic, as well as in the topic 20 | prolog and in the 21 | topicmeta of the topicref in the ditamap. However, to 22 | avoid potential translation and processing complications, the elements should 23 | be deliberately placed in specific locations within the topic or map. 24 |

25 |
26 |
27 | -------------------------------------------------------------------------------- /Metadata_Conditional/c_Managing_Metadata.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Managing metadata elements and attributes 5 | The use of metadata elements and attributes may be best managed by 6 | a Content Management System. 7 | 8 | Tony 9 | SelfmetadatamanagingCMS 10 | 11 | 12 |

When working in a topic-based, modular architecture, where metadata 13 | plays a key role, one of the major challenges for authors is managing metadata. 14 | In this respect, 15 | managing metadata means such things as ensuring consistent 16 | metadata use, using metadata for retrieval of authoring topics, enforcing 17 | business metadata rules, and effective use of conditional metadata attributes. 18 | The most effective way of managing metadata is through a 19 | Content Management System (CMS). 20 |

21 |

If a 22 | CMS is not being used, you may find that recording metadata 23 | attribute values used in a collection inside a comments area within the ditamap 24 | XML code might be helpful. 25 |

26 |

There are some DITA software tools that provide some features that 27 | leverage metadata, such as reporting on attribute values in a collection. You 28 | may find these tools useful in supplementing your authoring tool features. Two 29 | such tools are 30 | DITAinformationcenter and 31 | WinANT Echidna. 32 |

33 |
34 |
35 | -------------------------------------------------------------------------------- /Metadata_Conditional/c_Other_Metadata.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Other metadata 6 | In addition to the select attributes, DITA content includes many 7 | forms of metadata. These metadata elements and attributes are used to manage 8 | and 9 | 11 | topics, ditamaps and publications. 12 | 13 | 14 | 15 | 16 | -------------------------------------------------------------------------------- /Metadata_Conditional/c_Styling_Issues_with_Conditions.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Styling Issues for Conditional Text 5 | 6 |

7 | This topic isn't really required; out of scope. 8 | 9 |

10 |
12 | Rationale 13 | 15 |

I'd suggest that our approach to style policies should consist of 16 | selectors and properties. In essence, a policy file should be able to attach 17 | any style or layout property (including an exclude or hide property) to any 18 | content fragment. The selectors should be CSS-like matches on inherited class, 19 | instance identifier, token value, or nesting of the above. The goal should be 20 | to put policy decisions in the hands of the broad audience that wouldn't be 21 | successful with XSLT. (Because XSLT is always available as a general fallback, 22 | style policies can provide a purely declarative set of selectors and properties 23 | rather than executable flow and expressions.) To produce books from bookmaps, 24 | the set of properties will need properties like page break and so on. A bit 25 | more on the thought: 26 | http://www.oasis-open.org/apps/org/workgroup/dita/email/archives/200409/msg00022.html 27 |

28 |

Paul's note below highlights the convergence of this approach with 29 | DITA conditional values, which also provide a system of selectors and 30 | properties. In a perfect world, existing DITA values files would remain valid 31 | instances of the more general style policies format. A transform might be 32 | acceptable. 33 |

34 |
35 |
36 |
37 |
38 | -------------------------------------------------------------------------------- /Metadata_Conditional/c_The_props_Attribute.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | The 6 | <synph>props</synph> attribute 7 | The 8 | props attribute is only used for 9 | 11 | new metadata attributes. 12 | 13 | Tony 14 | Selfattributespropsselect 15 | attributescondition 16 | attributesprops attribute 18 | 19 | 20 |

The 21 | props attribute is technically one of the select (or 22 | condition) attributes, designed for filtering and flagging during publishing. 23 | However, the 24 | props attribute is not intended to be used within a topic 25 | or document. It is provided to be used as the basis for 26 | 28 | condition attributes. 29 |

30 |

Do not use this attribute when authoring DITA topics 31 | or maps. 32 |

33 |
34 |
35 | -------------------------------------------------------------------------------- /Metadata_Conditional/c_The_source_Element.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | The 6 | <synph>source</synph> element 7 | When a topic is based on information from another resource, 8 | details of that related resource can be stored in the 9 | source metadata element in the topic 10 | prolog section. 11 | 12 | Tony SelfDublin Core Metadata Element 14 | Setsource 15 | elementDublin Core 16 | Metadataelementssourceattributeshrefhref 17 | attribute 18 | 19 | 20 |

The 21 | source element in the topic 22 | prolog section is used to nominate the name and/or 23 | location of information from which the topic was drawn or based. It is based on 24 | the Dublin Core Metadata Initiative 25 | property. The location of the resource is recorded 26 | in the 27 | source element's 28 | href attribute. 29 |

30 |

For example, if a topic was based on figures published in a Department 31 | of Transport report, the source element may be coded as: 32 | <source href="http://www.transport.gov.au/design/adr_online.aspx"> 33 | Australian Design Rules 34 | </source> 35 |

36 |

When published to an HTML-based output format, the address in the 37 | href attribute of the 38 | source element are included in the Dublin Core 39 | DC.source metadata in the head section of the HTML page. 40 |

41 |
42 |
43 | -------------------------------------------------------------------------------- /Metadata_Conditional/c_The_status_attribute.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | The 6 | <synph>status</synph> attribute 7 | The position of a topic or content element in the development life 8 | cycle is recorded in the 9 | status attribute. 10 | 11 | Tony Selfstatus 12 | attributeattributesstatusDocument 13 | Development Life Cyclelife 14 | cycleproject planning 15 | 16 | 17 |

Most DITA content elements include the 18 | status attribute. This attribute makes most sense when 19 | applied to the top-level topic element, such as 20 | concept, 21 | task and 22 | reference elements, and you can use it to record the 23 | status or progress of the information in its life cycle. 24 |

25 |

Valid values for the 26 | status attribute are: 27 |

37 |

38 |

Some authoring tools may highlight topics with different 39 | status attribute values in different ways, and some 40 | publishing tools may also take advantage of the attribute values. 41 |

42 |
43 |
44 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # DITAStyleGuide 2 | Source for The DITA Style Guide (English) 3 | Author: Tony Self 4 | -------------------------------------------------------------------------------- /Sample_Topics/t_mirage_engine_failure.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Engine failure below 10,000 feet 5 | 6 | 7 | 8 | Eject. 9 | 10 | 11 | 12 | 13 | 14 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Body_Elements.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Body elements 5 | The simple block structures within the body of topics are 6 | 8 | as the 9 | body elements. 10 | 11 | Tony 12 | Selfelementsbodybody 13 | elements 14 | 15 | 16 |

Body elements are the most common content authoring block elements, and 17 | include: 18 |

19 | 29 |
30 |
31 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Choice_Lists.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | Choice lists 6 | When writing task topics, the choice list structure can be used to 7 | describe alternative step choices. 8 | 9 | Tony Selfchoice 10 | listlistschoice list in task 11 | topicelementschoiceschoicechoices 12 | elementchoice element 13 | 14 | 15 |

A choice list is a special purpose list used within 16 | step elements in task topics to indicate that the user has 17 | to choose one of several actions to complete the task. 18 |

19 |

The choice list (choices) is similar in structure to the 20 | general purpose unordered list (ul). A 21 | choices element contains one or more 22 | choice elements. 23 |

24 |

An example of a choice list being used within a step is: 25 | <step> 26 | <cmd>Place the car in gear.</cmd> 27 | <choices> 28 | <choice>For automatic gearboxes, select <uicontrol>Park</uicontrol>.</choice> 29 | <choice>For manual gearboxes, select first gear.</choice> 30 | </choices> 31 | </step> 32 |

33 |
34 |
35 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Code_Blocks.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Identifying programming code 6 | The codeblock and codeph elements are used to identify code 7 | snippets. 8 | 9 | Tony Selfcodeph 10 | elementcodeblock 11 | elementelementscodephcodeblocksample 12 | codeprogramming codemark-up 13 | languagesmarking up 14 | 15 | 16 |

Examples of programming, scripting, or mark-up language code are marked 17 | up using the code phrase (codeph) and code block 18 | (codeblock) elements. As the element names suggest, code phrase 19 | is used when the code sample occurs inline within a paragraph or other block 20 | element, while code block is used when the code is more than one line long, and 21 | is a block in its own right. 22 |

23 |

Code block elements can be nested inside a paragraph (or other block 24 | element). 25 |

26 |

If you have text that introduces the codeblock and more text that 27 | immediately explains the code, you can use a structure such as in the following 28 | example: 29 | <p> 30 | If you display debugging information, such as in: 31 | <codeblock> 32 | debugText = app.name & app.ver 33 | debug.print("Value is " & debugText) 34 | </codeblock> 35 | you must launch the application in debugging mode. 36 | </p> 37 | 38 |

39 |

Line breaks can be used inside 40 | codeblock elements. 41 |

42 |
43 |
44 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Definition_Lists_vs_Tables.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | Definition lists versus tables 6 | Definition lists should be used for structuring terms and their 7 | corresponding definitions, rather than an alternative table structure. 8 | 9 | Tony 10 | Selfelementsdltabledefinition 11 | liststablesdefinitionsterms 12 | 13 | 14 |

Some information structures, particularly terms with corresponding 15 | definitions, can be marked up as either definition lists or tables. 16 |

17 |

If the content is indeed made up of terms and 18 | definitions, the definition list (dl) structure should be used. 19 | For content not so clearly identifiable as terms and definitions, but where 20 | there is a two part structure made up of short phrase and a longer explanation 21 | of the phrase, the simpler definition list structure should always be preferred 22 | over the table structure. 23 |

24 |

Definition lists are particularly suited to defining or explaining 25 | components or items. 26 |

27 | 28 | The difference between tables and definition lists 32 | Screen captures showing the difference between tables and 33 | definition lists in PDF output 34 | 35 | 36 |

Definition lists are rendered with fewer potential complications than 37 | tables, and are semantically stronger than the more generic table structure. 38 |

39 |
40 |
41 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Footnotes.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 6 | Footnotes 7 | The footnote (fn) element is used to nominate 8 | supplementary information that is not appropriate to be included in the flow of 9 | the content. 10 | 11 | Tony Selffn 12 | elementelementsfnfootnotes 13 | 14 | 15 |

A footnote is usually seen as being specific to page layout output 16 | formats, so marking up text as a footnote could be viewed as recording 17 | presentational information within content; something that DITA tries to avoid. 18 |

19 |

However, footnotes can also be considered as semantic identifiers for 20 | supplementary information that doesn't belong inline in the text. The footnote 21 | content is not critical to understanding the content, but provides extra 22 | information that may be useful to some readers. 23 |

24 |

The footnote (fn) element is typically rendered in the 25 | output as a number in the flow of the text and the footnote content at the 26 | bottom of the page or topic. The footnote number is automatically calculated 27 | during the publishing process. In hypertext output formats, the inline footnote 28 | reference number may be hyperlinked to the footnote at the bottom of the topic. 29 | Some publishing tools may display the footnote content in a popup window (in 30 | some hypertext output formats). 31 |

32 |

An example of a footnote (fn) element is: 33 | <p>Always wear a seatbelt. 34 | <fn>Some jurisdictions allow a medical exemption from wearing a seat belt 35 | in exceptional circumstances.</fn> 36 | </p> 37 |

38 |

39 |

40 |
41 |
42 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Images_within_Steps.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Images within steps 5 | Images that support a procedural step can be included within a 6 | stepxmp or an 7 | info element. 8 | 9 | Tony Selfimage 10 | elementelementsimagestepxmpinfoinfo 11 | elementstepxmp 12 | elementimageswithin 13 | steps 14 | 15 | 16 |

Images can be used to support documentation of task steps, as 17 | image elements within the 18 | cmd element, or as 19 | image elements within the 20 | stepxmp or 21 | info elements. 22 |

23 | 24 | Task topic 25 | <synph>steps</synph> structure showing 26 | <synph>image</synph> within a 27 | <synph>step</synph> 30 | Screen capture of task topic in DITA editor showing semantic 31 | elements 32 | 33 | 34 | 35 | Typical rendered result of steps mark-up 40 | Screen capture showing the rendered result of steps mark-up 41 | 42 | 43 |
44 |
45 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_List_of_Domains.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Element domains 5 | Elements in DITA are arranged into domains for 6 | 8 | purposes and technical reasons. 9 | 10 | Tony 11 | Selfdomainsmark-up 12 | domainselement 13 | domainsDTDschemaXSD 14 | 15 | 16 |

The base DITA elements are grouped into 17 | domains. You can see this clearly in the 18 | . 20 | 21 |

22 |

The DITA element mark-up domains are: 23 |

37 |

38 |

Different sets of elements are intended for use when documenting 39 | different types of things. The software domain, for example, contains the 40 | elements designed to semantically describe software characteristics. 41 |

42 |

The element domains are technically 43 | 45 | into different DTD or XSD schema modules. 46 |

47 |
48 |
49 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Lists.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Lists 6 | The purpose of a list is to make it easier for the reader to 7 | understand sequences of information and collections of like information. 8 | Different types of lists are used for different information structures. 9 | 10 | 11 | 12 | 13 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Map_Elements.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | Map elements 6 | The 7 | map elements are the elements used in ditamaps and bookmaps. 8 | 9 | Tony 10 | Selfelementsmapmap 11 | elements 12 | 13 | 14 |

The map elements are a small set of elements, some of which have been 15 | 17 | into other elements for use in bookmaps. 18 |

19 |

The map elements include: 20 |

34 |

35 |
36 |
37 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Mark-up_Concepts.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | Working with mark-up 6 | 7 |

There are a number of concepts and principles of XML mark-up in general, 8 | and DITA mark-up in particular. 9 |

10 |
11 |
12 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Multiple_Titles_in_a_Section.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | Titles 6 | A title is not the same as a heading. A topic, a figure, a table 7 | and a section should each have only one title. 8 | 9 | Tony 10 | Selfsectionsheadingstitle 11 | elementsection elementtopic 12 | elementfig elementtable 13 | elementtitlesfigureselementssectiontitletopicfigtable 14 | 15 | 16 |

The intention of the DITA approach is that the elements most commonly 17 | cross-referenced, such as topics, sections, figures and tables, should have a 18 | title. In some cases, the title element is mandatory. 19 |

20 |

Even though the DITA DTD may technically allow 21 | multiple titles to exist in one section, you should limit your section content 22 | to one title. Do not use titles as though they are headings. If you need 23 | multiple headings in a section, chances are that you really need multiple 24 | sections. 25 |

26 |
28 | Rationale 29 | Multiple 31 | titles are allowed by the *DTD* but not by the language of the specification. 32 | 33 |
34 |
35 |
36 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_One_Steps_per_Topic.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Substeps within Steps 5 | 6 | 7 | 8 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Other_Domains.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Metadata domain 6 | domainsmetadataindexingxNALmetadata 7 | domain 8 | 9 | 10 |

The metadata domain elements are designed for describing index entries 11 | and map-level metadata elements. 12 |

13 |
14 |
15 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Paragraphs.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | Paragraphs 6 | Paragraphs are the basic components of topics. A paragraph 7 | (p) element should be a self-contained unit dealing with one 8 | idea or point, typically expressed in two or more related sentences. The 9 | p element should be used when no other semantically-specific 10 | block element is available. 11 | 12 | 13 |
15 | Rationale 16 | There are two purposes for paragraphs, the 17 | one logical and the other practical. The logical purpose is to signal stages in 18 | a narrative or argument. The practical one is to relieve the forbidding gloom 19 | of a solid page of text. 20 | 21 |
22 |
23 |
24 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Parameter_Lists.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | Parameter lists 6 | When documenting programming functions and interfaces, the 7 | parameter list can be used to explain parameters passed between applications 8 | and functions. 9 | 10 | Tony Selfparameter 11 | listslistsparameter 12 | listelementsparmlplentryptpdparml 13 | elementplentry elementpt 14 | entrypd entry 15 | 16 | 17 |

Parameter lists are a special purpose list used to describe parameters 18 | in a program or application programming interface. The parameter list 19 | (parml) is similar in structure to the general purpose 20 | definition list (dl). 21 |

22 |

A parameter list (parml) element contains one or more 23 | parameter list entry (plentry) elements, each typically 24 | containing a parameter name or term (pt) and a parameter 25 | description (pd) element. 26 |

27 |

An example of a parameter list being used to explain some programming code is: 28 | <codeblock>callHelp(hFileName, contentId)</codeblock> 29 | <p>where 30 | <parml> 31 | <plentry> 32 | <pt>hFileName</pt> 33 | <pd>is the relative path to the Help file</pd> 34 | </plentry> 35 | <plentry> 36 | <pt>contentId</pt> 37 | <pd>is the context ID of the topic to display</pd> 38 | </plentry> 39 | </parml> 40 | </p> 41 |

42 |
43 |
44 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Phrases.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Phrases 5 | The semantics of words and phrases in DITA content is expressed 6 | through a broad range of phrase elements. 7 | 8 | 9 | 10 | 11 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Poetry_Dialogue_Text_Fragments.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Poetry, 5 | <ph 6 | conref="../../conref/conref_source.dita#topic_E1642C5A86C44BCE86FECD98EBAA3C89/var_dialogue"><?xm-replace_text Phrase?></ph> 7 | and fragments of text 8 | The 9 | lines element is used for content where the line breaks are 10 | important to the meaning of the text. 11 | 12 | Tony 13 | Selflineselementslinespoetrytext 15 | fragmentsline 16 | breakspre-formatting 17 | text 18 | 19 | 20 |

The 21 | lines element may be used to represent character 22 | , 24 | and text fragments where the line breaks can be considered to be part of the 25 | content. A good example of the 26 | lines element is to describe a poem. 27 |

28 |

A processor will treat line-end characters within a 29 | lines element to be part of the data; normally, for most 30 | other elements, line-end characters are ignored. 31 |

32 |

The 33 | lines element is similar to the 34 | pre element in HTML. 35 |

36 |
37 |
38 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Procedures.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Procedures and steps 6 | The purpose of procedural documents is to explain to the reader 7 | how to accomplish tasks. The task information type is specifically designed for 8 | procedures, with a well-defined structure built around steps. 9 | 10 | 11 | 12 | 13 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Program_Script_and_Routine_Names.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 6 | Program, script and routine names 7 | Program, routine, API and script names are identified using the 8 | cmdname and 9 | apiname elements. 10 | 11 | elementscmdnameapinameapiname 12 | elementcmdname elementprogram 13 | names 14 | 15 | 16 |

The DITA programming domain is a set of mark-up elements used for 17 | documenting programming languages and their use. The software domain is a 18 | similar set of elements used for documenting software applications. 19 |

20 |

To identify a program or script name within an 21 | end-user's use of a software application, you should use the 22 | cmdname (command name) element (from the software domain). 23 | 24 |

25 |

To identify a function, API or sub-routine within 26 | documentation aimed at programmers, you should use the 27 | apiname (API name) element (from the programming domain). 28 |

29 | 30 | Referring to a program name 31 | <step><cmd>After resetting the computer, run 32 | the <cmdname>syscheck</cmdname> program to verify 33 | the recovery.</cmd></step> 34 | 35 | 36 | Referring to a sub-routine or function 37 | <p>You can link the <apiname>print</apiname> sub-routine to 38 | the button's <apiname>onclick</apiname> event.</p> 39 | 40 |
41 |
42 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Programming_Domain.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Programming domain 6 | domainsprogrammingprogramming 7 | domainexemplarchunking 8 | attribute 9 | 10 | 11 |

The elements in the programming domain are designed for documenting 12 | programming languages. 13 |

14 |
15 |
16 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Prolog_Elements.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Prolog elements 5 | A topic's metadata is stored in a range of 6 | prolog elements. 7 | 8 | Tony 9 | Selfelementsprologprolog 10 | elements 11 | 12 | 13 |

The DITA prolog elements contain the main metadata for a topic or 14 | collection. 15 |

16 |

The types of information recorded in the prolog include: 17 |

31 |

32 |
33 |
34 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Required_and_Optional_Steps.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | Required and optional steps 6 | The 7 | importance attribute of a step is used to indicate whether 8 | an element is optional or mandatory. 9 | 10 | Tony Selfstep 11 | elementsubstep elementimportance 12 | attributeattributesimportanceelementsstepsubstepmandatory 13 | stepsoptional steps 14 | 15 | 16 |

The 17 | step and 18 | substep elements have an optional 19 | importance attribute, which has two valid values: 20 | and 21 | . The attribute is used to indicate whether the 22 | step is optional (within a set of mandatory steps), or required (within a set 23 | of optional steps). The 24 | setting is more commonly used than 25 | . 26 |

27 |

During processing to a reading format, steps with an 28 | importance attribute are typically rendered with an 29 | Optional: or 30 | Required: prefix. 31 |

32 | 33 | Typical rendering of step with importance attribute 34 | set 38 | Screen capture showing typical rendering of step with importance 39 | attribute set 40 | 41 | 42 |
43 |
44 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Single_Step_Procedure.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Single step procedure 5 | A procedure or task containing just one action should be marked-up 6 | using the normal steps/step/cmd structure. 7 | 8 | Tony Selfsteps 9 | elementstep elementsingle step 10 | procedureelementssteps 11 | 12 | 13 |

A single step procedure should still be marked up 14 | using the 15 | steps structure, rather than 16 | steps-unordered or 17 | steps-informal. 18 |

19 |

Some writers object to the default processing of something like: 20 |

21 | <steps> 22 | <step><cmd>Eject!</cmd></step> 23 | <steps> 24 |

as 25 |

26 | 1. Eject! 27 |

because they feel the number is unwarranted or confusing. 28 |

29 |

However, the semantics of the DITA source should always be observed over 30 | any preference in output format. The output processing should be changed if the 31 | output needs to be different (in our case, represented as a bulleted item 32 | instead of a numbered item). The DITA source shouldn't be corrupted or 33 | bent to achieve a certain output result. 34 |

35 |
36 |
37 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Software_Domain.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Software domain 6 | domainssoftwaresoftware 7 | domain 8 | 9 | 10 |

The software domain elements are designed for documenting the operation 11 | of a software program. 12 |

13 |
14 |
15 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Special_Characters_and_Dates.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Special characters and dates 6 | 7 |

Special characters and dates require different handling than normal 8 | text. 9 |

10 |
11 |
12 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Tables.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Tables 5 | The purpose of a table is to structure, 6 | 8 | and present factual data that a user will need to look up or reference. There 9 | are two general purpose table types in DITA: 10 | table and 11 | simpletable. 12 | 13 | 14 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_The_systemoutput_Element.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | Printouts, read-outs and other system output 6 | When a computer system, application or hardware equipment produces 7 | some output intended for reading by a user, the output is described in DITA 8 | using the 9 | systemoutput element. 10 | 11 | Tony 12 | Selfelementssystemoutputsystemoutput 13 | elementprintoutsread-outs 14 | from systems 15 | 16 | 17 |

The system output (systemoutput) element is used to 18 | describe the display or read-out from the device, application or system being 19 | documented. The 20 | systemoutput element is similar to the 21 | msgph element in that both elements describe the output 22 | from a system. The 23 | msgph element specifically describes a system message; 24 | systemoutput is less specific. 25 |

26 |

The 27 | systemoutput element should also be used when describing 28 | snippets of text from a printout from a computer application or system, such as 29 | words on the printed page. 30 |

31 |

Example: 32 | <p>Second and subsequent level numbers in a nested ordered 33 | list are typically rendered following the format of 34 | <systemoutput>1. a. I.</systemoutput>.</p> 35 |

36 |
37 |
38 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Topic_Elements.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Topic elements 5 | The 6 | topic elements are the basic structural building blocks of all 7 | information types. 8 | 9 | Tony 10 | Selfelementstopictopic 11 | elements 12 | 13 | 14 |

The topic elements are the main structural elements of topics. Some 15 | topic elements are generic (ie, inherited from the 16 | topic proto information type), while others are specific to 17 | the concept, task or reference information types. 18 |

19 |

Examples of topic elements include: 20 |

38 |

39 |
40 |
41 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Topic_Preview_via_shortdesc.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Topic Preview via shortdesc 5 | 6 | 7 | 8 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Types_of_Tables.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | Types of tables 6 | There are two different types of general purpose tables in DITA, 7 | table and 8 | simpletable, both of which are based on the CALS table model 9 | standard. 10 | 11 | Tony 12 | Selftablestypes 13 | oftable 14 | elementsimpletable 15 | elementelementstablesimpletable 16 | 17 | 18 |

The two types of general purpose tables in base DITA are: 19 |

20 | 21 |
table 22 |
23 |
The standard 24 | table structure is designed for complex, tabular 25 | information, where a title can be applied to the table. The 26 | table can also be easily cross-referenced, and a 27 | List of Tables generated during the publishing process. 28 |
29 |
30 | 31 |
simpletable 32 |
33 |
The 34 | simpletable structure is a much simplified design, 35 | with no provision for titles or cross-referencing. It is used for informal, 36 | simple tabular information. 37 |
38 |
39 |
40 |

41 |

Both types of table are based on the CALS standard table structure; the 42 | table structure of HTML is based on the same standard. 43 |

44 |

DITA also includes some special purpose tables, including relationship 45 | tables (used in ditamaps for cross-reference metadata) and 46 | properties tables (used in reference topics). 47 |

48 |
49 |
50 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Typographical_Domain.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Typographic (highlighting) domain 5 | domainstypographictypographic 6 | domainhighlighting domaintypographical 7 | domain 8 | 9 | 10 |

The elements in the typographic domain are used to describe styling 11 | characteristics. They are primarily intended as the basis for 12 | . 14 | Avoid using these elements. 15 |

16 |

Semantic elements should always be used in preference 17 | to typographic elements. 18 |

19 |
21 | Rationale 22 | Never use these elements when a semantically specific element is 23 | available. These elements are not intended for use by 24 | specializers, and are intended solely for use 25 | by authors when no semantically appropriate element is available and a 26 | formatting effect is required. 27 | 28 |
29 |
30 |
31 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Use_of_Class_Attribute.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Use of 5 | <synph>class</synph> attribute 6 | The 7 | class attribute is used in 8 | , 10 | and should not be set by a DITA author. The 11 | class attribute should not be confused with the 12 | outputclass attribute. 13 | 14 | Tony 15 | Selfinheritanceclass 16 | attributeoutputclass 17 | attributeattributesclassoutputclass 19 | 20 | 21 |

All DITA elements have a 22 | class attribute, but as a DITA author, you should never 23 | change this attribute. In fact, most DITA editors will hide it from you. The 24 | DITA 25 | class attribute is not the same as the HTML 26 | class attribute. (DITA's 27 | outputclass attribute is the closest equivalent to HTML 28 | class.) 29 |

30 |

All DITA based processors use the class attribute to determine how an 31 | element should be processed, rather than by using the element name itself. This 32 | is because 33 | 35 | may make the element name unfamiliar to the processor, but the 36 | class will indicate the element's inheritance, and 37 | therefore how it should be handled. 38 |

39 |
40 |
41 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_User_Interface_Domain.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | User interface domain 6 | domainsuser 7 | interfaceuser interface 8 | domain 9 | 10 | 11 |

The user interface domain elements are designed for documenting the user 12 | interface of a software program. 13 |

14 |
15 |
16 | -------------------------------------------------------------------------------- /Syntax_and_Markup/c_Utilities_Domain.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Utilities domain 6 | domainsutilitiesimage 7 | maputilities 8 | domain 9 | 10 | 11 |

The utilities domain elements are non-semantic elements used in defining 12 | image maps. 13 |

14 |
15 |
16 | -------------------------------------------------------------------------------- /Syntax_and_Markup/duplicated_c_Phrases_and_Blocks.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Phrases and Blocks 6 | DITA domain elements can be classified into 7 | block elements and 8 | phrase elements. 9 | 10 | Tony Selfphrase 11 | elementsblock elementsinline 12 | elementsspan elementsparagraph 13 | elements 14 | 15 | 16 |

In XML document mark-up languages, including DITA and XHTML, there are 17 | typically two types of content mark-up elements: block (or paragraph) elements, 18 | and phrase (or inline) elements. 19 |

20 |

Phrases are spans of text within a larger block of text, such as words 21 | within a paragraph. Typical phrase elements are term (term), 22 | code phrase (codeph), quotation (q), and syntax 23 | phrase (synph). 24 |

25 |

Blocks are paragraph-like elements, which are normally displayed with 26 | spacing above and below the block. Typical block elements are paragraph 27 | (p), code block (codeblock), long quotation 28 | (lq), and note (note). 29 |

30 |
31 |
32 | -------------------------------------------------------------------------------- /Syntax_and_Markup/obsolete_c_Semantics_of_Lists.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | The Semantics of Lists 5 | 6 |

It is possible that an unordered list's items might be re-sequenced (if 7 | not randomised), such as where the unordered list comprises possible answers 8 | for a multiple choice question in a Learning specialisation topic. 9 |

10 |

Perhaps discuss that lists can be sorted during processing. Maybe use 11 | linklist and linkpool as examples. 12 |

13 |
15 | Rationale 16 |
17 |
18 |
19 | -------------------------------------------------------------------------------- /Syntax_and_Markup/obsolete_c_Using_Term_Element_for_Definitions.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Using the 5 | <synph>term</synph> Element When Defining a Term 6 | 7 |

How should an expansion of acronym, abbreviation or other term be 8 | handled? For example, in the snippet: 9 |

10 | technologies such as XML Localization Interchange File Format 11 | (XLIFF) 12 | 13 |

should the mark-up be: 14 |

15 | technologies such as XML Localization Interchange File Format (<term>XLIFF</term>) 16 |

or 17 |

18 | technologies such as <term>XML Localization Interchange File Format</term> (<term>XLIFF</term>) 19 |

or 20 |

21 | technologies such as <term>XML Localization Interchange File Format</term> (XLIFF) 22 |

or something else? 23 |

24 |
25 |
26 | -------------------------------------------------------------------------------- /Syntax_and_Markup/r_Typography_Domain_Elements.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | Typographic domain elements 6 | The typographic domain elements each have a specific styling 7 | purpose. 8 | 9 | Tony 10 | Selfelementstypographictypographic 11 | domain 12 | 13 | 14 | 15 | Element NameSemantic 16 | Purpose 17 | 18 | bbold (strong) 19 | 20 | iitalic (emphasis) 21 | 22 | uunderlined 23 | 24 | ttteletype (typewriter) 25 | 26 | supsuperscript 27 | 28 | subsubscript 29 | 30 | 31 | 32 | 33 | -------------------------------------------------------------------------------- /Syntax_and_Markup/r_Utilities_Domain_Elements.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | Utilities domain elements 6 | The elements in the utilities domain each have a specific purpose 7 | in defining image map properties. 8 | 9 | Tony 10 | Selfelementsutilitiesutilities 11 | domainimage 12 | mapshypergraphics 13 | 14 | 15 | 16 | Element NameSemantic 17 | Purpose 18 | 19 | imagemapclient-side image 20 | map 21 | 22 | areahotspot area within an image 23 | map 24 | 25 | coordsco-ordinates of a hotspot area 26 | within an image map 27 | 28 | shapeshape of a hotspot area within an 29 | image map 30 | 31 | 32 | 33 | 34 | -------------------------------------------------------------------------------- /Syntax_and_Markup/r_software_domain_elements.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | Software domain elements 6 | The elements in the software domain each have a specific semantic 7 | purpose. 8 | 9 | Tony 10 | Selfelementssoftwaresoftware 11 | domain elements 12 | 13 | 14 | 15 | Element NameSemantic 16 | Purpose 17 | 18 | msgphmessage phrase 19 | 20 | msgblock message block 21 | 22 | msgnummessage number 23 | 24 | cmdnamecommand name 25 | 26 | varnamevariable (to be provided by 27 | user) name 28 | 29 | filepathfile name or path, or 30 | URI 31 | 32 | userinputuser input 33 | 34 | systemoutputsystem output 35 | 36 | 37 | 38 | 39 | -------------------------------------------------------------------------------- /Syntax_and_Markup/r_userinterface_domain_elements.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 6 | User interface domain elements 7 | The elements in the user interface domain each have a specific 8 | semantic purpose. 9 | 10 | Tony 11 | Selfelementsuser 12 | interfaceuser interface 13 | domain 14 | 15 | 16 | 17 | Element NameSemantic 18 | Purpose 19 | 20 | uicontroluser interface 21 | control 22 | 23 | wintitlewindow title 24 | 25 | menucascademenu cascade 26 | 27 | shortcutshortcut 28 | 29 | screencharacter (text only) screen 30 | 31 | 32 | 33 | 34 | 35 | -------------------------------------------------------------------------------- /Topics_and_Information_Types/c_Avoiding_Links_in_Topics.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Avoiding linking in topics 5 | A topic with an embedded link is bound to the target of that link. 6 | If the target topic is not included in the same output, the link is not 7 | relevant (and will appear as a broken link in the output). Links should 8 | therefore be removed from the topic to the ditamap; the map being the place 9 | where context is stored. 10 | 11 | Tony 12 | Selfreltablerelationship 13 | tablecontextseparation of content 14 | and 15 | formlinksembeddedlinksgeneratedhyperlinksembedded 16 | links 17 | 18 | 19 |

For content to be truly separated from format, structure, context and 20 | delivery, there can be no links embedded within the topic content, because 21 | links contain 22 | context. 23 |

24 |

Embedded links create a dependency upon the linked topics; the topic can 25 | only make sense if the target topics for each of the links it are delivered 26 | alongside it. If a target topic is not included in the same collection as the 27 | topic, then the link will be broken. 28 |

29 |

DITA includes automatic linking mechanisms based on relationships 30 | established in 31 | relationship table (reltable) within the ditamap. Because 32 | the ditamap defines the collection of topics to be delivered as a publication, 33 | this is a more logical place for links between topics in the collection to be 34 | defined. 35 |

36 |
37 |
38 | -------------------------------------------------------------------------------- /Topics_and_Information_Types/c_Concept.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Concept 5 | The 6 | concept topic is one of the three base DITA information types. 7 | 8 | 9 | Tony Selfinformation 10 | typesconceptconcept information 11 | typeconcept topic 12 | 13 | 14 |

Concept topics are used to document conceptual or overview information. 15 | They contain background information that users must know before they can successfully 16 | work with a product or within a process. Concepts can be broken into sections, but they 17 | are primarily comprised of simple paragraphs and unordered lists.

18 |

Concept topics answer the question what is?.

19 |

The root element of a concept topic is 20 | concept. 21 |

22 |
23 |
24 | -------------------------------------------------------------------------------- /Topics_and_Information_Types/c_Disambiguation_Topics.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Disambiguation topics 5 | Disambiguation topics help direct readers to the appropriate 6 | content where a term or concept is ambiguous and may refer to more than one 7 | topic. 8 | 9 | Tony 10 | Selfdisambiguationparent 11 | topics 12 | 13 | 14 |

Disambiguation topics help clarify ambiguity when one term 15 | or topic title may relate to a number of different topics. For example, a term 16 | ABS may stand for 17 | Anti-lock Braking System or for 18 | Automatic Brightness Sequencer. A disambiguation topic is 19 | typically a single topic explaining the different uses of the term, and links 20 | to the relevant alternative topics. 21 |

22 |
23 |
24 | -------------------------------------------------------------------------------- /Topics_and_Information_Types/c_Reference.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Reference 5 | The 6 | reference topic is one of the three base DITA information 7 | types. 8 | 9 | Tony Selfinformation 10 | typesreferencereference 11 | information type 12 | 13 | 14 |

Reference topics are used to describe features of sets of things, such 15 | as codes, types and commands. Information that normally demands tabular presentation 16 | probably belongs in reference topics. Catalogues, directories and bibliographies are 17 | good examples of reference topic information. Reference topics are often into tables.

20 |

Reference topics contains facts without explanation.

21 |

The root element of a reference topic is 22 | reference. 23 |

24 |
25 |
26 | -------------------------------------------------------------------------------- /Topics_and_Information_Types/c_Specialising_Information_Types.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | <ph 6 | conref="../../conref/conref_source.dita#topic_E1642C5A86C44BCE86FECD98EBAA3C89/var_Specialised_InitCap"><?xm-replace_text Phrase?></ph> 7 | information types 8 | 10 | information types provide a topic architecture that closely matches the 11 | structure of your content. 12 | 13 | Tony Selfinformation 15 | typescontent 17 | model 18 | 19 | 20 |

DITA is designed around topic 21 | . 23 | Many types of content will not suit the structure of the DITA base information 24 | types of concept, task and reference, but new information types, with a 25 | structure to exactly suit the nature of the content, can be evolved from the 26 | base types. 27 |

28 |

A 29 | 31 | information type is always derived from another DITA information type, so that 32 | you only need to define how your information type is different from what it is 33 | based on. 34 |

35 |
36 |
37 | -------------------------------------------------------------------------------- /Topics_and_Information_Types/c_Structuring_Reference_Data.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | Structuring Reference Data

A common form of documentation is Application Programming Interface (API) documentation. This involves documenting the functions of a shared programming library, and allows developers to re-use common programming functions. The information structure of an API function may be:

A specialised reference information types should be used for this sort of information structure. Some such specialised information types are available publicly, and are suited for particular programming languages. For example, the is a Java API information type available from the DITA Open Toolkit area on SourceForge.

-------------------------------------------------------------------------------- /Topics_and_Information_Types/c_Task.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Task 5 | The 6 | task topic is one of the three base DITA information types. 7 | 8 | Tony Selfinformation 9 | typestasktask information 10 | typetask topic 11 | 12 | 13 |

Task topics are used to document the steps of a particular task or procedure, 14 | or to document the stages within a high level process. Task topics are the building 15 | blocks for task-oriented documentation. Task topics are more strictly structured than 16 | concept and reference topics.

17 |

Task topics address the question of how to?.

18 |

The root element of a task topic is 19 | task. 20 |

21 |
22 |
23 | -------------------------------------------------------------------------------- /Topics_and_Information_Types/c_Topic_Proto.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | Topic (proto information type) 6 | The 7 | topic information type is the 8 | ancestor of all DITA information types, and is used mainly as 9 | the basis for 10 | 12 | new information types. 13 | 14 | Tony Selfinformation 15 | typestopictopic information 16 | typeproto information 17 | type 18 | 19 | 20 |

All DITA information types have 21 | evolved from the 22 | topic 23 | proto information type. The 24 | topic type is 25 | weakly information typed, or even 26 | untyped, in that it has generic rather than semantic 27 | elements. It is designed as a starting point for 28 | , 30 | and not for use as a container for structured, semantic content. 31 |

32 |

Apart from for 33 | , 35 | the other purpose of the untyped topic information type is to store legacy 36 | information during the migration of style-based documents to DITA. For example, 37 | when migrating untyped HTML content to DITA, it can be useful to first convert 38 | HTML topics to untyped DITA topic, for later conversion to correctly typed DITA 39 | information types such as concept, task and reference. 40 |

41 |

The root element of an untyped topic is 42 | topic. 43 |

44 |
45 |
46 | -------------------------------------------------------------------------------- /Topics_and_Information_Types/c_Working_with_Topics.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Working with topics 6 | exemplarstub 7 | topic 8 | 9 | 10 |

Topics are the building blocks of DITA, and a methodical approach to 11 | topic creation will result in consistent and more effective documents. 12 |

13 |
14 |
15 | -------------------------------------------------------------------------------- /Topics_and_Information_Types/obsolete_c_Common_Specialisations.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Common Specialisations 5 | 6 | 7 | 8 |

9 |

10 |

Another interesting difference is that DITA allows other information 11 | types to be defined through 12 | specialisations. Some common DITA specialisations are: 13 |

21 |

22 |
23 |
24 | -------------------------------------------------------------------------------- /Topics_and_Information_Types/obsolete_c_FAQ_Topics.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Example: FAQ (or Question and Answer) as Specialised Information 5 | Type 6 | 7 |

8 |

9 |
11 | Rationale 12 | ejosejulie wrote: > In the troubleshooting section of the 13 | document, I want to design the > page with all the questions in the 14 | beginning that is linked to the > answers in the same page. Please explain 15 | how to do it? The low-tech way is to use <xref> for the questions at the 16 | beginning. Each one points to the Question+Answer which comes later in the 17 | topic. I'd probably use <section> for a Question+Answer, <title> 18 | for the question, and <p> for the answer. <concept id="thistopic"> 19 | <title>Troubleshooting</title> <conbody> <sl> 20 | <sli><xref href="#thistopic/q1">What is 21 | foo?</xref></sli> <!-- More questions --> </sl> 22 | <section id="q1"> <title>What is foo?</title> <p>foo is 23 | a word used as a placeholder by geeks.</p> </section> <!-- More 24 | answers. --> </conbody> </concept> 25 | 26 |

Source: Deborah Pickett, Yahoo! DITA Users Group 27 |

28 |

29 | Turn this into a worked example... 30 | 31 |

32 |

Follow up from Michael Priestley 33 |

34 | Or a reference topic, with nested reference topic children - put the 35 | <related-links> to the children in the container reference topic. Same 36 | idea as others, but moving from xref and section to link and topic, which I 37 | tend to prefer for architectural reasons (like ability to integrate with 38 | map-based linking at some later point) 39 | 40 |
41 |
42 |
43 | -------------------------------------------------------------------------------- /Topics_and_Information_Types/obsolete_c_Sample_Content_Model.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Sample Content Model 5 | 6 |

7 | This topic isn't really needed. 8 | 9 |

10 |

A simple example topic content model for describing a software feature 11 | might be: 12 |

13 | 29 |
30 |
31 | -------------------------------------------------------------------------------- /Topics_and_Information_Types/obsolete_c_Topic_Type_Specialisation.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | Topic Type Specialisation

To create a new topic type (something other than topic, task, concept or reference), the steps that Eliot Kimber suggests you should follow are:

  1. Work out which elements you will need in your new topic type. For example, if your new topic type is designed to contain lists of airliner registrations, you may decide you need elements for manufacturer, build number, model number, model name, version number, country of registration, and registration code.
  2. "Clone" the shell DTD of the base topic type that is the closest match to your new topic type. For example, our airliner registration topic may be a specialised type of reference topic.
  3. Create a sample document with the mark-up for the new topic type.
  4. Modify the DTD modules until the sample document validates.
-------------------------------------------------------------------------------- /Topics_and_Information_Types/obsolete_c_What_if_the_Content_Model_Does_Not_Fit.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | What if a content model doesn't fit? 5 | 6 |

7 | This belongs in syntax, with a new title, such as Hacking 8 | the Content Model. File name would need changing too. May be already a topic 9 | with same purpose, so maybe merge? 10 | 11 |

12 |
14 | Rationale 15 | I was wondering if anyone knows of an extension that's been developed 16 | that allows you to add a <note> element *between* <step> elements 17 | in a DITA task. (Even if you have to wrap it in an <info> element.) There 18 | are places in our documentation where we need a cautionary statement to come 19 | before a step or a series of steps. Putting it within the previous step's 20 | element won't cut it. 21 | 22 | For example: 23 | 24 | <steps> 25 | <step><cmd>This is the first step.</cmd></step> 26 | <info><note type="warning">Here is a warning statement that 27 | needs to come before the next step.</note></info> 28 | <step><cmd>This is the next step.</cmd></step> 29 | <step><cmd>You get the point.</cmd></step> 30 | </steps> 31 |

Mike Kokic, correspondence to dita-users Yahoo group 32 |

33 |
34 |
35 |
36 | -------------------------------------------------------------------------------- /Topics_and_Information_Types/obsolete_c_Writing_Task_Topics.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | Writing Task Topics

Link to Task Topic Exemplar in Exegesis

Source: Hughes (2009)

-------------------------------------------------------------------------------- /artefact_graphics.ditamap: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Graphics and Figures 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | -------------------------------------------------------------------------------- /artefact_introduction.ditamap: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | DITA Style Guide Introduction 5 | 6 | 7 | 8 | 9 | -------------------------------------------------------------------------------- /artefact_test.ditamap: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | DITA Authoring Concepts 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | -------------------------------------------------------------------------------- /c_Content_Re-use.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | Content re-use 6 | 7 | Re-use, re-use, re-use, 8 | re-use... content re-use is key to content management so it bears repeating 9 | repeating repeating. Content re-use means that you can write content once and 10 | use it wherever required, but it also means that you have to write content 11 | consistently so that it can be re-used. 12 | 13 | 14 | 15 | -------------------------------------------------------------------------------- /c_Conventions_(Not_Included_in_Output).dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Conventions (Not Included in Output) 6 | 7 | 8 | 9 |

ditamap is not a term; it is just a normal word. The exception is when 10 | it is being defined. Avoid starting a sentence with ditamap. 11 |

12 |

conref is not a term; it is just a normal word. The exception is when it 13 | is being defined. Avoid starting a sentence with conref. 14 |

15 |
16 |
17 | -------------------------------------------------------------------------------- /c_Cross-referencing.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | Cross-referencing 6 | Cross-references are a means of binding individual topics into a 7 | coherent and navigable document. 8 | 9 | linkinglinkslinkslinking 10 | 11 | 12 | There 14 | is no greater skill a web professional needs to develop than the ability to 15 | create quality links. Many websites do not need more publishing. Rather, they 16 | need more linking of content in appropriate task journeys. Linking is a complex 17 | skill because it requires you to see the task through your customer's eyes. 18 | 19 | 20 | 21 | -------------------------------------------------------------------------------- /c_DITA_Authoring_Concepts.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | DITA authoring concepts 6 | Moving from style-based authoring to a structured authoring 7 | methodology such as DITA requires a radically different approach to writing. 8 | 9 | 10 | DITA is an open content standard that defines a 11 | common structure for content that promotes the consistent creation, sharing, 12 | and re-use of content. 13 | 14 |

15 | This section needs reorganisation, and more DITA overview 16 | content from papers, WinANT, or HATC424. (Perhaps refer to TACTICS workbook?) 17 | Some of the topics should be moved to the Literature review section of the 18 | Exegesis. 19 | 20 | Need to add an introduction topic to say that this Manual 21 | of Style isn't a replacement for the DITA Langref, but is intended to be read 22 | alongside it. Also, it is not intended to be a comprehensive guide to all DITA 23 | elements and attributes, and nor is it intended to be a DITA training manual. 24 | It is intended to be a reference when contentious issues are encountered. It 25 | documents a series of suggestions for how DITA should be implemented, and its 26 | main goal is to provide a tool for creating consistent and logical DITA 27 | semantic mark-up. 28 | 29 | Do we need a topic explaining the open source movement 30 | 31 |

32 |
33 |
34 | -------------------------------------------------------------------------------- /c_Language_and_Punctuation.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Language and punctuation 6 | 7 | If language is not correct, then what is said is 8 | not what is meant; if what is said is not what is meant, then what must be done 9 | remains undone; if this remains undone, morals and art will deteriorate; if 10 | justice goes astray, the people will stand about in helpless confusion. Hence 11 | there must be no arbitrariness in what is said. This matters above everything. 12 | 13 | 14 | 15 | -------------------------------------------------------------------------------- /c_Syntax_and_Markup.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | Syntax and mark-up 6 | 7 | I ascribe a basic importance to the phenomenon 8 | of language. To speak means to be in a position to use a certain syntax, to 9 | grasp the morphology of this or that language, but it means above all to assume 10 | a culture, to support the weight of a 11 | civilization. 12 | 13 | 14 | 15 | -------------------------------------------------------------------------------- /c_The_DITA_Publishing_Process.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | The DITA documentation process 5 | 6 | The most difficult thing is the decision to 7 | act, the rest is merely tenacity. The fears are paper tigers. You can do 8 | anything you decide to do. You can act to change and control your life; and the 9 | procedure, the process is its own reward. 10 | 11 | 12 | 13 | -------------------------------------------------------------------------------- /c_Topics_and_Information_Types.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Information types and topics 6 | Topics are the building blocks of modular documents, and 7 | organising topics by semantic information types is one of the architectural 8 | features of DITA. 9 | 10 | 11 | Information is not knowledge. Knowledge is not 12 | wisdom. Wisdom is not truth. 13 | 14 | 15 | 16 | -------------------------------------------------------------------------------- /c_Types_of_Metadata.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Metadata, conditional processing, and indexing 6 | 7 | Knowledge is not gained by collecting 8 | information, but by understanding what information to throw away. 9 | 10 |
12 | References 13 |

John Durham Peters quotation from keynote address delivered at ANZCA 14 | 2010, Canberra, Australia. 15 |

16 |
17 |
18 |
19 | -------------------------------------------------------------------------------- /c_Working_with_Graphics_and_Figures.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Graphics and figures 5 | graphicsimagesfigures 6 | 7 | 8 | Un bon croquis vaut 9 | mieux qu'un long discours. (A good sketch is better than a long speech.) 10 | 11 | 12 | 13 | -------------------------------------------------------------------------------- /conref/conref_source_email.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Mailing List References 6 | Tony SelfHyperWrite Pty 8 | Ltdbibliographycitationsmailing 9 | listsreferences 10 | 11 | 12 | 18 | 19 | 20 | -------------------------------------------------------------------------------- /conref/conref_source_footnotes.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Conref Source for Footnotes 6 | This topic is not meant for inclusion in a ditamap, but as a 7 | source of transcluded footnote content. 8 | 9 | 10 |

A footnote must exist in a paragraph, as it is an inline element, not a 11 | block element. 12 |

13 |

Ament, K., 2003. Single Sourcing: Building Modular 14 | Documentation 1st ed., New York: William Andrew Publishing. 15 |

16 | 17 |
18 | -------------------------------------------------------------------------------- /conref/conref_source_index.ditamap: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Index Term Re-use 6 | 7 | 8 | conref 9 | 10 | 11 | -------------------------------------------------------------------------------- /conref/conref_source_metadata.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Metadata Conref Source 5 | This topic contains only metadata for re-use in other topics. 6 | 7 | Tony SelfHyperWrite Pty 9 | Ltdspecialisationspecialisation 12 | elementsgeneralisationorganisingorganising re-usespecialisedorganisation of 18 | elementsdomain 20 | specialisationstructural 22 | specialisationspecialisationpros and 24 | consspecialisationrules 26 | ofspecialisationtypes 28 | ofdomainstructuraldialoguelocalising graphicslocalisationlabellinglocalisationgraphics 34 | 35 | 36 | 37 | -------------------------------------------------------------------------------- /conref/en-US_conref_source_metadata.dita: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Metadata Conref Source 5 | This topic contains only metadata for re-use in other topics. 6 | 7 | Tony SelfHyperWrite Pty 9 | Ltdspecializationspecialization 12 | elementsgeneralizationorganizingorganizing re-usespecializedorganization of 18 | elementsdomain 20 | specializationstructural 22 | specializationspecializationpros and 24 | consspecializationrules 26 | ofspecializationtypes 28 | ofdomainstructuraldialoglocalizing graphicslocalizationlabelinglocalizationgraphics 34 | 35 | 36 | 37 | -------------------------------------------------------------------------------- /conref/temp.txt: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /images/BlockDiagram_DITA_within_XML.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/BlockDiagram_DITA_within_XML.gif -------------------------------------------------------------------------------- /images/BlockDiagram_DITA_within_XML.vsd: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/BlockDiagram_DITA_within_XML.vsd -------------------------------------------------------------------------------- /images/DITA_Workflow.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/DITA_Workflow.gif -------------------------------------------------------------------------------- /images/ace.swf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/ace.swf -------------------------------------------------------------------------------- /images/breadcrumbs.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/breadcrumbs.png -------------------------------------------------------------------------------- /images/breadcrumbs.psp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/breadcrumbs.psp -------------------------------------------------------------------------------- /images/callout_key_ej25_turbo.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/callout_key_ej25_turbo.jpg -------------------------------------------------------------------------------- /images/callout_text_ej25_turbo.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/callout_text_ej25_turbo.jpg -------------------------------------------------------------------------------- /images/choicetable_example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/choicetable_example.png -------------------------------------------------------------------------------- /images/collection_links_html.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/collection_links_html.gif -------------------------------------------------------------------------------- /images/collection_links_pdf.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/collection_links_pdf.gif -------------------------------------------------------------------------------- /images/collection_type_choice.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/collection_type_choice.gif -------------------------------------------------------------------------------- /images/collection_type_family.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/collection_type_family.gif -------------------------------------------------------------------------------- /images/collection_type_sequence.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/collection_type_sequence.gif -------------------------------------------------------------------------------- /images/collection_type_unordered.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/collection_type_unordered.gif -------------------------------------------------------------------------------- /images/conref_folder_structure.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/conref_folder_structure.png -------------------------------------------------------------------------------- /images/conref_organisation_table.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/conref_organisation_table.png -------------------------------------------------------------------------------- /images/content_form_example1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/content_form_example1.png -------------------------------------------------------------------------------- /images/content_form_example2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/content_form_example2.png -------------------------------------------------------------------------------- /images/content_form_example3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/content_form_example3.png -------------------------------------------------------------------------------- /images/darwin.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/darwin.jpg -------------------------------------------------------------------------------- /images/darwin_library_of_congress.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/darwin_library_of_congress.jpg -------------------------------------------------------------------------------- /images/design_patterns_1.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/design_patterns_1.gif -------------------------------------------------------------------------------- /images/design_patterns_2.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/design_patterns_2.gif -------------------------------------------------------------------------------- /images/design_patterns_3.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/design_patterns_3.gif -------------------------------------------------------------------------------- /images/dl_vs_table.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/dl_vs_table.png -------------------------------------------------------------------------------- /images/eclipse_help_map_structure.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/eclipse_help_map_structure.png -------------------------------------------------------------------------------- /images/ej25_turbo_engine_WRX.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/ej25_turbo_engine_WRX.jpg -------------------------------------------------------------------------------- /images/embedded_maps.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/embedded_maps.gif -------------------------------------------------------------------------------- /images/evolution.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/evolution.gif -------------------------------------------------------------------------------- /images/evolution.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/evolution.png -------------------------------------------------------------------------------- /images/evolution.vsd: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/evolution.vsd -------------------------------------------------------------------------------- /images/figure_example_result.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/figure_example_result.png -------------------------------------------------------------------------------- /images/generated_links_example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/generated_links_example.png -------------------------------------------------------------------------------- /images/generated_links_example1.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/generated_links_example1.gif -------------------------------------------------------------------------------- /images/html_help_map_structure.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/html_help_map_structure.png -------------------------------------------------------------------------------- /images/hughes_stub_topic_example1.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/hughes_stub_topic_example1.jpg -------------------------------------------------------------------------------- /images/hughes_stub_topic_example2.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/hughes_stub_topic_example2.jpg -------------------------------------------------------------------------------- /images/index_multilevel.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/index_multilevel.png -------------------------------------------------------------------------------- /images/index_seealso.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/index_seealso.png -------------------------------------------------------------------------------- /images/indirection_schematic.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/indirection_schematic.png -------------------------------------------------------------------------------- /images/indirection_schematic.vsd: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/indirection_schematic.vsd -------------------------------------------------------------------------------- /images/info_type_content_model.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/info_type_content_model.gif -------------------------------------------------------------------------------- /images/info_type_content_model.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/info_type_content_model.png -------------------------------------------------------------------------------- /images/info_type_specialisation.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/info_type_specialisation.gif -------------------------------------------------------------------------------- /images/information_types.vsd: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/information_types.vsd -------------------------------------------------------------------------------- /images/list_types_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/list_types_1.png -------------------------------------------------------------------------------- /images/nested_conref_schematic.vsd: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/nested_conref_schematic.vsd -------------------------------------------------------------------------------- /images/network_address.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/network_address.png -------------------------------------------------------------------------------- /images/note_in_step_rendered.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/note_in_step_rendered.png -------------------------------------------------------------------------------- /images/parallel_vs_embedded_lists.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/parallel_vs_embedded_lists.png -------------------------------------------------------------------------------- /images/parallel_vs_embedded_lists.vsd: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/parallel_vs_embedded_lists.vsd -------------------------------------------------------------------------------- /images/prereq_required_links.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/prereq_required_links.png -------------------------------------------------------------------------------- /images/process_levels_idoinfotech-com.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/process_levels_idoinfotech-com.jpg -------------------------------------------------------------------------------- /images/process_levels_idoinfotech-com.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/process_levels_idoinfotech-com.png -------------------------------------------------------------------------------- /images/processes_vs_procedures.vsd: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/processes_vs_procedures.vsd -------------------------------------------------------------------------------- /images/processes_vs_procedures_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/processes_vs_procedures_1.png -------------------------------------------------------------------------------- /images/restricting_tags_xmetal.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/restricting_tags_xmetal.png -------------------------------------------------------------------------------- /images/sample_button.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/sample_button.png -------------------------------------------------------------------------------- /images/screen_capture_field_example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/screen_capture_field_example.png -------------------------------------------------------------------------------- /images/shortdesc_example1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/shortdesc_example1.png -------------------------------------------------------------------------------- /images/shortdesc_example2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/shortdesc_example2.png -------------------------------------------------------------------------------- /images/shortdesc_example3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/shortdesc_example3.png -------------------------------------------------------------------------------- /images/sl_vs_ul.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/sl_vs_ul.png -------------------------------------------------------------------------------- /images/sl_vs_ul.png.bak: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/sl_vs_ul.png.bak -------------------------------------------------------------------------------- /images/specialisation_schematic.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/specialisation_schematic.gif -------------------------------------------------------------------------------- /images/step_importance_attribute_rendered.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/step_importance_attribute_rendered.png -------------------------------------------------------------------------------- /images/stub_topic_example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/stub_topic_example.png -------------------------------------------------------------------------------- /images/style_guide_cascade.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/style_guide_cascade.jpg -------------------------------------------------------------------------------- /images/task_topic_steps_structure.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/task_topic_steps_structure.png -------------------------------------------------------------------------------- /images/task_topic_steps_structure_rendered.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/task_topic_steps_structure_rendered.png -------------------------------------------------------------------------------- /images/title_usage.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/title_usage.png -------------------------------------------------------------------------------- /images/toc_example.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/toc_example.gif -------------------------------------------------------------------------------- /images/xsl_in_publishing.vsd: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/xsl_in_publishing.vsd -------------------------------------------------------------------------------- /images/~$$parallel_vs_embedded_lists.~vsd: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperwrite/DITAStyleGuide/dadb2916fa0d3f81bbeb20337317ebdb8dfe8112/images/~$$parallel_vs_embedded_lists.~vsd --------------------------------------------------------------------------------