Getting Started in Arbortext and Documentum. Created by Michelle Partridge Doerr April 21, 2009

Transcription

1 Getting Started in Arbortext and Documentum Created by Michelle Partridge Doerr April 21, 2009

2 Table of Contents 1.0 Introduction to the CMS Introduction to Arbortext Introduction to Documentum Explanation of how Arbortext and Documentum work together What projects require Arbortext and Documentum Where to find other tools for projects About the Interface Where to find Arbortext and Documentum systems on your desktop Features of Arbortext Catalogue of Arbortext toolbar icons Catalogue of tags in Arbortext Features of Documentum Desktop Features of the Docbase Browser Performing Tasks Access files using Arbortext Check out a file in Documentum Check in a file in Documentum Nest sections in Arbortext Add and format headings in Arbortext Apply and delete tags in Arbortext Add IDs to tags Insert a section in Arbortext Insert a paragraph in Arbortext Insert links in Arbortext Insert footnotes and footnote references in Arbortext Insert rules in Arbortext Use tables in Arbortext Insert and format a list in Arbortext Reference sections in Arbortext... 47

3 3 4.0 References Catalogue of ID conventions... 49

4 1.0 Introduction to the CMS Introduction to Arbortext Typically, most technical publications are created as one large file with both text and graphics, which can only be worked on by one person at a time. Information that applies to multiple documents is either rewritten from scratch or copied and pasted, which creates redundant copies of the same or similar information. Every document is manually formatted and laid out for publishing. When the publications have to be updated to incorporate changes, changes require searching for and updating each instance of the same information and then manually reformatting all affected documents. AICPA has a more efficient process using Arbortext Editor version 5.2, an HTML and XML authoring tool. Arbortext looks and works like familiar word processing software and allows authors to create reusable chunks of information (text, graphics, data). Authors then combine those chunks to make documents, and the same chunks can be used in several separate documents. Content Managers use Arbortext to create HTML and XML versions of AICPA s professional publications. Arbortext has a word processing interface, which means that you don t need to have extensive knowledge of mark-up languages to use the software. 1.2 Introduction to Documentum AICPA uses Documentum Desktop version 5.3 as its content management system. The Documentum system lets you access, use, reuse, and distribute information quickly and easily by storing it in small packages. Publications are broken into several sections so that you can access only the content that is relevant to you. Using the Documentum system, you store information of any kind text, graphics, and scanned images in repositories called Docbases. A Docbase is a secure repository for storing files. All files used in Documentum are stored in Docbases. Each Docbase provides security, services, and tools for sharing content among different users. Each Docbase provides automated processes that control the lifecycles of files and the delivery of files. 1.3 Explanation of how Arbortext and Documentum work together We use Arbortext to mark up AICPA professional publications in HTML and XML. We use Documentum to manage all of the professional publications content. Whenever we need to work on a publication, we have to find the file in Documentum. All of the content we manage at the AICPA is contained in the Proflitxml Docbase. When you open the Arbortext interface, you connect to Documentum and browse for the file you wish to edit.

5 5 1.4 What projects require Arbortext and Documentum Any time we make updates to the professional literature, we use both Arbortext and Documentum. The following table shows our publication line and how often they are updated. Publication How it is updated How often it is updated Technical Manager (TM) Paperbacks produced once a marks up the previous year version of the guide with the updates and sends us the MS Word doc with tracked changes. We make the tracked changes in the CMS. New guides are received as MS Word files. Audit Guides and Audit and Accounting Guides Audit Risk Alerts Checklists Practice Aids Professional Standards Technical Practice Aids PCAOB Standards and Related Rules New alerts are received as Word files from Editorial. We convert the file and replace the old version with the new. Technical Manager (TM) marks up the previous version of the guide with the updates and sends us the MS Word doc with tracked changes. We make the tracked changes in the CMS. New Practice Aids are received as MS Word files from Editorial. New standards are received as MS Word files from Editorial. Conforming changes are received in a list via . New standards are received as MS Word files from Editorial. Conforming changes are received in a list via . We convert new releases from PDF. Conforming changes are received in a list via . Paperbacks produced once a year Paperbacks produced once a year New Practice Aids are received intermittently throughout the year. Updates received intermittently/ Looseleaf reports generated several times a year. Updates received intermittently/ Looseleaf reports generated several times a year. Updates received intermittently/ Looseleaf reports generated several times a year. Financial Statement (Collection of looseleaf Looseleaf reports are

6 6 Preparation Manual versions of checklists.) generated several times a year. Audit and Accounting Manual (Looseleaf version of paperback) Updated once a year in its entirety Audit and Accounting Guides (Collection of looseleaf versions of guides and Looseleaf reports are generated several times a Accounting Trends and Techniques alerts.) (Looseleaf version of paperback) year. Updated once a year in its entirety 1.5 Where to find other tools for projects We upload all MS Word files to our team s Document Library on SharePoint. The Word Import tool automatically converts MS Word documents into HTML Arbortext files. It is listed within All Programs in the start menu. All the paperback versions of the previous year s guides and alerts and all the looseleaf binders are located in the empty cube across from Michelle Ortiz. All project management tasks are located in the Content Management Task List on the team s SharePoint page.

7 2.0 About the Interface Where to find Arbortext and Documentum systems on your desktop Once the software is installed on your laptop, icons for both systems will appear on your desktop. To access either system, simply double click the appropriate icon. The Arbortext icon looks like this: And the Documentum icon looks like this: 2.2 Features of Arbortext At the AICPA, you will use the Arbortext toolbar (top of the screen), the nesting window (left side of screen), and the mark-up window (right side of screen). Typically, you work primarily with the toolbar and mark-up window. You can use the nesting window to reveal the nesting in your document (see section 3.4, Nest sections in Arbortext).

8 8 2.3 Catalogue of Arbortext toolbar icons The toolbar is represented in the preceding screen shot. You probably recognize the editing icons (New, Open, Save, Find, Cut, Copy, and Paste). The markup icons appear on the next row, followed by the table icons. The markup icons we use most frequently are circled: Insert Markup: This icon displays a list of tags that we use to mark up the text (see section 2.4, Catalogue of tags in Arbortext). Modify Attributes: This icon allows you to enter information about the tags, like IDs and roles. Delete Markup: This icon deletes the tag around selected text. Check Correctness: This icon checks for broken links and nesting errors in the document. To view all the toolbars in the preceding screenshot: 1. Click on the View button in the toolbar. 2. Hover your cursor over Toolbars 3. Ensure that all toolbars (Edit, Markup, Table, and Application) are selected.

9 9 2.4 Catalogue of tags in Arbortext The tags we use are located in the Insert Mark-up window. The following table describes several tags that we use frequently in professional publications. chapter section sectioninfo title titleabbrev para footnote footnoteref hrule newline olink ulink inserts a new chapter segment; the highest level of segments; contains sections inserts a new section segment inserts the title and titleabbrev tags inserts titles inserts titles for storage information inserts a new paragraph inserts a footnote inserts a reference to an existing footnote in the same document inserts a horizontal rule inserts a new line of text within a paragraph inserts a link to internal sources inserts a link to external sources

10 10 tab inserts a tab itemizedlist inserts a bulleted list table inserts a table 2.5 Features of Documentum Desktop We use Arbortext to access Documentum through the Docbase Browser (described in the following section). Occasionally, we use the Documentum Desktop to check in files (using Checked Out Files ). You can also access the Proflit Docbase to view files (using Docbases ). 2.6 Features of the Docbase Browser The DocBase Browser displays the available Docbases in Documentum. It appears when you browse for a file in Arbortext (see section 3.1, Access files using Arbortext). To search for a file, expand the Proflitxml Docbase. Right-clicking on a file gives you options for working with the file. We typically use only the following options: View: View the file without the ability to make changes (like the Read Only function in MS Word) Edit: Open the file to make changes. Check In: Check in the file and save your changes. Cancel Check Out: Check in the file without saving your changes.

11 The Docbase Browser displays a key next to sections you currently have checked out. 11

12 It displays a lock next to sections other people currently have checked out. 12

13 13 The Docbase Browser window needs to remain open while you have files checked out. If you close the browser while you have files check out, Documentum will save the previous version of the file (and your changes will be lost). Think of the browser like a gate. You need the browser open to get to the files. If you close the gate, you can t get to the files any more. When you have checked in all the files you were working on, it is safe to close the browser.

14 Performing Tasks 3.1 Access files using Arbortext 1. Double click on the Arbortext icon on your desktop. 2. In the new window, click on the Documentum button in the menu tool bar. 3. Choose Connect. 4. In the new window ( Log On to Docbase ), choose Proflitxml from the drop-down menu for the Docbase option. Ensure that the Use Windows Login box is selected. Click Log On. 5. A message should appear along the bottom of the main window: User Name Connected to Arbortext Adapter to Documentum/XML. This means that you re connected to the Documentum CMS. 6. Click on the Documentum button in the menu tool bar again. 7. Click Browse. The Docbase Browser window will open. 3.2 Check out a file in Documentum (Continued from section 3.1, Access files using Arbortext) 1. In the Docbase Browser, expand Proflitxml to display the folders.

15 15 2. Expand the folder of the publication you wish to work on until you reach the section of content you wish to check out. To expand, simply click on the plus sign to the left of the section. If a minus sign is displayed, the section cannot be expanded. 3. Click on the section once to select it. Right click once on the section to open a dialogue box. 4. In the new dialogue box, choose Edit. 5. In the new window, ensure that Download and check out descendents is selected and click Check Out. 6. A window with a progress bar will appear, and then a new window will open with the content displayed. You may begin to make changes.

16 Check in a file in Documentum 1. When you have completed your edits to the content, select the Docbase Browser window. 2. Click on the checked-out section once to select it. Right click once on the section to open a dialogue box. 3. In the new dialogue box, click Check In (click Cancel Check-out if you wish to save the previous version of the file) 4. In the new window, ensure that Make this the current version and Request full-text indexing are selected and click Check In. 5. A window with a progress bar will appear until the action is complete.

17 Nest sections in Arbortext The majority of the publications we produce at AICPA are made up of chapters. These chapters are organized within books, which is the largest section of content we work with. Within these chapters are sections, and within the sections are other sections, paragraphs, tables, graphics, and the like. Nesting refers to the hierarchy of these chunks of content. Your guide to what should be nested within sections is the MS Word document. It contains levels of headings that show which lower-level heads are nested within which upper-level heads (see section 3.5, Add and format headings in Arbortext, for a list of the heading styles we use). To nest a section within another section: 1. Find the end tag of the section you want to nest a new section within. 2. Place your cursor inside that end tag. 3. Click the Insert Markup button in the toolbar. 4. In the new Insert Markup window, select the section tag. 5. Click the Insert button. You can use the left window to collapse sections to make it easier to see how content is nested. To collapse a section, simply click on the box containing the minus symbol.

18 18

19 Add and format headings in Arbortext In our professional literature, we use headings to correspond to sections of content. Therefore, each section has a heading, which we put inside a title tag (see section 3.8, Insert a section in

20 20 Arbortext). The following table lists the types of sections and their roles and the corresponding title roles. Section Section Role Title Role Chapter ls_level_2 ps_section_heading Section ls_level_3 ps_main_heading Nested section ls_level_4 ps_sub_heading Next nested section ls_level_5 ps_subsub_heading Next nested section ls_level_6 ps_subsubsub_heading Lowest nested section ls_level_8 ps_para_number To change the role of a title tag: 1. Place your cursor within the title tag 2. Click on the Modify Attributes button in the toolbar. 3. In the new Modify Attributes window, select the appropriate role in the drop-down menu. Click the OK button.

21 Apply and delete tags in Arbortext To apply tags to existing text: 1. Use cursor to highlight the text you want to tag. 2. Click the Insert Markup button in the toolbar. 3. In the new Insert Markup window, select the tag you wish to insert from the menu. 4. Click the Insert button.

22 22 To delete existing tags: 1. Place your cursor within the tag you wish to delete. 2. Click the Delete Markup button in the toolbar (see section 2.3, Catalogue of Arbortext toolbar icons). 3.7 Add IDs to tags In order for Documentum to catalogue all the content we work with, we need to add IDs to the tags we use in Arbortext. The IDs are like directions that tell Documentum which document you want that particular piece of content to be part of. The tags that need to be identified are chapter, section, footnote, and footnoteref tags because these are chucks of content that can be referenced among documents. To add an ID to a tag, simply: 1. Place your cursor inside the tag you wish to identify. 2. Click the Modify Attributes button in the tool bar. 3. In the new Modify Attributes window, in the id: space, type the ID according to AICPA s conventions. 4. Click the OK button.

23 23 Refer to section 4.1, Catalogue of ID conventions, to see a catalogue of AICPA s ID naming conventions. 3.8 Insert a section in Arbortext 1. Place your cursor within the previous section tag or directly after it (depending on whether you want the new section nested [see section 3.4, Nest sections in Arbortext]). 2. Click the Insert Markup button in the toolbar. 3. In the new Insert Markup window, select the section tag and click the Insert button 4. In the new Modify Attributes window, complete the id and role sections and click the OK button.

24 24 5. Place your cursor within the new section tag you inserted. 6. In the Insert Markup window, select the sectioninfo tag and click the Insert button. 7. Place your cursor within the new sectioninfo tag you inserted. 8. In the Insert Markup window, select the titleabbrev tag and click the Insert button. 9. Place your cursor within the new titleabbrev tag you created. Type the title of the section. 10. Place your cursor outside and to the right of the new titleabbrev tag you created. 11. In the Insert Markup window, select the title tag and click the Insert button. 12. Place your cursor within the new title tag you created. Type the title of the section. 13. Leaving your cursor within the title tag, click on the Modify Attributes button in the toolbar. 14. In the new Modify Attributes window, select the appropriate role from the drop-down menu (see section 3.5, Add and format headings in Arbortext) and click the OK button. 3.9 Insert a paragraph in Arbortext 1. Place your cursor where you wish to insert a new paragraph (for example, after the sectioninfo tag in a new section or after an existing para tag in an existing section). 2. Click on the Insert Markup button in the toolbar. 3. In the new Insert Markup window, select the para tag and click the OK button.

25 25 4. Place your cursor within the new para tag you created. 5. Click the Modify Attributes button in the toolbar. 6. In the new Modify Attributes window, select the appropriate role from the drop-down menu and click the OK button. (See the following table for a list of commonly used paragraph roles.)

26 26 ps_para_number ps_indent_0 ps_indent_2 ps_indent_hang_2 ps_indent_hang_4 ps_table_center For the first paragraphs within a numbered section For paragraphs within unnumbered sections (an appendix, notice to readers, or preface) For paragraphs following the first paragraph within a numbered section For paragraphs of block text (used for quotes longer than 5 lines) For numbered and lettered lists For secondary numbered and lettered lists For table titles 3.10 Insert links in Arbortext There are two types of links in Arbortext: olink and ulink. The olink is an internal link, meaning it links to other literature we have within Documentum. All AICPA literature can be linked in this manner. The ulink is an external link, meaning it links to anything available on the Web that has a URL. To insert an olink (internal link): 1. Using your cursor, select the text you wish to link. 2. Click the Insert Markup button in the toolbar. 3. In the new Insert Markup window, select the olink tag 4. Click the Insert button.

27 27 5. In the new Modify Attributes window, select the appropriate targetdoc from the drop-down menu (see table in section 4.1, Catalogue of ID conventions). The target doc is the general document within which the content you are linking is located. 6. Type in the appropriate targetptr in the space provided. The target pointer is the ID of the content you are linking (see table in section 4.1, Catalogue of ID conventions). 7. Click the OK button.

28 28 To insert a ulink (external link): 1. Using your cursor, select the text you wish to link. 2. If the text is a URL, press the Ctrl and C keys to copy the text. 3. Ensuring that the text is still highlighted, click the Insert Markup button in the toolbar. 4. In the new Insert Markup window, select the ulink tag 5. Click the Insert button.

29 29 6. In the new Modify Attributes window, in the url: space, type the URL, including or press the Ctrl and P keys to paste the URL. 7. Click the OK button.

30 Insert footnotes and footnote references in Arbortext In Arbortext, footnote tags and text appear within the content as a shaded section of text. If you wish to repeat the same footnote content elsewhere in the section you re working in, you insert a footnote reference, which creates a link to the original footnote. To insert a footnote: 1. Place your cursor at the point in the text where you want the footnote to appear. 2. Click the Insert Mark-up button in the toolbar. 3. In the new Insert Markup window, select the footnote tag. 4. Click the Insert button.

31 31 5. In the new Modify Attributes window, type the footnote ID in the id: space and the footnote label in the label: space. In the role: space, select from the drop-down menu either character (if the footnote label is a symbol) or number (if the footnote label is a number). 6. Click the OK button.

32 7. Place your cursor within the new footnote tag to the right of the footnote label. 8. In the Insert Mark-up window, select para. 9. Click the Insert button. 10. Type the footnote text inside the para tag. 32

33 33 To insert a footnote reference: 1. Place your cursor at the point in the text where you want the footnote reference to appear. 2. Click the Insert Mark-up button in the toolbar. 3. In the new Insert Markup window, select the footnoteref tag. 4. Click the Insert button.

34 34 5. Click the Modify Attributes button in the toolbar. 6. In the new Modify Attributes window, type the ID of the footnote you want to reference in the linkend: space and the footnote reference label in the label: space. 7. Click the OK button.

35 Insert rules in Arbortext We use horizontal rules in our documents to separate blocks of text. You will use them most often in checklists to set apart Notes and Practice Tips. They can only be used inside para tags. To insert a horizontal rule: 1. Place your cursor within the para tag where you want the rule to appear. 2. Click the Insert Mark-up button in the toolbar. 3. In the new Insert Markup window, select the hrule tag. 4. Click the Insert button.

36 36 5. Click the Modify Attributes button in the toolbar. 6. In the new Modify Attributes window, select from the drop-down menu in the role: space either rs_full (for a rule that spans the entire page) or rs_half for a rule that spans half of the page. 7. Click the OK button.

37 Use tables in Arbortext Insert a table Tables should be inserted outside of para tags but within the section that precedes it (as opposed to within its own section) because it should be nested within a section. To insert a table: 1. Place your cursor outside the para tag you want the table to appear after. 2. Click the Insert Mark-up button in the toolbar. 3. In the new Insert Markup window, select the table tag. 4. Click the Insert button. 5. In the new Insert Table window, select the number of columns and rows from the menus. 6. Click the OK button.

38 38 7. Place your cursor inside one new entry tag. 8. In the Insert Markup window, select para. 9. Click Insert

39 Repeat steps 7 9 for each entry tag. 11. Type the text for each cell inside each para tag. Format a table There are two ways to view tables: with tags or with the grid lines. You can choose the view that you find easiest to use. To view all the table tags (using table markup ): 1. Click View in the toolbar. 2. Position your cursor over Tables. 3. In the new window, click Table Markup to select it.

40 40 To view the table grid without tags: 1. Click View in the toolbar. 2. Position your cursor over Tables. 3. In the new window, click Table Markup to deselect it. Formatting a table in Arbortext is similar to the process for formatting a table in MS Word. The Table button in the toolbar contains the following options: Insert a column or row Delete a column or row Span (merge) cells Unspan (divide) cells

41 It also gives you the access to the Table Properties window, which allows you to: Change the column width Align text within the cells (to the top, left, bottom, or right) Modify table and cell borders 41

42 Insert and format a list in Arbortext We use the itemizedlist tag to insert bulleted lists, but we use para tags to make numbered and lettered lists. The reason is that the itemizedlist tag has an option for bullets and em dashes but not numbers or letters. To insert a bulleted list: 1. Place your cursor outside the para tag of the paragraph you want the list to follow. 2. Click the Insert Mark-up button in the toolbar. 3. In the new Insert Markup window, select the itemizedlist tag. 4. Click the Insert button. 5. In the Insert Markup window, select the para tag. 6. Click the Insert button.

43 43 7. Place your cursor inside the new itemizedlist tag but outside the listitem tag. 8. Click the Modify Attributes button in the toolbar. 9. In the new Modify Attributes window, select from the drop-down menu in the mark: space bullet. Select from the drop-down menu in the role: space ps_indent_2.

44 Click the OK button. 11. To make several bullet points, copy the listitem tag, place your cursor after the first listitem tag, and paste the number of bullet points you want. 12. Type your list text within each para tag within each listitem tag. To insert a lettered or numbered list: 1. Place your cursor outside of the para tag of the paragraph that you want the list to follow. 2. Click the Insert Mark-up button in the toolbar. 3. In the new Insert Markup window, select the para tag. 4. Click the Insert button.

45 45 5. Place your cursor inside the new para tag. 6. Click the Modify Attributes button in the toolbar. 7. In the new Modify Attributes window, select from the drop-down menu in the role: space ps_indent_hang_2. 8. Click the OK button.

46 46 9. Type the letter or number you want for the first list point. 10. In the Insert Markup window, select the tab tag. 11. Click the Insert button.

47 To make several list points, copy the para tag, place your cursor after the first para tag, and paste the number of list points you want. 13. Be sure to change the letter or number in each list point Reference sections in Arbortext Referencing means copying a section of content from one publication and using it in another publication. But instead of just making a duplicate of the content (like you would if you used the copy and paste features of MS Word), referencing allows Documentum to update the referenced section each time the original section is changed. The smallest chunks of content we can reference are sections, but we usually reference chapters. To reference a section: 1. Check out from Documentum the publication that contains the section you want to reference.

48 48 2. Using the nesting window (see section 2.2, Features of Arbortext), collapse the sections you want to copy. This makes it easier to see the sections. 3. Highlight the section of text, right click on it, and click on Copy. 4. Check out from Documentum the publication to which you want add the referenced section. 5. Place your cursor where you want paste the referenced section, right click on it, and click on Paste. 6. In the new Arbortext Editor Response window, click on the Reference button. (Click on the Duplicate button if you only want to paste the section without referencing.)

49 References 4.1 Catalogue of ID conventions The following table lists examples of our ID conventions. Document Target Doc (for linking) ID Auditing Standard No. 4 ps-pcaob pcoab_as_4 AU section 411 ps au_411 Paragraph.07 of AU section 411 ps au_ Interpretation Paragraph.56 of chapter 1 of Audit and Accounting Guide Not-for-Profit Organizations (AAG NPO) ps aag-npo aag-npo1.56 Appendix G of chapter 1 of aag-npo AAG NPO Scope section of chapter 1 aag-npo of AAG NPO Footnote 4 of chapter 1 of aag-npo AAG NPO Table 4-1 of chapter 4 of aag-lhi AAG LHI Rule 203 of the Professional ps et_ Code of Conduct Statement of Position 04-2 tpa acc_10610 Practice Bulletin 11 tpa pb_12110 aag-npo1_appg aag-npo1_scope aag-npo1_fn4 aag-lhi4_table4-1