/usr/share/doc/libooolib-perl/doc/ooolib-perl-0.1.8-doc.html is in libooolib-perl 0.1.9-1.1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 | <html>
<head>
<title>OpenOffice.org Perl Module (ooolib-perl)</title>
</head>
<body bgcolor=ffffff>
<center>
<h1>OpenOffice.org Perl Library (ooolib-perl)<h1>
<h2>Version 0.1.8</h2>
<h2>Documentation</h2>
</center>
<hr>
<a name=table><h1>Table of Contents</h1>
<ol>
<li><a href=#table>Table of Contents</a>
<li><a href=#info>Information</a>
<ul>
<li><a href=#info-contact>Contact Information</a>
<li><a href=#info-license>ooolib-perl License</a>
</ul>
<li><a href=#setup>Setup and Installation</a>
<ul>
<li><a href=#setup-require>Requirements</a>
<li><a href=#setup-contents>Contents</a>
<li><a href=#setup-examples>Example Programs</a>
</ul>
<li><a href=#api>Application Programming Interface (API)</a>
<ul>
<li><a href=#api-basic>Basic Outline</a>
<li><a href=#api-set>oooSet - Property Setting</a>
<li><a href=#api-data>oooData - Documents Data</a>
<li><a href=#api-special>oooSpecial - Special Data</a>
<li><a href=#api-generate>oooGenerate - Document Creation</a>
<li><a href=#api-error>oooError - Error reporting</a>
</ul>
<li><a href=#internal>Library Internals</a>
<ul>
<li><a href=#internal-variable>Internal Variables</a>
<li><a href=#internal-cleantext>oooCleanText</a>
<li><a href=#internal-meta>oooWriteMeta</a>
<li><a href=#internal-contents>oooWriteContests</a>
<li><a href=#internal-styles>oooWriteStyles</a>
<li><a href=#internal-mimetype>oooWriteMimetype</a>
<li><a href=#internal-settings>oooWriteSettings</a>
<li><a href=#internal-manifest>oooWriteManifest</a>
<li><a href=#internal-timestamp>oooTimeStamp</a>
<li><a href=#internal-datetime>oooDateTime</a>
<li><a href=#internal-cellupdate>oooCellUpdate</a>
<li><a href=#internal-cellcheck>oooCellCheck</a>
<li><a href=#internal-stylename>oooStyleName</a>
</ul>
</ol>
<hr>
<a name=info><h1>Information</h1>
Information about the ooolib-perl project. I am interested in seeing how the ooolib is being used. If you are using ooolib in a program or on your website, please email me and let me know.<p>
<a name=info-contact><h3>Contact Information</h3>
You can contact me, Joseph Colton, at either of these addresses. For e-mail:<br>
josephcolton@gmail.com<p>
For mailing or visiting:<br>
55-579 Naniloa Loop<br>
Laie, Hawaii 96762<p>
<a name=info-license><h3>ooolib-perl License</h3>
ooolib-perl - This Perl Library is built to create OpenOffice.org documents.<br>
Copyright (C) 2003-2006 Joseph Colton<p>
This library is free software; you can redistribute it and/or<br>
modify it under the terms of the GNU Lesser General Public<br>
License as published by the Free Software Foundation; either<br>
version 2.1 of the License, or (at your option) any later version.<p>
This library is distributed in the hope that it will be useful,<br>
but WITHOUT ANY WARRANTY; without even the implied warranty of<br>
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU<br>
Lesser General Public License for more details.<p>
You should have received a copy of the GNU Lesser General Public<br>
License along with this library; if not, write to the Free Software<br>
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA<br>
<p>
<hr>
<a name=setup><h1>Setup and Installation</h1>
The setup and installation for ooolib-perl is really quite easy. Because the library is written in Perl, there is no compiling. You only need to have the requirements and use the require statement in your program.<p>
<a name=setup-require><h3>Requirements</h3>
In order to use ooolib-perl you will need to have a machine running GNU/Linux and have either the Archive::Zip module or the zip command installed. To view the resulting documents you will need to have OpenOffice.org 1.1 Beta or later.<p>
<a name=setup-contents><h3>Contents</h3>
Below are the files and directories included with the source for ooolib:<p>
<pre>
ChangeLog This file contains information about changes to ooolib-perl
in each version.
doc/ This is the documentation directory.
examples/ This directory contains example programs.
ooolib.pm This is the ooolib-perl module.
README The readme file.
TODO This file contains information about tasks that are not yet
completed.
mime.types This file contains mime type information you can use with Apache, etc.
</pre>
<a name=setup-examples><h3>Example Programs</h3>
There are currently very few example programs. The number and use of the example programs are subject to change as the feature set of ooolib grows.<p>
<hr>
<a name=api><h1>Application Programming Interface (API)</h1>
The Application Programming Interface or API is just the collection of functions you use to create programs that use ooolib.<p>
<a name=api-basic><h3>Basic Outline</h3>
Perl scripts using ooolib need a few basic things. You need to use the module and you need to create the document by specifying what type of document you are creating. Finally you need to create the document with the generate command. This is about the shortest a script can be:
#!/usr/bin/perl
use ooolib;
$doc = new ooolib("sxw");
$doc->oooSet("builddir", ".");
$doc->oooSet("author", "The Author");
$filename = $doc->oooGenerate("basic.sxw");
<p>
For you can save and use this code if you like: <a href=base_code>base_code</a>
<a name=api-set><h3>oooSet - Setting Properties</h3>
Sets variables used in creating and processing documents.<br>
<b>Synopsis</b>:<br>
&oooSet(NAME, <DATA>);<br>
<b>Description</b>:<br>
oooSet can only be called after oooInit. This function sets options such as the author, subject, bold, italics, etc. The first argument, NAME, refers to what is to be set. Each NAME argument has different <DATA> options that are needed. Here are the current names with the <DATA> that they require:<br>
<ul>
<li>"title" - Takes a single string value that is used as the title of the document.
<li>"author" - Takes a single string value that is used as the name of the author for the document.
<li>"subject" - Takes a single string value that is used as the subject of the document.
<li>"comments" - Takes a single string value that is used as the comments for the document.
<li>"builddir" - Takes a single string that is supposed to contain the path for the creation of the document.
<li>"keyword" - Takes a single string containing a single word that is to be added to the keywords for the document. This may be used multiple times to add multiple keywords to the document.
<li>"meta[1-4]-name" - Takes a single string containing the title of a user defined variable.
<li>"meta[1-4]-value" - Takes a single string containing the value of a user defined variable.
<li>"cell-loc" - Takes x and y coordinates in a spreadsheet. The next oooData call will print to the resulting cell.
<li>"column-width" - Takes x as the column number and a width in centimeters. (Sorry for those of you who use inches. I guess I have spent too much time in foreign countries. 1 inch = 2.54 cm.)
<li>"cell-left" - Moves the writing cell one to the left.
<li>"cell-right" - Moves the writing cell one to the right.
<li>"cell-up" - Moves the writing cell up one.
<li>"cell-down" - Moves the writing cell down one.
<li>"cell-auto" - Takes x and y values. After each oooData call the writing cell is incremented by these x and y values.
<li>"justify" - Takes a single argument of "right", "left", "center", or "block". The next text will then be justified accordingly.
<li>"bold" - Takes a single argument of either "on" or "off".
<li>"italic" - Takes a single argument of either "on" or "off".
<li>"underline" - Takes a single argument of either "on" or "off".
<li>"text-color" - Takes a single argument of six hex digits in the form RRGGBB where RR is the red, GG is the green, and BB is the blue for the color of the text. You may also select the following options "red", "green", "blue", "black", "white", and "default".
<li>"text-bgcolor" - Takes the same argument at "text-color" except it is instead applied to the background or highlighting of the text.
<li>"text-size" - Takes a single argument that must be a number for the size of the font. The following text will be written in this size. The exception is the headings.
<li>"text-font" - Takes a single argument for the font. The following are valid fonts:
<ul>
<li>"Arial"
<li>"Bitstream Vera Sans"
<li>"Bitstream Vera Serif"
<li>"Bookman"
<li>"Courier"
<li>"Courier 10 Pitch"
<li>"Helvetica"
<li>"Lucidabright"
<li>"Lucidasans"
<li>"Lucida Sans Unicode"
<li>"Lucidatypewriter"
<li>"Luxi Mono"
<li>"Luxi Sans"
<li>"Luxi Serif"
<li>"Symbol"
<li>"Tahoma"
<li>"Times"
<li>"Times New Roman"
<li>"Utopia"
<li>"Zapf Chancery"
<li>"Zapf Dingbats"
</ul>
</ul>
<b>Return Value</b>:<br>
On successful completion oooSet returns the string "ok". If there is a problem, oooSet will return the string "error" and an error message will be available by calling oooError.<br>
<a name=api-data><h3>oooData - Documents Data</h3>
Takes data and formats it for use in the document.<br>
<b>Synopsis</b>:<br>
&oooData(STYLE, TEXT);<br>
<b>Description</b>:<br>
oooData can only be called after oooInit has been called. It takes a string STYLE and a string of TEXT then uses this information to create the data in the content.xml file. The TEXT is run through the character filter oooCleanText, then the STYLE is looked up.<br>
In some cases, the style needs to have features such as bold, italics, right, center, or block justification added. This is also handled by this function call.<br>
This is a list of the different styles currently available:<br>
<ul>
<li>"h" - Heading takes a single additional argument for the heading text.
<li>"h[1-9]" - Headings 1-9 take a single additional argument for the heading text.
<li>"default" - Default or Standard text take an additional argument for the text.
<li>"textbody" - Text body takes a string argument for the text.
<li>"cell-float" - Takes a single number for a cell.
<li>"cell-text" - Takes a single string for a cell's text.
<li>"cell-formula" - Takes a single string for a cell's formula.
<li>"cell-skip" - Just runs the cell-auto increment without writing anything to the cell.
</ul>
<b>Return Value</b>:<br>
Return the string "ok" on successful completion and the string "error" if there is a problem.<br>
<a name=api-special><h3>oooSpecial - Special Data</h3>
This function creates special types of data for documents.<br>
<b>Synopsis</b>:<br>
&oooSpecial(STYLE, <ARGS>);<br>
<b>Description</b>:<br>
oooSpecial takes a single argument for a style and then optional additional arguments required to carry out the style. Below are the current styles:<br>
<ul>
<li>"pagebreak" - This creates a page break and does not require any additional arguments.
<li>"list-ordered" - This creates an ordered list. The first call passes in an argument "new" and some text string. This becomes the first list item. The return value of the first call is the list ID number. For future calls on the same list just pass in the list ID instead of "new".
</ul>
<b>Return Value</b>:<br>
Return values vary, but if you get "ok" then everything worked. If you get "error" then there is a problem. All other return values also indicate things worked out correctly. For other return values see the description of the different styles.<br>
<a name=api-generate><h3>oooGenerate - Document Creation</h3>
Creates the end document file.<br>
<b>Synopsis</b>:<br>
&oooGenerate;<br>
&oooGenerate(FILENAME);<br>
<b>Description</b>:<br>
The oooGenerate function is either left empty or is passed a single string argument, FILENAME, that is used to determine the filename for the document being created.<br>
In the event that a FILENAME is picked, oooGenerate will make sure the filename ends with the correct file extension. If it is not present, oooGenerate will append the correction extension and create the file.<br>
If no FILENAME is supplied, oooGenerate will create a a name consisting of the date and the pid number of the processes running ooolib, and the correction file extension.<br>
<b>Return Value</b>:<br>
Once oooGenerate has successfully completed, it will return a string containing the complete path of the newly created document. If there is an error, oooGenerate will return the string "error" and an error message will be available by calling oooError.<br>
<a name=api-error><h3>oooError - Error reporting</h3>
Gives error messages to help in debugging code.<br>
<b>Synopsis</b>:<br>
&oooError;<br>
<b>Description</b>:<br>
oooError returns a string containing the last error message. If two errors are reported to oooError, it will only return the last error.<br>
<b>Return Value</b>:<br>
A string containing the last error message.<br>
<hr>
<a name=internal><h1>Library Internals</h1>
If you are interested in working on the inside of the library you will probably want to know a little bit about how it is setup.
<a name=internal-variable><h3>Internal Variables</h3>
<ul>
<li>$version - This variable holds the version number of the library.
<li>%options - This variable holds lots of information set with the oooSet function.
<li>@keywords - This variable holds a list of the keywords.
<li>@fontdecls - This variable holds information about used fonts.
<li>%cellhash - This variable holds all of the spreadsheet data before writing the document.
<li>@documenttext - This variable holds all of the main text for the content.xml file.
<li>@autostyles - This variable holds any new styles created by making new combinations of bold, italics, justification, etc.
<li>@autolists - This variable holds all of the information needed to create lists. It is really an extension to the @autostyles variable and comes directly after it in the content.xml file.
<li>$MINX - The minimum allowed x value in the spreadsheet.
<li>$MINY - The minimum allowed y value in the spreadsheet.
<li>$MAXX - The maximum allowed x value in the spreadsheet.
<li>$MAXY - The maximum allowed y value in the spreadsheet.
</ul>
<a name=internal-cleantext><h3>oooCleanText</h3>
This function prepares a text string to be included in the XML for OpenOffice.org documents.<br>
<b>Synopsis</b>:<br>
&oooCleanText(TEXT);<br>
<b>Description</b>:<br>
oooCleanText takes a string, TEXT, and replaces special characters that conflict with the text of the XML for the OpenOffice.org documents. This is the order of the substitutions:<br>
"&" becomes "&amp;"<br>
"'" becomes "&apos;"<br>
"<" becomes "&lt;"<br>
">" becomes "&gt;"<br>
<b>Return Value</b>:<br>
Once the text has been modified, the resulting text is returned.<br>
<a name=internal-meta><h3>oooWriteMeta</h3>
Writes the meta.xml file that is included in the document.<br>
<b>Synopsis</b>:<br>
&oooWriteMeta(BUILDDIR, TYPE);<br>
<b>Description</b>:<br>
The function oooWriteMeta takes two string BUILDDIR and TYPE as input and uses the information previously entered using commands like oooSet to build the meta.xml file.<br>
<b>Return Value</b>:<br>
Return "ok" on success and "error" if an error occurs.<br>
<a name=internal-contents><h3>oooWriteContests</h3>
Writes the content.xml file.<br>
<b>Synopsis</b>:<br>
&oooWriteContents(BUILDDIR, TYPE);<br>
<b>Description</b>:<br>
The function oooWriteContents takes two strings BUILDDIR and TYPE as input and uses the information previously entered using commands like oooSet and oooData to build the content.xml file.<br>
<b>Return Value</b>:<br>
Returns "ok" on success and "error" if an error occurs.<br>
<a name=internal-styles><h3>oooWriteStyles</h3>
Writes the styles.xml file.<br>
<b>Synopsis</b>:<br>
&oooWriteStyles(BUILDDIR, TYPE);<br>
<b>Description</b>:<br>
The function oooWriteStyles takes two strings BUILDDIR and TYPE as input and uses the type of document to build a styles.xml file.<br>
<b>Return Value</b>:<br>
Returns "ok" on success and "error" if an error occurs.<br>
<a name=internal-mimetype><h3>oooWriteMimetype</h3>
Writes the mimetype file.<br>
<b>Synopsis</b>:<br>
&oooWriteMimetype(BUILDDIR, TYPE);<br>
<b>Description</b>:<br>
The function oooWriteMimetype takes two strings BUILDDIR and TYPE as input and uses the type of document to build a mimetype file.<br>
<b>Return Value</b>:<br>
Returns "ok" on success and "error" if an error occurs.<br>
<a name=internal-settings><h3>oooWriteSettings</h3>
Writes the settings.xml file.<br>
<b>Synopsis</b>:<br>
&oooWriteSettings(BUILDDIR, TYPE);<br>
<b>Description</b>:<br>
The function oooWriteSettings takes two strings BUILDDIR and TYPE as input and uses the type of document to build a settings.xml file.<br>
<b>Return Value</b>:<br>
Returns "ok" on success and "error" if an error occurs.<br>
<a name=internal-manifest><h3>oooWriteManifest</h3>
Writes the manifest file.<br>
<b>Synopsis</b>:<br>
&oooWriteManifest(BUILDDIR, TYPE);<br>
<b>Description</b>:<br>
The function oooWriteManifest takes two strings BUILDDIR and TYPE as input and builds the manifest.xml file.<br>
<b>Return Value</b>:<br>
Returns "ok" on success and "error" if an error occurs.<br>
<a name=internal-timestamp><h3>oooTimeStamp</h3>
Returns a time stamp.<br>
<b>Synopsis</b>:<br>
&oooTimeStamp;<br>
<b>Description</b>:<br>
The oooTimeStamp function calculates the date and returns a string indicating the date.<br>
<b>Return Value</b>:<br>
A string in the form YYYY-MM-DDTHH:MM:SS.<br>
<a name=internal-datetime><h3>oooDateTime</h3>
Returns the date and time: yyyy, mm, dd, hh, mm, ss<br>
<b>Synopsis</b>:<br>
&oooDateTime;<br>
<b>Description</b>:<br>
Gets the date and time information, then returns the results.<br>
<b>Return Value</b>:<br>
Returns an array (year, month, day, hour, minute, second)<br>
<a name=internal-cellupdate><h3>oooCellUpdate</h3>
Updates max values and current values for x and y<br>
<b>Synopsis</b>:<br>
&oooCellUpdate;<br>
<b>Description</b>:<br>
The function oooCellUpdate is called after data is entered in a cell. It updates the cell location if the cell-auto x and y have been set. Next it calls oooCellCheck to make sure the resulting x and y values are still valid.<br>
<b>Return Value</b>:<br>
None<br>
<a name=internal-cellcheck><h3>oooCellCheck</h3>
Tests to make sure the x and y values are legal<br>
<b>Synopsis</b>:<br>
&oooCellCheck;<br>
<b>Description</b>:<br>
Checks and makes sure the x ($cellhash{x}) and y ($cellhash{y}) values are between the maximum ($MAXX, $MAXY) and minimum ($MINX, $MINY) allowed values. If they are too high or too low they are set to the max or min value.<br>
<b>Return Value</b>:<br>
None<br>
<a name=internal-stylename><h3>oooStyleName</h3>
Returns the name of the style to use<br>
<b>Synopsis</b>:<br>
&oooStyleName(STYLE);<br>
<b>Description</b>:<br>
The oooStyleName function keeps track of which combinations of bold, italics, underline, right, left, center, and block justification have auto style aliases. If there is one it is returned, if not it is created and returned.<br>
<b>Return Value</b>:<br>
Returns a string that contains the style that should be used for the text.<br>
</body>
</html>
|