MadCap Flare Version 9

Transcription

1 MadCap Flare Version 9 Importing an MSWord 2007 Document TECHCOMM PROCEDURE Sample Flare Project by Laura Protano

2 Copyright 2014 Company Incorporated. All Rights Reserved. The copyright and trade secret laws of the United States and other countries protect this material. No part of this material or software covered by the copyrights herein may be reproduced distributed or altered in any fashion without prior written consent of Company Incorporated. Content is subject to change without notice. For permission to reproduce or distribute this material please contact Company Incorporated. Trademarks Company Incorporated is a trademark of Company Incorporated. Microsoft Windows is a registered trademark of Microsoft Corporation. All other trademarks and trade names are the property of their respective companies. Last Revised: 6/26/2014 Contact Information Company Incorporated Corporate Headquarters 123 Main Street Town, ST Tel: Fax:

3 2Contents About this Procedure 1 1 Prepare the Word Document for Import 3 2 Create the Flare Project 9 3 Import the Word Document to the Flare Project 15 4 Organize Topics by Chapter 23 5 Set Up the Project TOC 25 6 Clean Up the Imported Content 31 Delete Empty Tags 31 Format Imported Tables 31 Format Imported Lists 33 Format Imported Images 34 Format Imported Notes 35 Fix Imported Text Cross-References 35 Apply New Styles 36 7 Set Up the PDF Output 37 8 Set Up the HTML5 Output 39 Writing Sample 2014 Laura Protano iii

4 Contents MadCap Flare iv Writing Sample 2014 Laura Protano

5 About this Procedure This procedure describes the steps to import a Microsoft Word 2007 document into a MadCap Flare version 9 project. These steps assume that you have already created a global Flare project that contains a stylesheet, page layouts, a master page, an HTML5 skin file, common topic files (for example, cover page and home page designs), as well as the required snippets, variables, and condition tags. To import a Word 2007 document to a Flare project, complete the following tasks: "Prepare the Word Document for Import" on page 3 "Create the Flare Project" on page 9 "Import the Word Document to the Flare Project" on page 15 "Organize Topics by Chapter" on page 23 "Set Up the Project TOC" on page 25 "Clean Up the Imported Content" on page 31 "Set Up the PDF Output" on page 37 "Set Up the HTML5 Output" on page 39 Writing Sample 2014 Laura Protano 1

6 About this Procedure MadCap Flare 2 Writing Sample 2014 Laura Protano

7 1 1Prepare the Word Document for Import Before you import a Word Document to a Flare project, you will apply several formatting changes to the Word document. This will reduce the amount of manual corrections needed in the Flare project after the import. Make the Word changes in a copy of the original document to ensure that the original Word document remains intact and available for comparison with the completed Flare project. To prepare a Word 2007 document (*.docx) for import into a Flare project: 1. Make a copy of the original Word document. 2. Open the copy of the Word document. Note After the Word import to Flare, you will delete the imported cover page, copyright page, and table of contents (TOC) topics. Therefore, you do not need to complete any prep work in those sections of the Word document except for updating the TOC after you complete all other prep steps. (Flare creates its project TOC based on the Word TOC.) 3. Attach the latest TechComm Word template (long version: TechComm_LongDocs_<date>.dotx), and select the Automatically Update Document Styles check box. You can do this from the Developer ribbon (if open), or from Word Options > Add-ins > Manage: Templates. 4. Check if the document uses consistent heading and paragraph styles throughout the document. It's OK if the document uses old paragraph styles; we'll convert them to new styles during the import. However, you want to be sure that all headings and paragraphs don't use the same paragraph style (e.g., Normal) with inline formatting applied to generate the desired look. If that is the case, apply paragraph styles to headings and body text as needed before starting the preparation process. 5. For all heading styles in use in the Word document, including appendix headings, turn off autonumbering. To do so: a. Open the Styles window from the Home ribbon. b. Right-click a heading style, and select Modify. c. Click the Format button, and select Numbering. The Numbering and Bullets window opens. By default, None is selected. Writing Sample 2014 Laura Protano 3

8 1 Prepare the Word Document for Import MadCap Flare d. Click OK to clear the numbering for the heading styles. e. Repeat for all heading styles in use in the document. 6. If any headings appear in all capital letters, change them to initial caps only. From the Home ribbon, Font group, click the Change Case tool and then select Capitalize Each Word. (Tip! An easy way to tell if any headings appear in all caps is to review the TOC.) 7. Do the following to prepare images in the Word document: Save a copy of inserted Visio objects. If a Visio diagram is inserted as an object in the Word document, save a copy of the image as a Visio file (*.VSD) so that you can edit the source file later. To do so, right-click the image, select Visio Object > Open. Then, with Visio open, select File menu > Save Copy As, and save the Visio file to a local folder. (Unlike Word, Flare does not let you insert a Visio object into a topic.) During the Import, Flare automatically converts a Visio object to a PNG file and inserts the PNG file into the topic. When you save your Flare project in source control, also save a copy of the Visio files. Remove text boxes. If an image is inserted within a text box, copy the image to a separate paragraph (e.g., paragraph style Graphic Centered or Graphic Left-Aligned), and then delete the text box. This avoids problems when working in Word's Outline view later in this process. 8. Do the following to prepare lists (numbered and bulleted) in the Word document: Single Level Lists a. Apply the Normal paragraph style to the list (including images in the list). This removes all numbers and bullets. b. Use Word s Numbering or Bullets tool to reapply the numbers or bullets. This changes the style to List Paragraph. During the import to Flare, DO NOT map Word's List Paragraph paragraph style to a Flare style. These lists will import as a single list, but you will need to tweak the list to get the correct bullet style and indentation. Multi-Level Lists There are two ways to prepare multi-level lists; both methods require that you have an original copy of the Word document so that you can recreate the nested levels. Method 1, Set List Sublevels in Word Document a. Apply the Normal paragraph style to the list (including images in the list). This removes all numbers and bullets. b. Use Word s Numbering or Bullets tool to reapply the numbers or bullets. This changes the style to List Paragraph. c. Use Word s Increase Indent tool to indent the levels of numbers or bullets as needed. 4 Writing Sample 2014 Laura Protano

9 MadCap Flare 1 Prepare the Word Document for Import During the import, DO NOT map Word's List Paragraph paragraph style to a Flare style. After the import, the indented levels will appear as separate lists within the original list (for example, items 1 to 3, then 1-10 (the nested items), then 4-5 (continuation of the original list). Use Flare s Merge with Previous List tool to link the indented level to the previous list, and then use Flare s indent tool to indent the sublevel. This method lets you more easily see where the indented levels appear in Flare than the next method. Method 2, Set List Sublevels in Flare Apply the Normal style to the list (including images in the list); this removes all numbers and bullets. Then, use Word s bullet/number tool to reapply the numbers/bullets. This changes the style to List Paragraph. a. Apply the Normal paragraph style to the list (including images in the list). This removes all numbers and bullets. b. Use Word s Numbering or Bullets tool to reapply the numbers or bullets. This changes the style to List Paragraph. During the import, DO NOT map Word's List Paragraph paragraph style to a Flare style. After the import, a single list appears with no indication of where to indent the sublevels. Use Flare's Indent Items tool to manually adjust list levels. Use a copy of the original Word document to determine where the list levels need to be adjusted. 9. Use Word's Outline View (View ribbon, Document Views group, Outline tool) to complete the following steps: Notes If the Word document contains images placed within text boxes, they appear as blank paragraph marks in Outline View and could inadvertently get deleted. Before you complete the steps in this section, remove the text boxes as described earlier in this process. Make sure Word's Show/Hide Paragraph mark tool (Home ribbon, Paragraph group) is set to show the paragraph marks. a. Use Outline View to remove empty paragraphs and hard page breaks from the Word document. If you don't remove empty paragraphs, you'll have to delete them from the Flare document after the import. In Flare, spacing between paragraphs is controlled by Flare styles; typically, no empty paragraphs are needed.. If you don't remove hard page breaks, topics will split badly during the import. (Outline View shows hard page breaks only; it does not show page breaks applied via Paragraph properties. You do not need to remove the latter type of page break.) b. If the document contains text with manual character formatting applied (for example, bold, italic, color), apply Word character styles to that text. During the Flare import, manual character formatting is not retained. However, if you have applied Word character styles, you can map them to Flare span styles during the import in order to retain the formatting. Writing Sample 2014 Laura Protano 5

10 1 Prepare the Word Document for Import MadCap Flare Tip: In word, use the F4 key (repeat) when possible to save time when applying character styles. Caution: Apply character styles that reflects the text's function (e.g., UI element), rather than trying to retain the existing manual formatting. This helps to ensure that the character styles match our current standards. c. If the Word document contains a cross-references that has been entered manually rather than using the Word cross-reference tool, do the following to apply character formatting to text; after the import, this will provide a visual queue as to where a Flare cross-reference should be inserted: i. Select the cross reference sentence in Word and clear all formatting (Ctrl+Spacebar) or Clear All in the Style menu. ii. iii. Edit the text to remove references to chapter, guide, or "earlier/later in the document." For example, change the sentence "See the Module Overview chapter in this guide for details on searching for letter triggers." to "See Module Overview for details on searching for letter triggers." Select only the name of the topic or chapter and apply the ImportReference style. d. Apply the Note paragraph style to obvious notes so that you can map this style to the Flare p.note class during the import. 10. Update the Word document's headings to be semantically correct for conversion to HTML. Do not skip any heading levels, and any text that is used as a heading should have a heading paragraph style applied. The Word chapter headings should be one of the Level 1 styles (e.g., Heading 1, Heading 1 No Num), and subsequent heading levels should be used in sequence without skipping any levels. For example, if all your chapters start with "Heading 2", change this to "Heading 1", and then adjust subsequent heading levels as needed. If you use bold body text as a pseudo-heading, change the style to a heading 3 or 4 to import the text as a heading. Note It can be helpful to complete this step in Outline View, since that view shows any special formatting applied to text (e.g., red/bold) so you can easily identify text formatted as a heading and verify that a heading style is applied. 11. Optionally, find and delete outdated index hits. From the Find dialog box, click More >>, then click Special, and select Field from the Special menu. Although index hits do get imported to Flare, don't import them if they are outdated. Alternatively, you can delete the imported index entries from the Flare topics after the import. 6 Writing Sample 2014 Laura Protano

11 MadCap Flare 1 Prepare the Word Document for Import 12. Last Prep Step: Update the TOC in the Word document. Either click the Update Table link at the beginning of the Table of Contents (see figure below), or select the entire document and update all fields (Ctrl+A, then F9). When you receive a prompt asking whether you want to update just the TOC page numbering or the entire TOC, select the option to update the entire TOC. It's important to complete this step after all other preparation is complete to ensure that the resulting Flare TOC entries will not contain numbers or text that you'll need to edit, and to ensure that the hierarchy of the Flare TOC will be more accurate. Review the TOC to make sure there are no numbers in headings. This can happen if the heading style has a hidden number assigned. In that case, adjust the heading style or local formatting to make sure that the numbering is removed from the heading style, and then repeat this step. Writing Sample 2014 Laura Protano 7

12 1 Prepare the Word Document for Import MadCap Flare 8 Writing Sample 2014 Laura Protano

13 2 2Create the Flare Project To create a new Flare project based on the department's global Flare project, do the following: 1. Using SharePoint's Explorer View, copy the global project from SharePoint to a new empty folder where you will store the new project. Note In order to use Explorer View to copy over Flare project files or folders already posted to SharePoint, you must first check out the files. Since some Flare folders (e.g., Content) can contain hundreds of files, it's best to use SharePoint's Manage Content and Structure tool (from the Site Actions menu) to check out the entire folder, and then check it back in again after you have copied the updated files to the folder.) 2. Rename the project file (*.flprj file) to reflect your new project. 3. Double-click the project file to open it in Flare. 4. Optional. If not already configured, use Flare's SharePoint Explorer tool to point to the location of the global project on SharePoint. This lets you keep your project synchronized with the team's shared styles and other content. Note This location is already configured in the global project so it should appear in your project by default when you open SharePoint Explorer. This step is provided for reference, but you can typically skip this step. a. On the Flare Project ribbon, click SharePoint Explorer. SharePoint Explorer opens in the left-side of the application window. b. In the SharePoint Explorer pane, click the Connect to SharePoint Server tool. The Connect to SharePoint Server dialog box opens. c. Enter the URL of the department's GlobalProject folder on SharePoint, and then click the blue check mark button to connect to the server. The dialog box shows a success message after Flare verifies that it can reach the server. d. Click OK. Writing Sample 2014 Laura Protano 9

14 2 Create the Flare Project MadCap Flare SharePoint Explorer shows the newly mapped location: 5. The global project that you use to create a new project is configured with mappings that allow you to synchronize new projects with the global project. This is useful when we make changes to files shared across projects such as our logo or style sheet. To view these mappings, select Project ribbon > Manage Mappings. The following figure shows how the Map Files and Folders window should look for a TechComm Flare project: Optionally. If your project does not have the correct mappings to the global project, complete the following steps to set those mappings: a. In SharePoint Explorer, navigate to the target folder or file (see table below), copy it to your project, and then select to synchronize it with your project. You can synchronize with entire folders or individual files in the Content folder (for example, all file in the TableStyles folder), and you can synchronize with individual files only in the Project folder (for example, a condition tag file). Folder or File to Synchronize Location In the project's CONTENT folder: Global_Images folder Global_Master_ Page.flmsp and Startup_ Content > Resources > Images > Global Images Content > Resources > MasterPages > Global_Master_ Page.flmsp 10 Writing Sample 2014 Laura Protano

15 MadCap Flare 2 Create the Flare Project Folder or File to Synchronize Location Page.flmsp Master Page file PageLayouts folder Snippets folder Content > Resources > PageLayouts Content > Resources > Snippets *Note that if you add project-specific snippets,... (check what happens). TechComm CSS.css Stylesheet file TableStyles folder Topic Templates folder Content > Resources > Stylesheets > TechComm CSS.css Content > Resources > TableStyles Content > Topic Templates In the project's PROJECT folder: Default.flcts Conditional Text file Global_Variables.flvar Variables file Project > ConditionTagSets > Default.flcts Project > VariableSets > Global_Variables.flvar b. Right-click the folder or file name, and select Copy to Project. If copying a folder, the Select Folder dialog box opens. Writing Sample 2014 Laura Protano 11

16 2 Create the Flare Project MadCap Flare Select the folder in your project where you want to copy the contents of the specified folder and then click OK. Always select the folder one level above where the folder is located. For example, when you copy the Global_Images folder, select the Images folder because that contains the Global_Images folder. If copying a file, the Select Project Path dialog box opens. Select the folder in your project where you want to copy the file and then click OK. 12 Writing Sample 2014 Laura Protano

17 MadCap Flare 2 Create the Flare Project Because your project already contains all of these global project components, a Confirm Replace dialog box opens: c. Select the Do this for all conflicts check box, and then click Replace. The Copy to Project dialog box shows a list of the files to be copied to your project. d. Select the Keep file(s) synchronized (created mapping) check box, and then click OK. Writing Sample 2014 Laura Protano 13

18 2 Create the Flare Project MadCap Flare 6. Using Content Explorer, delete the following folders: Content > Topic Files > 1 Chap Content > Topic Files > 2 Chap Content > Topic Files > A Appendix Content > Topic Files > B Appendix Content > Topic Files > Glossary Example Content > Topic Files > DELETE Revision Table When you delete the preceding folders, Flare searches for components linked to the files. A Link Update window opens. Click Remove Links to remove the links to the folders and files you are deleting. Notes Do not delete the PrintOnly_Topics folder or the HelpOnly_Topics folder; these contain files that you will use for the print and Help output. To use any of the topic folders or files from the global project in the future, you can browse to the location of the global project on SharePoint and select that folder or file. For example, if you want to use the sample glossary file. 7. From the Project Organizer, delete the sample Table of Contents files: Global TOC.fltoc and Word TOC.fltoc (Project Organizer > TOCs). When you delete the TOC files, Flare searches for components linked to the files. A Link Update window opens. Click Remove Links to remove the links to the TOC files you are deleting. 8. Enter the Project Variables. In Project Organizer, open the Project Variables file (Variables > Project_Variables) and enter values for this project. These values appear on the Cover Page and other places. Close the variables file when complete. 9. Click the Save All tool on the Quick Access toolbar to save the project. 10. If you haven't already done so, set up a SharePoint Alert for the global project folder. This way you'll know when files change, and you can choose to synchronize your project files with the global project (Project ribbon > Synchronize Files tool). While in SharePoint Date View (the default view), float the cursor over the GlobalProject folder, and then click the down arrow to select Alert Me. Click OK to use the default Alert settings, or modify the settings first so that you only receive alerts once a day (recommended) or once a week. SharePoint sends you an alert when there is a change to the global project (new file, changed file, deleted file). See Appendix C for more information about synchronizing projects with the global project. ALERT! When you synchronize your project with the global project, never copy files from your project to the global project. Only copy files from the global project to your project. For more information, see Appendix C. 14 Writing Sample 2014 Laura Protano

19 3 3Import the Word Document to the Flare Project To import the prepared MSWord document into the new Flare project: 1. Open the project file in Flare. 2. On the Project ribbon, click the down arrow under the Import tool (left side of ribbon), and then select MS Word Documents. Writing Sample 2014 Laura Protano 15

20 3 Import the Word Document to the Flare Project MadCap Flare The Import Wizard opens. Under Import Options, notice that Import into this project is selected. 3. To use the import wizard, complete the following steps: a. Click Next. The Select MS Word Documents to import page opens. b. Clear the Link Generated Files to Source Files check box, click Add Files, browse to find the modified copy of the MSWord document that you will import, and then click Open. 16 Writing Sample 2014 Laura Protano

21 MadCap Flare 3 Import the Word Document to the Flare Project The Select MS Word Documents to import page shows the selected file in the MS Word Files list. c. Click Next. Flare scans the source document to collect a list of styles. d. When Flare finishes collecting styles, the New Topic Styles page opens. e. To generate new Flare topic files (that is, *.htm files) based on your heading styles, select those heading styles. For most import project, select Headings 1 through 3. Note If your project contains heading 4 topics with lengthy content, you might decide to create separate topic files for each of your heading 4 topics. In that case, you should also select Heading 4 in this step. If the heading 4 topics are short and you want to keep them contained within the parent Heading 3 topic file, then be sure to edit the topic file later and change the h4 heading style to h4.withinh3. For Help output, this style gives the Heading 4 a distinct appearance from the Heading 3 in the same Help topic. Most of our Word TOCs are designed to show 3 levels of headings only. As a result, the Flare TOC created by the import will NOT include Heading Writing Sample 2014 Laura Protano 17

22 3 Import the Word Document to the Flare Project MadCap Flare 4 topic files. You'll need to manually add them. f. Click Next. The Options page opens. g. Change the value of the Approximate Filename Length from 24 to 35, and then click Next. The Stylesheet page opens. 18 Writing Sample 2014 Laura Protano

23 MadCap Flare 3 Import the Word Document to the Flare Project h. Click Stylesheet to select the TechComm CSS.css file located here in the new project: \Project\Content\Resources\Stylesheets. i. Under Source Styles, select Don't Preserve MS Word Styles. j. Click Next. The Paragraph Style Mapping page opens. k. Map the MSWord paragraph styles to Flare CSS styles. The styles mappings from Word to Flare/CSS are located in the department's Team Docs folder on SharePoint. l. Click Next. The Character Style Mapping page opens Writing Sample 2014 Laura Protano 19

24 3 Import the Word Document to the Flare Project MadCap Flare m. Map the MSWord character styles to Flare CSS styles (span.<class>) as described in the Import Mapping document. n. Click Finish. Flare shows the import progress. When Flare completes the import process, the Accept Imported Documents dialog box opens. 4. Click Accept. 20 Writing Sample 2014 Laura Protano

25 MadCap Flare 3 Import the Word Document to the Flare Project The import process adds the following files to your project: Topic files. In Content Explorer, Flare adds a new folder with the same name as the imported MSWord Document. The new topic files are located in that folder. TOC file. See Project Organizer > TOCs. Import file. See Project Organizer > Import. Master Page. See Content > Resources > Master Pages. A copy of the TechComm CSS.css stylesheet file named TechComm CSS1.css. See Content Explorer > Resources > Stylesheets. 5. From Content Explorer, delete the following: The TechComm CSS1.css file (not TechComm CSS.css) created by the import process (Content > Resources > Stylesheets). During the deletion, you will be prompted to break the links. Click Remove Links. The <Imported_DocumentName.flmsp> Master Page file created by the import process (Content > Resources > MasterPages). Do not delete the global master page file. 6. If the project includes Visio source files, copy them to a Visio Source Files folder in the Project folder at the same level as the *.flprj file; do not place this folder in the Contents folder; if you do, it might inadvertently get included in the Help output files. Writing Sample 2014 Laura Protano 21

26 3 Import the Word Document to the Flare Project MadCap Flare 22 Writing Sample 2014 Laura Protano

27 4 4Organize Topics by Chapter To organize imported topics by chapter:: 1. With the Flare project file open, open Content Explorer in the left pane. 2. The imported topic files are located in a folder that has the same name as the imported MSWord document (for example, "EDI Module UG"). 3. Click the Show Files tool ( ). Content Explorer expands to show files for the selected folder in the right pane. Writing Sample 2014 Laura Protano 23

28 4 Organize Topics by Chapter MadCap Flare 4. In the Topic Files folder, create a folder for each chapter in your document. Refer to either the original Word document or the imported TOC file to see a list of chapter names and the topics included in each chapter. 5. Do the following to move the topic files to the appropriate chapter folder: a. Click the folder that contains the imported topic files so that you can view all files. b. Select one or more files that you want to move. c. Drag the files to the appropriate chapter folder under Topic Files. When you do this, Flare compiles a list of links that it needs to update and shows this list in a dialog box. Click Update Links. Notes You might need to rename some topic files for clarity. For example, if there are two topics with the same name in the Word document, they will names like Introduction.htm and Introduction1.htm in the Flare project. If you rename topic files, be sure to adjust the name of the heading within the topic, and the Topic Title (part of the topic file's properties) if needed. If you don't see a topic file for an entry in the TOC, right-click the TOC entry and select Properties in order to see which topic file the entry is linked to. Rename the topic file for clarity if needed. When performing memory-intensive tasks (for example, moving 20 files to a new folder), Flare can sometimes show an erroneous "Not Responding" message at the top of the application window. Wait for several minutes before using Task Manager to end the job, because Flare usually recovers on its own. 6. If there were any hard page breaks left in the import document, you could end up with topic files that contain only part of a topic. Copy and paste content as needed to move a topic's content into the appropriate topic file. 7. The import process creates topics for the imported Cover Page and Copyright Page with topic file names like EDI Module UG.htm, EDI Module UG1.htm. You can delete these because we will create a new cover page topic and contents topic based on topic files from the global project. Before you delete the topic files that contain the imported Word cover page and TOC, check whether the files contain any topic content and, if yes, move that content to the appropriate file. 8. Apply conditions to folders and files. For example, if you imported a chapter of test case scenarios that you want to appear in the PDF output, but not the HTML5 output, right-click the folder in Content Explorer, and select Properties. On the Conditional Text tab, select the PrintOnly check box. (The default HTML5 target is already configured to exclude content marked as PrintOnly.) 9. Delete the empty folder that previously contained the imported topic files. 24 Writing Sample 2014 Laura Protano

29 5 5Set Up the Project TOC Note The print TOC structure is generated based on the TOC proxy (part of the Contents.htm file) and not based on the TOC file. However, the Help Contents structure is based on the TOC file. The TOC file does contain many settings that impact the print output, such as chapter and page numbers. To set up the project TOC for an imported MSWord document: 1. In Project Explorer, open the default TOC created by the import process. 2. Adjust long TOC entry names so that they are not too long to appear in the Help TOC. (The TOC entry name can be different from the topic title and heading.) Also, modify duplicate TOC entry names to make them unique (for example, add the name of the parent topic in parenthesis after the topic name). For duplicate TOC entry names, also change the *.htm file name, and the heading within the topic for easier maintenance. For example, if the Word document has two topics named "Search," the import creates two topic files: Search.htm and Search1.htm. The TOC entries for both those topics will read "Search", and the first heading in each topic will be "Search." 3. During the import, if you selected to create new topic files for Heading 4 topics, then you'll need to manually add those topics to the Flare TOC (by default, the Flare TOC includes only same number of heading levels as the Word TOC). To complete this step, open Content Explorer, and drag to the Heading 4 topics to the correct location in the Flare TOC. 4. Open Content Explorer in the left pane. 5. Open Content > Topic Files > PrintOnly_Topics, and drag the Cover Page.htm and Contents.htm files to the beginning of the TOC, in that sequence. Writing Sample 2014 Laura Protano 25

30 5 Set Up the Project TOC MadCap Flare In the TOC, change the default name of the cover page from "Copyright" (the name of the first heading in that topic) to "Cover Page" for clarity. 6. Do the following to set up the Cover Page for print output (this had the conditional PrintOnly setting by default): a. In the TOC file, right-click the Cover Page and Copyright Page entry, and select Open Link. b. If your project includes a subtitle, select the correct tag and class for the subtitle based on your product line. The subtitle color varies by product line. Select one of the following: p.subtitle_generic p.subtitle_core p.subtitle_govt p.subtitle_sales p.subtitle_mm c. Save and close the Cover page topic file. 26 Writing Sample 2014 Laura Protano

31 MadCap Flare 5 Set Up the Project TOC d. In the TOC file, right-click the Cover Page and Copyright Page entry, and select Properties. This opens the TOC properties for the Cover Page TOC entry. e. Set the following values on the Printed Output tab: Break Type: Page Layout Break, Page Layout: Cover, Page Type: First Right. Click OK. Note For release notes or other technical documents that should not show the blue arrow graphic at the bottom of the cover page, set the Page Type to "Normal" instead of "First Right". 7. Do the following to set up the Contents page for print output: a. In the TOC file, right-click the Contents entry, and select Properties. This opens the TOC properties for the Contents TOC entry. b. Set the following values on the Printed Output tab: Break Type: Chapter Break, Page Layout: TOC, Page Type: First Right, Page Number: Reset to 3, Format: roman. Click OK. Writing Sample 2014 Laura Protano 27

32 5 Set Up the Project TOC MadCap Flare 8. For each chapter and appendix in the TOC, set the TOC properties as follows: a. Right-click the TOC entry, and then select Properties. The Properties dialog box opens. b. Set the following values on the Printed Output tab: Break Type: Chapter Break, Page Layout: Chapter, Page Type: First Right. For Chapter 1, also enter these values: Page Number: Reset to 1, Format: decimal. For Appendices, also enter these values: Page Number: Reset to {chapnum} {n}, Format: text. Note The appendix page numbering format shown above is not supported in Word output. Use Word output, use a separate TOC, and set the appendix page numbering to continue in decimal format from the previous chapter. c. Click Auto-numbers to open that tab. d. For Chapter 1, under Chapter Number, select Reset to: 1 and Format: decimal. 28 Writing Sample 2014 Laura Protano

33 MadCap Flare 5 Set Up the Project TOC e. For subsequent chapters, under Chapter Numbers, verify that Increment number is selected. f. For Appendix A, under Chapter Number, select Reset to: 1 and Format: alpha. g. For subsequent appendixes, under Chapter Numbers, verify that Increment number is selected. h. Click OK. 9. If your project requires a revision history table, do the following: a. Using Content Explorer, open the topic template NewTopic_RevisionHistory.htm (Content > Topic Templates), select File > Save As, and save the file to your Content > Topic Files > PrintOnly_Topics folder. b. Enter revision information in the table in the new topic file, and then save changes. c. Add the revision history topic file to your TOC as the last item in the TOC. Position the new entry at the same level as a chapter or appendix. d. Right-click the TOC entry for the revision history table, select Properties, and then set the following values on the Printed Output tab: Break Type: Chapter Break, Page Layout: Chapter_NoHeaderNums, Page Type: First Right, Page Number: Reset to RH {n}, Format: text. 10. Save changes to the TOC file. 11. Modify the Project Properties to point to your TOC. To do so, select Project ribbon > Project Properties. The Project Properties dialog box opens. On the General tab, enter your TOC as the Master TOC. Writing Sample 2014 Laura Protano 29

34 5 Set Up the Project TOC MadCap Flare 30 Writing Sample 2014 Laura Protano

35 6 6Clean Up the Imported Content From the project's TOC file, open each book and topic, review the content, and fix the following issues if applicable: Delete Empty Tags 31 Format Imported Tables 31 Format Imported Lists 33 Format Imported Images 34 Format Imported Notes 35 Fix Imported Text Cross-References 35 Apply New Styles 36 Delete Empty Tags Delete empty tags, and occurrences of <p></p> that appear highlighted in yellow within the text (these result from hard page breaks in the source Word document). Format Imported Tables Do the following to apply formatting to each imported table: 1. Select the Table element in the Blocks section of the editor. 2. Right-click and select Table Properties. Writing Sample 2014 Laura Protano 31

36 6 Clean Up the Imported Content MadCap Flare The Table Properties dialog box opens. By default, an imported table has 0 header rows. 3. Change Number of header rows from 0 to Under AutoFit Behavior, select Auto Fit to Window, and enter 95 % (wide table) or 60 % (narrow table). In lists that include both wide images and wide tables, enter a table width of 100% for best left-alignment. 5. Under Align, select (default). 6. Under Table Style, select either Regular table (not alternating row color), or AltRowTable (for a table with alternating row colors). Do not select a style class. 7. Click OK. 8. Copy your header row content to the header row, and then delete the empty row. (You can also drag the tr block to the thead block and delete the empty tr row.) By default, the mapping process should set all table content to the p tag style, and then the table style sets the format for the header row and other content. If an imported table contains a list (bullets or number), see "Format Imported Tables", next. 32 Writing Sample 2014 Laura Protano

37 MadCap Flare 6 Clean Up the Imported Content Format Imported Lists There are steps you can take during preparation of the import document to greatly reduce the amount of list reformatting required after an import. See "Prepare the Word Document for Import" on page 3. If the source Word document included a list with a paragraph style other than List Paragraph, then Flare imports each item in the list as a single list item (li tag) within its own list tag (ul or ol tag), rather than grouping related list items in a single list. This needs to be fixed so that all list items in the same list are within a single ul or ol tag. The import process does not retain special formatting applied to "continue" list items (i.e., to hide the bullet or number), or a "last" list items (extra space below the item). Those styles need to be re-applied. The import process does not format nested list items correctly, those also need to be fixed. Note When fixing a nested table, it helps to have the MSWord source document open during this step so that you can see the formatting of the original list. If there are images within an imported list, the image also needs to be formatted correctly. Do the following to fix formatting for an imported list: 1. Select each ol or ul tag in the Blocks section of the editor, right-click, and select Unbind. This changes each item in the list to a p tag. 2. Select all the p tags to include in the list, and then select Home ribbon> Bullet List tool. The default list type is square bullets as configured in our style sheet. For a numbered list, click the drop-down and change the selection to Numbered List. 3. For a nested list within the list, select the nested items in the editor, and then click the Indent Items tool (Paragraph pane of the Home ribbon). If the nested list is of the same type (i.e., numbered or bulleted) as the parent list, then this step is complete. If the nested list is a different type (for example, bullets under a numbered item), then select Numbered List or Bullet List from the Bullet List tool. 4. For a continued item (that is, a list item with no bullet or number) or an image within a list, select the li tag within the Blocks section of the editor, then select the li.continue or li.continuelast style (Home ribbon > Styles pane). Note If you apply a continue style within a numbered list (ol), then you need to adjust numbering for subsequent li items. To adjust numbering, position the cursor in the paragraph, and then select Set Item Number from the List Actions tool (Paragraph pane, Home ribbon). 5. For the last item in a list, select the li tag within the Blocks section of the editor, and then select the li.last style. Writing Sample 2014 Laura Protano 33

38 6 Clean Up the Imported Content MadCap Flare 6. For a note within a list, apply the li.continue style. Then, right-click the li item (in the Blocks section of the editor), and select Make Paragraph Item. This adds a p tag within the li tag. Then, apply the style p.importnote. 7. For a list item (li or li.continue) that you want to keep with a subsequent item such as an image or sublist, apply one of the following classes: li.leadin or li.continueleadin. The first option shows the number or bullet; the second option hides the number or bullet. 8. For a list that imports correctly as a single list, but items are at the wrong level (e.g., show level 2 bullet icons instead of level 1 bullet icons), do the following: a. Position your cursor within the li block and select the Home ribbon > Outdent Items tool. The li tag changes to a p tag and the block is removed from the list. b. After all items are outdented, select all the blocks that should be list items in a single list, and use the Home ribbon > Bullet list tool to apply bullets or numbering. For information about how to format the images in a list, see "Format Imported Lists", next. Format Imported Images To format imported images, do the following: During the import, a paragraph that contains an image is mapped to the Flare style p.graphic which centers the image in print output and left-justifies it in Help. For small or narrow images that should be left-aligned in print, apply the class p.graphicsmall to the paragraph that contains the image. If the paragraph that contains the image does not use the style p.graphic or p.graphicsmall, apply the appropriate style. (Images in lists have their own styles, as described later in this section.) For images in paragraphs (not lists), apply Flare styles to the img tag as needed: Apply img.border to images that require a border. Apply img.bg to images that require a gray background. For images in lists, apply Flare styles to the li tag that contains the image, as well as the img tag as needed: To hide the number or bullet, and add extra space after the image, apply li.continuelast to the li tag that contains the image. If the image is wide, constrain the width by applying the img.list style to the img tag. If the image is wide and requires a border, apply the img.listborder style to the img tag. If the image source file includes a red border as was the old convention, use an image editor such as SnagIt or Capture to remove the border. Then, apply an image class with a border to the img tag (e.g., img.border or img.listborder). To determine the name of the image to edit, hover your cursor over the img block; the image name displays. From Content Explorer, you can browse to select the image (Resources > Images), right-click the image and then select Open with > SnagItEditor.exe (or other program). 34 Writing Sample 2014 Laura Protano

39 MadCap Flare 6 Clean Up the Imported Content Tip! Use SnagIt's Custom Trim tool (Image ribbon > Resize menu) to remove 1 px from each side of an image in order to quickly remove a red border. You can repeat the command multiple times if the border is wide, or set a wider custom trim. Make sure imported inline images (e.g., an icon in a sentence) appear in correct location and not above the target paragraph. If the image is a hyperlink, apply the img.linknoborder style to the img tag. (This fixes a known IE bug where a red border appears around images configured as hyperlinks.) Format Imported Notes In paragraphs that have the format p.note, apply the inline style span.noteheading to the text "Note" or "Notes", delete the colon, and adjust the spacing between the Note Heading and the content (2 hard spaces if plural; 4 otherwise). To insert a hard space, type Shift+spacebar. Fix Imported Text Cross-References Do the following to find and fix cross-references imported from MSWord that have the style span.importref applied (these are easy to locate because they have red formatting): 1. Position your cursor immediately before the span containing the imported reference text and select Insert ribbon, Cross Reference. You can also select the Insert a Cross Reference tool in the toolbar at the top of the open topic: 2. In the Insert Cross Reference dialog box, select the target topic., and then select one of these two xref styles in the Cross Reference Properties section: Madcap:xref.topicNameOnly -- For references to chapters. This style links to the main topic of the chapter (that you have selected) without a page number reference when the PDF is generated. Madcap:xref -- For references to topics. This style links to the topic that you have selected in the upper part of the dialog and automatically adds the text on XX page to the cross reference sentence when the PDF is generated. (The page number does not appear in the Help output.) If you don't select an xref format, Flare applies this default format. Writing Sample 2014 Laura Protano 35

40 6 Clean Up the Imported Content MadCap Flare The following figure shows an example of the Insert Cross Reference dialog box: 3. Right-click the span tag ( ) that contains the original import reference text, and select Delete. Apply New Styles For imported Word documents that did not use the most current paragraph and character styles (for example, Lead In Sentence, Screen Name, etc.), apply the equivalent Flare styles. For example, apply p.leadinsentence to a sentence that precedes a list, image, or table. 36 Writing Sample 2014 Laura Protano

41 7 7Set Up the PDF Output To set up the PDF output: 1. In Project Organizer, double-click the PDF target to open it (Targets > PDF). 2. On the General tab, enter an Output File name. For example, Benefits Module UG. Due to a known issue: if the output file name includes the period (.) character, then the output file name must include the *.pdf extension (e.g., Benefits Module v5.4.0 UG.pdf). 3. On the Conditional Text tab, verify that the condition ScreenOnly has the Exclude condition selected. 4. On the Variables tab, adjust any project-level variables for this target if needed. 5. On the PDF Options tab, enter the following values: Document Properties, Title: Enter the document title as it will appear in the Acrobat Reader title bar Document Properties, Author: Enter "<Company Name>" PDF Tagging: If your project must meet section 508 accessibility requirement, select this check box. Initial View, Magnification: Fit Page Initial View, Navigation: Page Only Initial View, Page Layout: Two-Up (Cover Page) 6. Save and close the PDF target file. 7. Create a PDF from the original document (Word) and from Flare, and compare for differences (for example, missing content, headers, images, and so on). Note F7 opens Spell Check tool in Flare (located on Tools ribbon). Writing Sample 2014 Laura Protano 37

42 7 Set Up the PDF Output MadCap Flare 38 Writing Sample 2014 Laura Protano

43 8 8Set Up the HTML5 Output To prepare the Flare project for Help output: 1. Open the Flare project. If you have not synched the project with the global project in awhile, sync it first. 2. Open the HTML5 skin (Project Organizer > Skins > HTML5), and do the following: a. Update the Caption on the General tab. The Caption appears in the browser tab when the Help is open in a browser window. The maximum Caption length that the browser tab shows is approximately 20 characters (for example, "ProductX Help"). b. Under Features, select to show the TOC tab only; keep all other tabs hidden. c. Under Options, select Automatically Synchronize TOC. The following figure shows an example of the HTML5 Skin Editor: Writing Sample 2014 Laura Protano 39

44 8 Set Up the HTML5 Output MadCap Flare 3. Do the following to enter the name of the Help output file: a. Open the HTML5 target file (Project Organizer > Targets, and then double-click the HTML5 target). b. On the General Tab, enter the Output File name. For example, for the Benefits module, enter Benefits Module Help. The resulting output file name will be: Benefits_Module_ Help.htm. c. On the Advanced tab, verify that the Exclude content not linked directly or indirectly from the target check box is selected. The following figure shows an example of the HTML5 Target Editor: 4. Do the following to create a home page for the module: a. Using Content Explorer, browse to find the Global_Home.htm file (Content > Topic Files > HelpOnly_Topics), and then rename it to reflect your project (e.g., Benefits_Help_Home). b. Open the Help Home topic. 40 Writing Sample 2014 Laura Protano

45 MadCap Flare 8 Set Up the HTML5 Output The new topic opens in the right pane as shown in the following figure: c. In the Help Home topic, do the following: i. Rename each h2 value to reflect the major sections in your Help. ii. iii. Update the descriptive text below the section name. For each section, right-click the Go to link, and select Edit Hyperlink. Then, change the link to point to the appropriate section, and adjust the tool tip for the link. d. Do the following add the home page topic to the TOC: i. Open the project TOC in the right pane (Project Organizer > TOCs, and then doubleclick the TOC file to open it). ii. iii. Open Content Explorer in the left pane. Drag the topic file from the Content Explorer pane to the top-most position in the TOC. iv. Rename the new TOC Entry (e.g., Benefit Module Help Home). 5. If a topic has subtopics that are contained in separate topic files, make sure the topic includes links to the subtopics. The content can include cross-references to the topics as applicable, or you can add a Help-only list of links. For example, if an H1 topic has three H2 subtopics that are each contained in a separate topic file, update the H1 topic so that it includes a link to each of the H2 subtopics. If the links are not applicable for print output, apply the "Screen-Only" condition tag. Methods to add topic links include: Insert contextual cross-references, or a bulleted list of cross-references. For more information, refer to the MadCap Flare Help. Writing Sample 2014 Laura Protano 41

46 8 Set Up the HTML5 Output MadCap Flare Create Concepts (View ribbon > Concept Window), associated related topics with the same concept, and then insert a Concept Link list (Insert ribbon > Concept Link (A-link) tool). An advantage to this approach is that you don't have to manually update the "Related Topics" link in each topic whenever you change the topics associated with the Concept. For more information, refer to the MadCap Flare Help. Always apply the ScreenOnly condition tag to the paragraph that contains the Concept Link list. Insert a Related Topics link list (Insert ribbon > Related Topics Control tool). For more information, refer to the MadCap Flare Help. Always apply the ScreenOnly condition tag to the paragraph that contains the Related Topics list. Insert a minitoc proxy. This is the fastest way to add a list of child topics to a parent topic, and we should use it whenever we can. An advantage to this approach is that the list updates automatically when you change child topics. This procedure is described below. Manually add a list of links. The only reason you would use this method is if the list of links is long (more than 5 links), and you want to format them in a table so that users won't have to scroll through a long list. This procedure is described below. To insert a minitoc proxy: a. Add the lead-in sentence to the Help topic (for example, "This topic describes the following tasks:". Style it with p.leadinsentence. b. Position the cursor where you want to insert the minitoc proxy. c. Select Insert ribbon > Proxy > Mini Toc Proxy. The MiniTOC Proxy dialog box opens: f. Select a TOC Depth of 1, and then click OK. g. Apply the condition tag ScreenOnly to both the lead-in sentence, and the minitoc proxy. 42 Writing Sample 2014 Laura Protano

47 MadCap Flare 8 Set Up the HTML5 Output Notes You can copy the conditionalized lead-in sentence and minitoc proxy from topic to topic (even from an H1 to an H2) to quickly add link lists to other topics. Just be sure to modify the lead-in sentence content as needed. Use the List_Subtopics_MiniTOCProxy snippet to quickly insert a generic lead-in sentence and minitocproxy. Both parts of the snippet have the ScreenOnly condition tag applied. To manually add a list of links: a. Add the lead-in sentence to the Help topic (for example, "This topic describes the following tasks:". Style it with p.leadinsentence. b. Insert a one-row table of the type "TopicLinks" (no heading row). c. Within the table, insert the cross-references to the topics (from the Insert ribbon). Select the xref format: "topicnameonly". d. After you insert all xrefs, apply the bullet style. Notes If there are more than 5 links, use two columns and set one of the columns to take up 50% of the available space. If there are more than 10 links, use three columns, and set two of the columns to take up 33% of the available space. Use the List_Subtopics_Table snippet to quickly insert a generic lead-in sentence and a table formatted for inserting a long list of subtopics. Both parts of the snippet have the ScreenOnly condition tag applied. e. Apply the condition tag ScreenOnly to both the lead-in sentence, and the table of links. 6. If a topic has subtopics that are contained in the SAME topic file (for example, if you have separate topic files for heading levels 1 to 3, but the heading 4 topics are contained within the heading 3 topic files), adjust the headings assigned to the lower-level subtopics so that they will appear correctly in the Help output. Make the following adjustments: h2 heading within an h1 topic Change style to h2.withinh1 h3 heading within an h1 topic Change style to h3.withinh1 h3 heading within an h2 topic Change style to h2.withinh2 h4 heading within an h2 topic Change style to h4.withinh2 h4 heading within an h3 topic Change style to h4.withinh3 7. If the source document includes one or more appendices, make the following adjustments for the Help output: Writing Sample 2014 Laura Protano 43

48 8 Set Up the HTML5 Output MadCap Flare a. Rename the appendix TOC entry to remove the Word "Appendix." The following figure shows an example of a TOC entry that needs to be renamed: Note If the guide includes more than one appendix, create a new TOC book named "Reference" and then nest the appendix topics within the Reference book. Create a new topic for the Reference book, and link the book to the topic. The only content in the Reference book topic will be links to the appendices (see the Global Project for an example of a Reference book topic). Use Flare's Content Explorer window (not the TOC) to apply the condition ScreenOnly to the new Reference topic. b. From the TOC, open the TOC properties for the entry and edit the Topic Title (used only in Help output) to remove the word "Appendix." The following figure shows an example of a Topic Title to rename. (You can delete the Topic Title, and Flare will use the first Heading in the topic as the Topic Title.) c. Open the topic, and apply the condition tag PrintOnly to the text "Appendix:" and the space immediately following it. To apply conditional text, select the text, and then, from the Home ribbon, click Conditions. 44 Writing Sample 2014 Laura Protano

49 MadCap Flare 8 Set Up the HTML5 Output The following figure shows an appendix heading (h1) with the PrintOnly condition applied: The following figures shows how the appendix will appear in HTML5 and PDF output after you make the adjustments: Writing Sample 2014 Laura Protano 45