Authoring OpenStax Documents in Apache OpenOffice Writer *

Transcription

1 OpenStax-CNX module: m Authoring OpenStax Documents in Apache OpenOffice Writer * R.G. (Dick) Baldwin This work is produced by OpenStax-CNX and licensed under the Creative Commons Attribution License 4.0 Abstract Learn how to create documents using Apache OpenOce Writer and publish those documents on OpenStax. Revised: Wed Apr 27 08:27:30 CDT 2016 This page is part of a Book titled OpenStax Publishing with a WYSIWYG Editor. 1 1 Table of contents Table of contents (p. 1) Preface (p. 2) Viewing tip (p. 2) * Figures (p. 2) * Listings (p. 3) Preview (p. 3) Available features (p. 3) A little more clarity (p. 3) Special requirements (p. 4) Discussion of available features (p. 4) Headings (p. 4) Lists, paragraphs, bold, and Italic (p. 4) * Ordered lists (p. 4) * Unordered lists (p. 5) * Paragraphs (p. 5) Preformatted text (p. 5) Pictures, hyperlinks, and bookmarks (p. 6) * Pictures (p. 6) * Hyperlinks and bookmarks (p. 6) Notes (p. 7) * Version 1.10: Apr 27, :28 am

2 OpenStax-CNX module: m * Contents of notes (p. 7) * How to create a note (p. 8) Run the program (p. 9) Some sample odt les (p. 9) The big picture (p. 9) The detailed picture (p. 9) * Extract content.xml and Pictures (p. 9) * Get and run the program (p. 10) * Translate XHTML into CNXML (p. 10) * Upload and publish the CNXML le (p. 10) Downloadable les (p. 11) A somewhat unique code (p. 11) How to use the code (p. 11) Miscellaneous (p. 12) 2 Preface In an earlier module titled Wysiwyg0100 Getting Started 2, I showed you how you can use a WYSIWYG XHTML editor to create documents for publication on OpenStax. While that is much easier than creating your documents in OpenStax's CNXML code, it does still require the use of an editing tool that may not be familiar to many potential authors. In this module, I will introduce you to a process and a program that will allow you to create documents using Apache OpenOce Writer 3 (referred to hereafter simply as Writer) and to publish those documents on OpenStax. With this process, you can create your documents in Writer, translate them into CNXML using programs that I will provide, and upload them to OpenStax as Plain CNXML. According to their website 4, "Writer has everything you would expect from a modern, fully equipped word processor. It is simple enough for a quick memo, yet powerful enough to create complete books with contents, diagrams, indexes, etc. You're free to concentrate on your ideas while Writer makes them look great." Writer is very similar to Microsoft Word. diculty making the transition to Writer. If you are familiar with Word, you should have no I will create this module exclusively using Writer along with a program named that I will provide. (See Run the program (p. 9).) 2.1 Viewing tip OpenOceToXhtml01 I recommend that you open another copy of this module in a separate browser window and use the following links to easily nd and view the Figures and Listings while you are reading about them Figures Figure 1 (p. 6). An old caricature of the author. Figure 2 (p. 8). A note containing an image. Figure 3 (p. 11). The Writer hyperlink dialog box

3 OpenStax-CNX module: m Listings Listing 1 (p. 5). Stand-alone preformatted text. Listing 2 (p. 7). A note containing preformatted text. 3 Preview This is not a general purpose Writer-to-CNXML translator process. Not all Writer features can be translated into CNXML. Also, the process will not provide you with access to all of the CNXML features that are available. (For example, it will not prepare you to create OpenStax documents having all of the features shown in the OpenStax Physics 5 book.) If you are looking for that degree of sophistication when publishing your documents on OpenStax, you simply need to learn how to create OpenStax documents using the online CNXML editor. This process is designed to support a reasonable subset of the features found in Writer and the features available with CNXML. In general, you should be able to use this process to create OpenStax documents containing the features shown in this module. 3.1 Available features Here is a list of the CNXML features that you should be able to include in your OpenStax documents using this process. These features can be created using normal Writer editing procedures. I will identify the Writer features that you can use and later translate into CNXM in this module and in several Writer sample odt les that I will provide. If I don't discuss a feature in this module or in one of those sample les, you probably can't use it. Those features are: 1. Headings with a parent/child relationship such as Preface (p. 2), Viewing tip (p. 2), and Figures (p. 2) shown above. 2. Ordinary paragraph text with bold, Italic, bold-italic, etc. 3. Inserted images (see Figure 1 (p. 6) ). 4. Local bookmarks such as those incorporated in the headings for Preface (p. 2), Viewing tip (p. 2), and Figures (p. 2) shown above. 5. Hyperlinks to local bookmarks such as this hyperlink (p. 4). 6. Hyperlinks to other websites such as the OpenStax Physics 6 book. 7. Ordered lists such as this list. a. Indentation in ordered list such at this one. b. And this one. 8. Unordered lists such as the items under the Table of Contents (p. 1). 9. Stand-alone preformatted text (see Listing 1 (p. 5) ). 10. CNXML notes containing paragraph text, preformatted text, lists, and images (see Figure 2 (p. 8) ). 3.2 A little more clarity The process described in this module isn't actually a Writer-to-CNXML translator process. Instead, it is a Writer-to-XHTML translator process. Once you have created your Writer document and saved it in an odt le, you can use the program that I will provide to translate it into an XHTML document. That XHTML le can then be translated into CNXML and uploaded to OpenStax using the program and procedures that I explained in the earlier module titled Wysiwyg0100 Getting Started

4 OpenStax-CNX module: m Note: As of April 2016, the program that I will provide with this module has only been tested under a Windows 7 operating system using Java version 8. 4 Special requirements You must disable all of the AutoCorrect options in Writer. Those are the features that automatically convert the rst word in each sentence to upper case, convert ordinary quotes into fancy quotes, convert ordinary dashes (minus sign characters) into fancy hyphens, etc. You can disable those options by selecting AutoCorrect on the Format menu and then clearing the While Typing checkbox. If you fail to do that, Writer will insert characters (such as fancy quotes) in the output that are not suitable for translating into CNXML and uploading to OpenStax. Also, if you plan to include computer code in your document, (see Listing 2 (p. 7) ), you should probably disable automatic spell checking. Otherwise, Writer may corrupt your computer code by changing the spelling of some of the code. 5 Discussion of available features The CNXML features that this program supports are described below. 5.1 Headings The program supports the use of Headings such as Preface (p. 2), Viewing tip (p. 2), Figures (p. 2), and Listings (p. 3) shown above. There are probably a variety of ways to create headings in Writer. The easiest way that I have found is to: Highlight the text that will form the heading Hold down the Ctrl key Press the numbers from 1 through 5 The number 1 will produce the highest level heading and the number 5 will produce the lowest level heading that is apparently supported by Writer. (You can hold the Ctrl key and press the number 6 but it won't produce a heading in the version of Writer that I am using ) For example, the headings Preface (p. 2), Viewing tip (p. 2), and Figures (p. 2) are levels 1, 2, and 3 respectively. Headings created in this manner will translate into h1, h2, and h3 headers in XHTML respectively. Those headers will then translate into sections in CNXML. If you are reading this document online at OpenStax, this section titled Headings is one of many sections contained in the CNXML document. The rules for using Headings are simple. Heading 1 is the top level heading. To produce a CNXML le that can be successfully uploaded to OpenStax, any element designated as Heading 2 must be a child of a Heading 1 element. Similarly, any element designated as Heading 3 must be a child of a Heading 2 element. You cannot create a Heading 1 element and then create a Heading 3 element below it without creating a Heading 2 element in between. (Well, actually you can do that but it will cause problems later on when you try to upload to OpenStax.) See Run the program (p. 9) for a link to a zip le containing a sample odt le named Headings.odt. 5.2 Lists, paragraphs, bold, and Italic Ordered lists The list that you see above (p. 3) is an ordered list. Each item has a numeral to its left. Writer provides many options for formatting ordered lists using numerals, letters, Roman numerals, etc. However, this program supports only the simple variety that you see above (p. 3) using numerals that begin with the numeral "1" and increase incrementally going down the page.

5 OpenStax-CNX module: m Unordered lists The list that you see under Table of contents (p. 1) is an unordered list, often referred to as a bullet list. There are no numbers on the left, just bullets. As before, Writer provides dierent options for formatting the bullets. However, this program supports only the simple variety that you see under Table of contents (p. 1) Paragraphs This program supports ordinary Writer paragraph text. This is the type of text that you get when you start typing in a blank document. This is paragraph text that you are reading right now. This sentence and the following sentences comprise a paragraph. In Writer, you terminate a paragraph when you press the Enter key. This sentence contains a bold word. This sentence contains an Italic word. This sentence contains text that is both bold and italic. There are various ways to style text as bold and Italic. The easiest way that I know of is to Highlight the text that is to be styled as bold or Italic Hold down the Ctrl key Press the b-key for bold and the i-key for Italic Important note: Because angle brackets and ampersands have very signicant meanings in HTML, you cannot include angle brackets and ampersands in your Writer text unless you put them in preformatted text. If you put them in preformatted text, you must rst convert them to their respective entities as shown below: The entity for < is < The entity for > is > The emtity for & is & See Run the program (p. 9) for a link to a zip le containing a sample odt le named ListsParagraphsBoldAndItalic.odt. 5.3 Preformatted text Preformatted text is a term that is used in HTML. To create text in Writer that will result in preformatted text in the XHTML output, you need to highlight the text and change the font to Courier New. (Any text in your Writer document that is styled as Courier New will be written into the output XHTML le as preformatted text.) When preformatted text is later translated into CNXML for uploading to OpenStax, it is given a CNXML style named code. Here is an example of stand-alone preformatted text. A simple paragraph was used to create a caption with a bookmark that can be referenced by hyperlinks elsewhere in the document. Listing 1. Stand-alone preformatted text. //Process hyperlinks else if(node.getnodename() == "text:a"){ System.out.println("---Processing text:a"); out.println("<a href=" + "\"" + valueof(node,"@xlink:href") + "\"" + ">"); //Process all XML child nodes // recursively applytemplates(node,null); out.println("</a>"); }//end else if //End process hyperlinks

6 OpenStax-CNX module: m As you will see later in Listing 2 (p. 7), preformatted text can also be put into a CNXML note, which in some cases may provide an improved visual experience in the OpenStax display. The typical purpose of preformatted text in a web page is to allow you to preserve the format such as indentation, line spacing, etc. In this program, preformatted text is also used to include characters, such as angle brackets, that would cause problems when mixed in with HTML code. Important notes: 1.As mentioned earlier, you may not include angle brackets and ampersands in your ordinary Writer paragraph text. However, you may put them in preformatted text provided that you rst convert them to their respective entities. 2.You may not make any of the text in preformatted text into either a local bookmark or a hyperlink. You also may not apply formatting such as bold and Italic to preformatted text. See Run the program (p. 9) for a link to a zip le containing a sample odt le named PreformattedText.odt. 5.4 Pictures, hyperlinks, and bookmarks Pictures You can insert images into your Writer document by selecting Picture on the Insert menu. The image shown below was inserted in that manner. Once inserted, the image becomes part of the odt le. It other words, the odt le will contain a copy of the image and not just a pointer to the original image le. Changes that you make to the image, using the Graphic Filter item on the Picture Bar, for example, will be made to the copy and not to the original image le. Figure 1. An old caricature of the author. An ordinary paragraph was used to create the caption with the bookmark shown above (p. 6). It is best to put the caption at the top instead of at the bottom. Later when a user clicks a hyperlink to a bookmark in the caption, that bookmark will be moved to the top of the page in the browser. For accessibility purposes, you should always provide Alt Text for your images. If you don't do that, OpenStax may refuse to accept and publish the image. You can create Alt Text by right-clicking on the image, selecting Description, and entering your text in the Title box Hyperlinks and bookmarks To create a bookmark, do the following: Place the cursor at the location for the bookmark. Select Bookmark on the Insert menu

7 OpenStax-CNX module: m Enter the text for the bookmark Important: When entering the text for a bookmark, don't leave any spaces and don't use any characters other than letters, numbers, and the underscore character. A good way to create descriptive bookmarks is to use "CamelCase" to create a bookmark that looks something like the following: MyVeryBestBookmark To create a hyperlink to another web site, do the following: Highlight the text that is to become the hyperlink. Select Hyperlink on the Insert menu. Select Internet and enter the URL in the Target box. To create a hyperlink to a bookmark in the same document: Highlight the text that is to become the hyperlink. Select Hyperlink on the Insert menu. Select Document. Enter the name of the bookmark in the Target box or click the button to the right of the Target box and select the bookmark in the list of Bookmarks. See Run the program (p. 9) for a link to a zip le containing a sample odt le named PicturesHyperlinksAndBookmarks.odt. 5.5 Notes A CNXML note is a container that can be used to cause material to be set apart from normal CNXML paragraph text providing a pleasing appearance in the OpenStax presentation Contents of notes Notes can contain ordinary paragraph text, preformatted text, lists, images, or a combination of those elements. This document contains several notes that contain ordinary paragraph text such as the one shown above (p. 7), which contains a mixture of ordinary paragraph text and preformatted text. The note shown here (p. 6) contains a list. The following note contains preformatted text. Listing 2. A note containing preformatted text. //Process hyperlinks else if(node.getnodename() == "text:a"){ System.out.println("---Processing text:a"); out.println("<a href=" + "\"" + valueof(node,"@xlink:href") + "\"" + ">"); //Process all XML child nodes // recursively applytemplates(node,null); out.println("</a>"); }//end else if //End process hyperlinks

8 OpenStax-CNX module: m As you can see, this is a good way to present program code. However, the visual eect might be more pleasing if the caption were moved inside the note as shown in Figure 2 (p. 8). Finally, the following note contains an image. In this case, a paragraph was used to create a caption with a bookmark inside the note. Figure 2. A note containing an image How to create a note To create a note in CNXML, you need to create a basic table in Writer with one row and one column. (Don't do anything fancy when you create the table.) You can then populate it with one or more of the items shown above. That table will eventually end up as a note on OpenStax.

9 OpenStax-CNX module: m Run the program Now it's time to explain the mechanics of using this process and this program to create and publish your documents on OpenStax. 6.1 Some sample odt les Before getting into the details, click here 8 to download a zip le named Samples.zip that contains several sample odt les. You can use these sample odt les to experiment with the process and the program. 6.2 The big picture The steps for creating and publishing your document on OpenStax are as follows: 1. Download and install the Apache OpenOce 9 suite. As of April 2016, it is free. Note that the suite contains several dierent elements in addition to Writer, such as Base, Calc, and Draw. 2. Use Writer to create your document as described above and save it. By default, the document will be saved in a le with an extension of odt. 3. Use the process described below to translate the odt le into an XHTML le. 4. Go to Wysiwyg0100 Getting Started/Running the program 10 and use the procedure described there to translate your XHTML le into a CNXML le for uploading to OpenStax. 5. Go to Wysiwyg0100 Getting Started/Upload and publish your new page 11 and use the procedure described there to upload your CNXML le and publish it on OpenStax. 6.3 The detailed picture I will concentrate steps 3, 4, and 5 in the above list. Although the output le that is produced when you save the document in Writer has an extension of odt, it is actually a zip le. You can conrm that by changing the extension from odt to zip and opening the le using whatever program you normally use to extract the contents of zip les. In Windows, for example, you can simply right-click on the zip le and select Open in a new window. Then you can copy the contents of the zip le into a dierent folder. Note that if you have a special zip program, such as WinZip installed on your computer, it will probably override the Windows default behavior described above Extract content.xml and Pictures When you open the zip le for extraction, you will see that it contains a large number of les and folders. In all cases, it should contain a le named content.xml. If your Writer document contains pictures, the zip le will also contain a folder named Pictures. The Pictures folder will contain copies of the image les that you inserted into your document. The image les in the Pictures folder will probably have very long names such as C C37E3C8FEA.jpg This process uses only the le named content.xml and the folder named Pictures if it exists. Extract those two items into an empty folder

10 OpenStax-CNX module: m Get and run the program Click here 12 to download a zip le named ProgramFiles.zip containing the compiled Java class les for the program named OpenOceToXhtml01. That zip le should contain the following four les: HtmlPreCleaner01.class OpenOceToXhtml01.class Translate01.class copyfilesfrompicture.bat Extract those four les into the same folder with the le named content.xml. (Note: if you haven't downloaded the program les since the revision date shown at the top of this module, it might be a good idea to download a fresh copy to make certain that you have the latest version.) Open a command-line window in that folder and execute the following command at the command prompt: java OpenOfficeToXhtml01 content.xml PreCleanerOutput.html > junk.txt This should produce several new les in that folder including a le named PreCleanerOutput.html and a copy of each of the image les from the Pictures folder, if any. The le named PreCleanerOutput.html is the XHTML le that you are looking for. If you open that le in your browser, you will see an XHTML version of your document Translate XHTML into CNXML Copy that le along with the image les into another empty folder. Then go to Wysiwyg0100 Getting Started/Running the program 13 and follow the procedures given there to translate the XHTML le named PreCleanerOutput.html into a CNXML le. As described in that module, you will open a command-line window in that folder and execute the following command at the command line: where java CNXMLprep12 PreCleanerOutput.html OutputFile.cnxml PreCleanerOutput.html is the name of the input le. OutputFile.cnxml is the name that you want to assign to the CNXML le produced by the program. This is the le that you will upload to OpenStax Upload and publish the CNXML le Then go to Wysiwyg0100 Getting Started/Upload and publish your new page 14 and follow the instructions there to upload your CNXML le to OpenStax, and to publish it on OpenStax. This program was developed using the Java SE Development Kit In order to run this program on your computer, you must have the Java SE Runtime Environment 8 (JRE) 16 or a later version of the JRE installed on your computer. The JRE is already installed on many computers and it may already be installed on yours (but it may be an earlier version that requires updating). If it is not installed, or it is not up to date, there are many web pages that provide instructions for downloading and installing Java. One of those web pages is located here

11 OpenStax-CNX module: m Downloadable les There is at least one major area where Writer doesn't serve us well for creating documents that will be published on OpenStax. Therefore, it was necessary for me to develop a workaround to deal with the issue. The issue is that as in the case in Get and run the program (p. 10) above, we often want to make it possible for the user to download a zip le, an audio le, or some other le type (other than an image le) by clicking on a link in the OpenStax document. As near as I can tell, Writer doesn't provide direct support for that capability. 7.1 A somewhat unique code Before getting into the details, let me introduce you to a somewhat unique code that is an integral part of my workaround: 12345OIcafa678910TIliga I say it is somewhat unique because I didn't nd any matches for the code with a Google search. To make the code easy to remember, the characters in the code are the numeric and letter equivalents of the rst letters of the words in the following nursery rhyme: One, two, three, four, five, Once I caught a fish alive, six, seven, eight, nine, ten, Then I let it go again. 7.2 How to use the code Now that you know what the code is and how to remember it, I will explain how to use it. Assume that you want to make it possible for your document's viewers to download a le named Samples.zip from the OpenStax site. (You will have placed that zip le along with any image les and other downloadable les in a zip le and uploaded it to OpenStax as described here 18 and here 19.) Highlight the text in your document that will be the hyperlink for downloading the le, such as the word here in the following sentence: Click here 20 to download the le named Samples.zip. Pull down the Insert menu and select Hyperlink. The dialog box shown in Figure 3 (p. 11) will appear. Figure 3. The Writer hyperlink dialog box

12 OpenStax-CNX module: m Select Internet on the left, check Web at the top and type the code into the Target eld followed immediately by the name of the downloadable le. Then click the Apply button and the Close button. This will cause a hyperlink pointing to a website with the name shown in Figure 3 (p. 11) to be contained in the le that is rst produced by translating the le named content.xml into XHTML. That is not what we are looking for. What we are looking for is a hyperlink to a le named Samples.zip that is in the same folder as the CNXML le on the OpenStax server. The hyperlink is modied to the following form for the nal XHTML output le. This is exactly what we need. <a href="samples.zip"> Clicking that link will cause the le named Samples.zip to be downloaded. 8 Miscellaneous This section contains a variety of miscellaneous information. Housekeeping material Module name: Authoring OpenStax Documents in Apache OpenOce Writer File: Wysiwyg0140.odt Published: 04/23/16 Disclaimers: Although the OpenStax site makes it possible for you to download a PDF le for this module at no charge, and also makes it possible for you to purchase a pre-printed version of the PDF le, you should be aware that some of the HTML elements in this module may not translate well into PDF. I also want you to know that, I receive no nancial compensation from the OpenStax website even if you purchase the PDF version of the module.

13 OpenStax-CNX module: m In the past, unknown individuals have copied my modules from OpenStax, converted them to Kindle books, and placed them for sale on Amazon.com showing me as the author. I neither receive compensation for those sales nor do I know who does receive compensation. If you purchase such a book, please be aware that it is a copy of a module that is freely available on OpenStax and that it was made and published without my prior knowledge. -end