diff options
Diffstat (limited to 'lib/ebooks/understandingoeb')
| -rw-r--r-- | lib/ebooks/understandingoeb/OEBActivityDiagram.png | bin | 0 -> 3433 bytes | |||
| -rw-r--r-- | lib/ebooks/understandingoeb/OEBClassDiagram.png | bin | 0 -> 1257 bytes | |||
| -rw-r--r-- | lib/ebooks/understandingoeb/chapter1.html | 114 | ||||
| -rw-r--r-- | lib/ebooks/understandingoeb/chapter2.html | 442 | ||||
| -rw-r--r-- | lib/ebooks/understandingoeb/chapter3.html | 230 | ||||
| -rw-r--r-- | lib/ebooks/understandingoeb/chapter4.html | 442 | ||||
| -rw-r--r-- | lib/ebooks/understandingoeb/chapter5.html | 156 | ||||
| -rw-r--r-- | lib/ebooks/understandingoeb/chapter6.html | 626 | ||||
| -rw-r--r-- | lib/ebooks/understandingoeb/foreword.html | 27 | ||||
| -rw-r--r-- | lib/ebooks/understandingoeb/preface.html | 33 | ||||
| -rw-r--r-- | lib/ebooks/understandingoeb/title.html | 26 | ||||
| -rw-r--r-- | lib/ebooks/understandingoeb/toc.html | 150 | ||||
| -rw-r--r-- | lib/ebooks/understandingoeb/understandingoeb.css | 28 | ||||
| -rw-r--r-- | lib/ebooks/understandingoeb/understandingoeb.opf | 65 |
14 files changed, 2339 insertions, 0 deletions
diff --git a/lib/ebooks/understandingoeb/OEBActivityDiagram.png b/lib/ebooks/understandingoeb/OEBActivityDiagram.png Binary files differnew file mode 100644 index 00000000..aee19094 --- /dev/null +++ b/lib/ebooks/understandingoeb/OEBActivityDiagram.png diff --git a/lib/ebooks/understandingoeb/OEBClassDiagram.png b/lib/ebooks/understandingoeb/OEBClassDiagram.png Binary files differnew file mode 100644 index 00000000..90f4a80a --- /dev/null +++ b/lib/ebooks/understandingoeb/OEBClassDiagram.png diff --git a/lib/ebooks/understandingoeb/chapter1.html b/lib/ebooks/understandingoeb/chapter1.html new file mode 100644 index 00000000..d90bf54a --- /dev/null +++ b/lib/ebooks/understandingoeb/chapter1.html @@ -0,0 +1,114 @@ +<?xml version='1.0'?> +<!DOCTYPE html PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Document//EN" "http://openebook.org/dtds/oeb-1.0.1/oebdoc101.dtd"> +<?xml-stylesheet href="understandingoeb.css" type="text/x-oeb1-css"?> + +<html> +<head> + <link rel="stylesheet" type="text/x-oeb1-css" href="understandingoeb.css" /> +<title>Understanding OEB Chapter 1</title> + <meta name="author" content="Garret Wilson" /> + <meta name="copyright" content="Copyright (c) 2000-2001 Garret Wilson. All rights reserved." /> +</head> + +<body> + +<h2 id="chapter1">1. Defining a Beginning</h2> + +<p>eBooks are by no means new. For years educators have been creating multimedia learning systems, businesses have been showing interactive kiosks, entrepreneurs have been showing electronic presentations, and corporations have been distributing PDF documents. Michael Hart's Project Gutenberg has been giving away electronic texts for, well, practically since computers were invented. A student creates an eBook when she writes a report for college. Your brother writes an eBook when he enters recipes into his computer. I listen to an eBook when I download an MP3 from...</p> + +<p>"Wait," you might say. "Those aren't really eBooks." You might say that because you've noticed some fundamental difference between eBooks and other electronic things, but more likely you would say that because you have an intuitive notion of what an eBook is.</p> + +<p>Unfortunately, many people have conflicting ideas about which electronic "things" are eBooks. Are eBooks hardware devices, or software? Are eBooks merely textual electronic content? Normal books can be shown on overhead projectors — is an electronic presentation an eBook? What's the difference between a file of recipes and a book full of recipies? An MP3 file isn't an eBook because you can't hear books — yet don't many companies sucessfully sell "audio books" on cassette?</p> + +<p>It should be painfully obvious at this point that to adequately discuss the Open eBook specification, it might be wise to find out exactly what an <dfn>eBook</dfn> is. Somewhat less obvious but no less painful is that I don't really know what an eBook is, either. Sorry. Even if I did, well, it probably wouldn't be the same thing that <em>you</em> think an eBook is. And whatever we thought, we'd likely change our minds once we thought about it a little longer. But don't worry, you're in good company — no one else in the "eBook industry" knows what an eBook is, either, although they all have ideas about what they want you to think an eBook is.</p> + +<h3 id="definingEBook">Defining "eBook"</h3> + +<p>In this book we'll try to skirt the issue of creating an authoritative definition of an eBook, considering an eBook to broadly mean whatever electronic content you want to present. We'll specifically discuss the <em>Open eBook Publication Structure</em> and the types of content it allows one to publish, allowing you to determine whether this format is right for your content. While we discuss the <em>Open eBook Publication Structure</em> and related publications, though, we'll need to come to some definitions that we agree upon, at least in the context of our discussion, which will allow us to know what the other is talking about.</p> + +<div class="sidebar" id="oebDefinitions"> +<h4 class="sidebarTitle">More Information: OEB and Definitions</h4> +<p>Most specifications, the OEB Publication Structure included, recognize the definition problem soon enough, as industry leaders sit around a table arguing for hours before realizing that they agree — they just used different words to express their viewpoints. For this reason, most specifications include a <dfn>glossary</dfn> of terms and their definitions as used within the specification.</p> + +<p>Glossaries are fine for one specification, but in the eBook world there are many separate relevant documents that use different terminologies to mean the same thing, or use the same terminology to mean different things. The OEB Forum has recently therefore committed to creating a terminology that can be used as a common language for the eBook industry as a whole. The Forum has even gone so far as to create a framework for explaining how different players in the eBook industry might give different meanings, based upon their backgrounds, for the words they use.</p> + +<p>Such a defining of terms is a necessity for the eBook industry to be able to efficiently move forward with other open, interdependent specifications related to the OEB Publication Structure. Currently the effort refers to this framework as an <dfn>ontology</dfn>, referring to the eBook industry as a whole as an <dfn>ePublishing ecology</dfn>. This framework is not yet finalized, but there have been reports that the terms "ontology" and "ecology" will be defined Real Soon Now.</p> +</div> + +<h4 id="eText">Electronic Book as an "Etext"</h4> + +<p>One of the first and most famous popularizations of books in electronic format was Project Gutenberg (<a href="http://www.gutenberg.org">http://www.gutenberg.org</a>). According to his own rendition (<a href="http://promo.net/pg/history.html">http://promo.net/pg/history.html</a>), Michael Hart in 1971 was granted access to a mainframe at the University of Illinois. Wanting to make productive use of the precious time he had been allotted on such a scarce resource, he entered the United States "Declaration of Independence" electronically and attempted to send it to everyone on the networks.</p> + +<p>Luckily, such an act occurred before the concept of spam and before the notoriety of computer viruses, so whatever negative repercussions of such unrequested correspondence did not spread far. Michael soon changed from actively sending these <dfn>electronic texts</dfn> (Etexts), as he calls them, to instead archiving them so that they can be downloaded from anyone at any time from anywhere. According to their published figures, Project Gutenberg went from archiving only 100 Etexts in January 1994 to 3333 Etexts in April 2001.</p> + +<p>Michael Hart's Etexts were certainly related to books — they did contain the same text word for word (more or less, in many cases page numbers and all) as the book from which they were taken. There was nothing "book-like" about these works, though. A user can read an Etext with whatever tool he/she has available, such as a text editor or word processor. As electronic versions of textual content of a book, though, Etexts could certainly fit one definition of an "eBook."</p> + +<h4 id="eBookHype">"eBook" as a Marketing Tool</h4> + +<p>By the late 1990s, several companies were attempting to make electronic versions of books that not only replicated the book's content but also duplicated the look of a book. Nuvomedia made a device the size of a small paperback named the Rocket eBook, and Softbook created a somewhat larger device called the Softbook Reader. Both were <dfn>dedicated</dfn> eBook reading devices; their only purpose in their electronic life was to show electronic texts. It seemed that so much attention was paid to the small packages of plastic and silicon that the devices themselves were referred to as "eBooks". It never really seemed clear what the textual content was called.</p> + +<p>One thing was clear, though: there needed to be some way for this textual content to somehow interoperate with both devices. Either company assumed it could win any war of device creation and marketing, but there were more immediate concerns: if the market for these new devices was to explode as these two companies hoped, they needed the help of the publishers from whom the textual content originated. They knew that publishers would not want to create electronic versions of their text in two separate formats, one for the Rocket eBook and another for the Softbook Reader.</p> + +<p>In late 1998 these two companies were joined by a third: Microsoft. Together these corporations formed an informal group of companies that vowed to prevent a "VHS vs. Betamax" war of formats in the eBook industry by inventing a common format in which electronic information could be stored. The Open eBook (OEB) Authoring Group they formed set out to create a specification that would allow publishers to release content in one format and know that any of the devices could access the stored information.</p> + +<p>Further divorcing the term "eBook" from the concept of a particular device was Microsoft's announcement in 1999 that it would be releasing the Microsoft Reader software. This software would run on any Windows-based computer and would allow eBooks to be downloaded and read without the need for a dedicated reading device. With the support of these two device manufacturers, a software giant, and other members of the OEB Authoring Group such as Versaware, Nokia, and GlobalMentor, the idea of an electronic book became a marketable idea around which each proponent could advance its own desires of profitability. The term "eBook" began to represent not just electronic text, but electronic text in the context of a new industry that would, it was claimed, change reading forever.</p> + +<h4 id="eBookInevitibility">The eBook as Inevitable</h4> + +<p>At this point we haven't really come any closer to knowing what an eBook is, but we've picked up a few other terms such as "reader" and "publisher" which themselves cry out for definitions. Before inevitably drawing artificial lines in the sand, it would be profitable to examine just what is significant about the eBook as an industry.</p> + +<p>It could be that the "universal format" argument of OEB is somewhat of a hollow one. As you'll learn, some parts of OEB by themselves are inadequate for complex textual content. Furthermore, although some software programs allow you to read OEB-based eBooks directly, on other devices and software products what you'll read is not OEB, but OEB text that has been manipulated and transformed into something specific to that device or software. eBooks in general and OEB in particular do in fact represent something very significant, though: the inevitability of electronic information storage and interaction.</p> + +<ol> + <li><strong>Convenience</strong>. Electronic song storage and listening is already too popular to fade. The convenience and space-saving efficiency of electronic music are no less significant in the world of electronic texts.</li> + <li><strong>Versatility</strong>. Once a book is in electronic format, it can be manipulated and presented in a variety of formats on a number of different devices.</li> + <li><strong>Storage</strong> Books that are stored electronically take up no physical space and can be transported with ease.</li> +</ol> + +<p>eBooks give the promise of true foreverness and universality to information. OEB is significant because its authors were wise enough to base it on several elegant standards that were already popular, robust, and that provide no roadblocks to international access. Will the OEB texts you create five years from now look like the OEB works you create today? Maybe. But because of OEB's foundations, the OEB eBooks you write will either work just as well as they do now or will be easily manipulated so that they can. In short, OEB is important because of the standards-compliant ways it requires you to encode your works. Whatever "OEB" means five years from now, the OEB works of today will still be useful.</p> + +<h3 id="oebMeaning">The Meaning of OEB</h3> + +<p>A year of hard work by the Open eBook Authoring Group led to the release on 16 September 1999 of the <em class="title">Open eBook Publication Structure 1.0</em>. This specification, which has recently been clarified and refined by version 1.0.1, defines a <dfn>publication structure</dfn> or format in which one can store a particular work. A work created in OEB format is called, appropriately, an <dfn>OEB publication</dfn>.</p> + +<p>In early 2000 the OEB Authoring Group became a formal body named the Open eBook Forum (OEBF) (<a href="http://www.openebook.org">http://www.openebook.org</a>). The term "OEB" itself is used in a multitude of contexts. Sometimes the OEB Forum is referred to as "OEB"; at other times, "OEB" refers to the <em class="title">OEB Publication Structure</em> which defines OEB Publications. Here we'll try to be specific about how we use OEB unless the meaning is clear from the context. In general, "OEB" will be used to designate that something has been produced by the OEB Forum, such as the <em>Open eBook Publication Structure</em> itself.</p> + +<p><object data="OEBClassDiagram.png" type="image/png">OEB Class Diagram</object></p> + +<p>The <em>Open eBook Publication Structure</em> is a specification for a document format, but to understand this format in context the specification divides the world into several abstract parts. In particular, a <dfn>publication</dfn> is meant for storing eBook content, and this content is processed and displayed to the user by a <dfn>reading system</dfn>. OEB calls the person reading the content the <dfn>reader</dfn>, which may be confusing to those who use software packages that contain "Reader" in their names.</p> + +<p><object data="OEBActivityDiagram.png" type="image/png">OEB Activity Diagram</object></p> + +<p><em class="rhetoricalQuestion">Is a reading system a piece of software?</em> Perhaps, but it could also be a hardware device. In fact, the reading system could be a piece of software that processes the OEB publication and stores it in a different form to be read by the reader on a hardware device.</p> + +<p><object data="ReadingSystemClassDiagram.png" type="image/png">Reading System Class Diagram</object></p> + +<p>The reading system is a convenient abstraction that allows the OEB publication structure specification to define how an OEB publication must be constructed, as well as how it must be interpreted and presented to a reader. As long as the rules in the <em>OEB Publication Structure</em> are followed, any number of things could work together and be classified as one "reading system". This allows a strict definition of how pieces of a system interact, without restricting innovation in implementing the various system components.</p> + +<p><em class="rhetoricalQuestion">Is the OEB publication actually delivered to the reader?</em> This depends on the particular reading system being used. Some reading systems may combine both the processing and the display of the OEB publication into one piece of software or into one hardware device. In other instances, a reading system may be composed of several components: one piece of software may read the OEB publication and interpret it and store it in a proprietary format that only the second display portion of the reading system can understand. It is then this proprietary version of the text that is used to display the data to the reader. In this scenario, the two pieces together would comprise the reading system.</p> + +<p>OEB does not care what type (if any) of intermediate files are produced before the content is shown to the user. The usefulness of the OEB publication, therefore, is not directly related to the user, but to the publisher. The author and/or publisher must convert content to only <em>one</em> format: the OEB publication structure format. Any OEB-compliant reading system will have the means to either display the OEB publication directly, or to convert it into a format that it can display or allow another component to display.</p> + +<p>The most important task as far as an author or publisher is concerned is therefore ensuring a work is in the OEB publication structure format. Any OEB-compliant reading system will be able to do whatever it needs to do to allow your content to be accessed by a reader.</p> + +<h3 id="usingOEB">Using OEB</h3> + +<p>All examples in this book (and this book itself) should be fully compliant with the <em>Open eBook Publication Structure</em> version 1.0.1. It should be possible to read each example using a OEB reading system that fully complies with the specification. As explained above, various OEB reading systems are available — some that use software combined with hardware, some that use separate software components, and some that can natively read an OEB-encoded work and display the eBook to the reader immediately.</p> + +<p>The Mentoract™ Reader from GlobalMentor, Inc. is one example of a native software-based OEB reading system. To read the example eBooks presented here, simply load an OEB package file or an individual OEB document (both of which will be explained in upcoming chapters) in the Mentoract Reader by selecting <code>File|Open...</code> from the pull-down menu. The Mentoract Reader is written in the Java programming language and can therefore run on a variety of desktop and notebook operating systems. The Mentoract™ Reader is available from <a href="http://www.globalmentor.com/software/reader/">http://www.globalmentor.com/software/reader/</a> as a free download.</p> + +<p>Other software-based reading systems, such as the Microsoft Reader from Microsoft Corporation, require two components for processing an eBook. The first component, such as the ReaderWorks software from OverDrive, Inc., manipulates the OEB files into a proprietary Microsoft file format named LIT. This LIT file can then be read using the Microsoft Reader. ReaderWorks is available from <a href="http://www.overdrive.com/readerworks/">http://www.overdrive.com/readerworks/</a> and the Microsoft Reader is available from the <a href="http://www.microsoft.com/reader/">http://www.microsoft.com/reader/</a> site.</p> + +<p>Various hardware eBook devices exist as well. Each usually comes with the appropriate software to process your OEB files so that they can be used with the device. Check with your specific eBook hardware vendor for more information on regarding the level of OEB support.</p> + +<h3 id="review">Review</h3> + +<h4 id="summary">Summary</h4> +<ul> + <li>In the OEB world, an OEB Publication is processed by a reading system and presented to a reader.</li> + <li>A reading system is an abstract concept; a reading system implementation may be composed of hardware, software, or both.</li> + <li>A reading system may present information to the reader directly from the OEB publication, or it may create one or more intermediate files. The OEB publication structure specification only defines that an OEB publication must be input to the reading system, and that the reading system correctly present the information to the reader.</li> +</ul> + +</body> +</html> diff --git a/lib/ebooks/understandingoeb/chapter2.html b/lib/ebooks/understandingoeb/chapter2.html new file mode 100644 index 00000000..964e25f6 --- /dev/null +++ b/lib/ebooks/understandingoeb/chapter2.html @@ -0,0 +1,442 @@ +<?xml version='1.0'?> +<!DOCTYPE html PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Document//EN" "http://openebook.org/dtds/oeb-1.0.1/oebdoc101.dtd"> +<?xml-stylesheet href="understandingoeb.css" type="text/x-oeb1-css"?> + +<html> +<head> + <link rel="stylesheet" type="text/x-oeb1-css" href="understandingoeb.css" /> +<title>Understanding OEB Chapter 2</title> + <meta name="author" content="Garret Wilson" /> + <meta name="copyright" content="Copyright (c) 2000-2001 Garret Wilson. All rights reserved." /> +</head> + +<body> + +<h2 id="chapter2">2. Understanding an OEB Publication</h2> + +<p>When you write a letter or create a report, you usually think of your end product as one entity: "my essay" or "Ralph's grocery list." Depending on how fancy you get, your document might have several pages with graphs, pictures, links, or even a sound clip. Depending on which application you use to create the document, the pictures might be separate clip art files or they might be embedded directly in the document. You may not know where the pictures are stored, and you may not care.</p> + +<p>Here you'll learn how to create a book in the OEB format by hand. Doing so is straightforward and easy, but there are several things you <em>will</em> have to know about and keep track of, such as the location of whatever graphics (if any) you have in your book. To keep things straight in the discussion, OEB uses the term <dfn>OEB Publication</dfn> to refer to all of the items — the pictures, charts, text, and everything else in your book — that are included in your work. We'll sometimes use just <dfn>publication</dfn> to mean the same thing.</p> + +<p><object data="OEBPublicationClassDiagram.png" type="image/png">OEB Publication Class Diagram</object></p> + +<p>You'll therefore be creating a publication, which consists of several items: an <dfn>OEB Package</dfn>, one or more <dfn>OEB Documents</dfn>, and other related files. The simplest publication would simply have two files: a package and a document. In fact, the first publication we'll create here will be that simple, including the book itself (the document) and a separate file (the package) that simply gives information about the book.</p> + +<h3 id="oebdocument">An OEB Document</h3> + +<p>Let's assume you already have a book. Your book is quite short — only one paragraph long. You've spent hours on every word, and now you're ready to introduce it to the world. Your book reads:</p> + +<blockquote> +Years ago, when strange creatures ruled the earth, the seas were beginning to form, and humans had yet to appear, there lived a young blovjus named Karl. Karl had three siblings: Kris, Krista, and Karla. Being extremely smaller than other blovji his age, Karl constantly ran into trouble at the dinner table. +</blockquote> + +<p>You have yet to decide whether this work is science fiction, poetry, or a science textbook, but you decide to put off that decision until the sequel — right now, the important thing is to get it into OEB format!</p> + +<h4 id="needmarkup">The Need for Markup</h4> + +<p>To publish this work, you would have to decide the format in which it should be stored. The first option would be to simply store the text of the book in a file with no formatting whatsoever. The file might be named <code>karl.txt</code>, and you could use a simple text editor such as the <code>Notepad</code> program that comes with Microsoft Windows. This method, sometimes referred to as <dfn>plain text</dfn> or <dfn>ASCII</dfn>, has several advantages, one of the most important being that your file can be read on basically any computer that has a text editor (most do).</p> + +<p>On the downside, your text doesn't look so great: you can't specify the font, you can't change styles, and you certainly can't embed pictures. Supporting multiple languages quickly becomes a problem, and when you realize that some text editors don't wrap lines, you'll have to go back and manually specify where each line ends.</p> + +<p>You may then decide to use a word processor to publish your work. This certainly works if you plan to print hard copies on a printer, but if you want to distribute your work electronically there are several issues to deal with. Instead of storing your book in plain text in a file, the word processor will add many codes to the file to specify the font, the style, the pictures, the default printer, among other things. If you were to examine your word processor file using a text editor, it might look something like this (although this particular example is completely fabricated):</p> + +<blockquote>@#$5098aa23150J:being @#$@$extremely@!$@...</blockquote> + +<p>You might see some familiar words somewhere in the file, but the rest of the "garbage" comprise codes recognizable to your word processor. The problem that arises is that each word processor uses a different format to store data. In fact, most word processors change storage formats whenever a new version is released, and sometimes have different formats for different operating systems. Furthermore, the format is <em>not</em> something that you could edit manually, without the help of the word processor itself.</p> + +<p>To solve problems such as these, <dfn>markup languages</dfn> were invented. Markup languages allow documents to be created in plain text format, just as we used earlier, with the addition of special symbols called <dfn>markup</dfn>. This allows files to be easily read, transported to several systems, and even edited by hand if needed, as we'll soon do here.</p> + +<p>An early markup language, SGML, stands for "Standard Generalized Markup Language" and was created before the World Wide Web even existed. If you've ever surfed the Web, you've definitely used (though maybe not created) HTML, a particular implementation of SGML which stands for "HyperText Markup Language." Most important to OEB is a markup language named XML, which stands for "eXtensible Markup Language." OEB uses XML to define what markup can be used in a particular document.</p> + +<p>As you've noticed already, OEB, like everything else in the computer industry, is rife with acronyms — don't let that confuse you. To see just how easy it is to create and OEB document, assume you want to emphasize that Karl was <em>extremely</em> small. You might then modify your story as follows:</p> + +<blockquote> +Years ago, when strange creatures ruled the earth, the seas were beginning to form, and humans had yet to appear, there lived a young blovjus named Karl. Karl had three siblings: Kris, Krista, and Karla. Being <code><em></code>extremely<code></em></code> smaller than other blovji his age, Karl constantly ran into trouble at the dinner table. +</blockquote> + +<p>The word "extremely" doesn't look any different — it just has <code><em></code> on one side and <code></em></code> on the other. However, when this gets displayed using an actual OEB reading system, it will look like this: <em>extremely</em>. We refer to the <code><em></code> and the <code></em></code> as the beginning and ending <dfn>tags</dfn>. In this case, "em" stands for "emphasized," and the "em" has to be in lowercase.</p> + +<div class="sidebar" id="markupalphabetsoup"> +<h4 class="sidebarTitle">More Information: Markup Alphabet Soup</h4> +<p>Standard Generalized Markup Language (SGML) can be considered the parent of all the markup languages we'll be discussing here. In reality, SGML is more like a markup language construction set — it allows one to create other markup languages by defining which tags can be used, for example. The Hypertext Markup Language (HTML), used on the World Wide Web, is a specific <dfn>application</dfn> of SGML. That is, SGML was used to create a certain set of tags and other markup to be used in the web; this set of tags is what is known as HTML.</p> + +<p>SGML is a very broad, generic language, allowing other markup languages to be constructed with a wide range of possibilities in the way actual tags are used. While this allows a lot of flexibility in designing markup languages using SGML, it's somewhat more difficult to actually process the documents based upon markup languages created with SGML. HTML in particular is notorious for allowing so many possible tag representations that in many cases it is ambiguous as to what was intended.</p> + +<p>In order to make SGML easier to use, easier to process, and to increase its popularity, the eXstensible Markup Language (XML) was created. XML simply takes the rules of SGML and makes them stricter. XML is therefore a subset of SGML, and all correct XML documents will be correct SGML documents. This doesn't necessarily work the other way around, though: even though HTML is an application of SGML, many (perhaps most) HTML documents are not correct XML documents because they don't meet XML's stricter rules.</p> + +<p>The OEB publication structure is an application of XML in the same way HTML is an application of SGML. The OEBPS uses XML to define a set of tags to be used for storing electronic book information. OEB documents are by definition correct XML documents. Since XML is a subset of SGML, this means that all correct OEB documents are by definition correct SGML documents.</p> + +<p>To say that XML has become popular is certainly an understatement; indeed, it's likely that in the future you can ignore the fact that SGML even exists. What about HTML, though? It's still used on the web and, HTML being an SGML application only, most HTML documents don't meet the strict requirements of XML. To address this situation, the World Wide Web Consortium has now released the XHTML specification at <a href="http://www.w3.org/TR/xhtml1/">http://www.w3.org/TR/xhtml1/</a>. XHTML is a modified version of HTML that correctly follows the rules of XML. Since XML is the way of the future, it is recommended you use XHTML for creating new web pages.</p> +</div> + +<h4 id="usingxml">Using XML</h4> + +<p>XML is powerful, but it's quite a simple markup language to use. Its basic rule is that markup consists of a beginning <dfn>tag</dfn> and a matching ending <dfn>tag</dfn>, and this pair of tags says something about the text which appears between them. In our example above, the beginning OEB tag <code><em></code> and the ending OEB tag <code></em></code> mean that the text between them should be emphasized, which usually means that they should be displayed in italics. In XML, an ending tag always has the same name as its beginning tag, with an extra slash (/) at the beginning. We usually refer to the <code><em></code> <code></em></code> tag pair in general as simply the "<code><em></code> tag" or more correctly, the "<code><em></code> element" which refers to both the beginning and ending tags and all text between them.</p> + +<ul> + <li><strong>XML Rule 1:</strong> Every beginning tag must be matched by an ending tag which has the same name, except that the ending tag begins with a forward slash (/).</li> +</ul> + +<p>Another important OEB tag to know about is the <code><p></code> tag, which indicates a paragraph. (You know by now that the <code><p></code> tag has a beginning tag part, <code><p></code>, and ending tag part, <code></p></code>.) Your soon-to-be bestseller, to correctly use OEB, should use the <code><p></code> tag for each paragraph. Since you have only one paragraph in your story, adding the <code><p></code> tag would look like this:</p> + +<blockquote> +<code><p></code>Years ago, when strange creatures ruled the earth, the seas were beginning to form, and humans had yet to appear, there lived a young blovjus named Karl. Karl had three siblings: Kris, Krista, and Karla. Being <code><em></code>extremely<code></em></code> smaller than other blovji his age, Karl constantly ran into trouble at the dinner table.<code></p></code> +</blockquote> + +<p>You'll notice that the <code><em></code> tag is inside the <code><p></code> tag. That's fine. In fact, there's even a name for it: a <dfn>nested tag</dfn>. OEB has certain rules about which tags can go inside which other tags, but one thing that applies to <em>all</em> nested XML tags (OEB tags included), is that they must fit neatly inside one another and not be crossed. In other words, <code><p></code><code><em></code><code></em></code><code></p></code> is fine, but <code><p></code><code><em></code><code></p></code><code></em></code> is not.</p> + +<ul> + <li><strong>XML Rule 2:</strong> A nested tag must have both its beginning and ending tags inside the tag in which it is found; that is, two tags cannot be crossed.</li> +</ul> + +<p>At this point you may be wondering, <em class="rhetoricalQuestion">If the less than (<) and greater than (>) symbols are markup characters, used to indicate tags, how do I present them in the text simply as characters, not as markup?</em> If you use one of these characters in your OEB document, it's likely to be confused as a tag, even if you're writing a mathematical expression such as <code>1 + 2 < 4</code>. For this reason, it is illegal in XML to use the less than (<) or greater than (>) character literally except as part of markup.</p> + +<p>To represent one of these characters, you'll need to use a <dfn>general entity</dfn>, which takes the form <code>&<em>entityName</em>;</code>, replacing <code><em>entityName</em></code> with the name of the character. To represent the less than (<) character, for example, you would use <code>&lt;</code>, and to represent the greater than (>) character you would use <code>&gt;</code>. This implies another question: <em class="rhetoricalQuestion">If the ampersand (&) character is used in general entities, how can I place an ampersand itself in the text?</em> There is a general entity for ampersand (&) as well: &amp;.</p> + +<p>XML defines five general entities that may be used in any XML document, including OEB documents. These are &amp; (&), &lt; (<), &gt; (>), &apos; ('), and &quot; (").</p> + +<ul> + <li><strong>XML Rule 3:</strong> A general entity takes the form <code>&<em>entityName</em>;</code> and represents one or more characters by name. XML defines five general entities that may always be used: &amp; (&), &lt; (<), &gt; (>), &apos; ('), and &quot; (").</li> +</ul> + +<h4 id="creatingoebdocument">Creating an OEB Document</h4> + +<p>There are only two more tags you should know about before you create your first OEB document: <code><html></code> and <code><body></code>. There's nothing difficult here, it's just a requirement set forth by OEB for a standard OEB document: each document must be inside an <code><html></code> tag, and the actual text of your work must be inside a <code><body></code> tag. You'll learn why later. For now, they are easy enough to add:</p> + +<blockquote> +<code><html></code><br /> +<code><body></code><br /> +<code><p></code>Years ago, when strange creatures ruled the earth, the seas were beginning to form, and humans had yet to appear, there lived a young blovjus named Karl. Karl had three siblings: Kris, Krista, and Karla. Being <code><em></code>extremely<code></em></code> smaller than other blovji his age, Karl constantly ran into trouble at the dinner table.<code></p></code><br /> +<code></body></code><br /> +<code></html></code> +</blockquote> + +<p>That's it! You've created your first OEB document. Although it's not a complete <em>OEB publication</em>, it is a an <em>OEB document</em>. The way the OEB Publication Structure 1.0 was written, each OEB document is also more or less an HTML file, which means that you can use an Internet World Wide Web browser to look at the document, even though your entire OEB publication isn't yet finished. Just name the file <code>karl.html</code>, for example, and load it into your favorite Web browser application.</p> + +<p>OK, actually, it's an HTML document but not <em>quite</em> an OEB document. Why? Because it doesn't <em>say</em> it is. The document needs to declare that it is an OEB document, and doing so requires two more lines that are always the same in OEB documents. Again, you'll learn more about these lines later, but in short, the first one says, "I'm an XML file:"</p> + +<blockquote> +<code><?xml version='1.0'?></code> +</blockquote> + +<p>(Note that this line uses an single quotes (') rather than double quotes ("). As in most cases in XML, either can be used.)</p> + +<p>The second one says, "Specifically, I'm an OEB document file — even more specifically, a 1.0.1 OEB document file:"</p> + +<blockquote> +<code><!DOCTYPE html PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Document//EN" "http://openebook.org/dtds/oeb-1.0.1/oebdoc101.dtd"></code> +</blockquote> + +<p>These two lines go at the top of the file, making the final OEB document look like this:</p> + +<blockquote> +<code><?xml version='1.0'?></code><br /> +<code><!DOCTYPE html PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Document//EN" "http://openebook.org/dtds/oeb-1.0.1/oebdoc101.dtd"></code><br /> +<code><html></code><br /> +<code><body></code><br /> + <code><p></code>Years ago, when strange creatures ruled the earth, the seas were beginning to form, and humans had yet to appear, there lived a young blovjus named Karl. Karl had three siblings: Kris, Krista, and Karla. Being <code><em></code>extremely<code></em></code> smaller than other blovji his age, Karl constantly ran into trouble at the dinner table.<code></p></code><br /> +<code></body></code><br /> +<code></html></code> +</blockquote> + +<h4 id="formattingoebtext">Formatting OEB Text</h4> + +<p>In this example, we've entered a <dfn>line break</dfn> at the end of each line by pressing the <code>Enter</code> or <code>Return</code> key on the computer keyboard. We've placed line breaks, for example after the <code><html></code> and <code><body></code> beginning tags. We've done this purely out of convenience: it's easier to edit the file with the beginning <code><body></code> tag directly above and in line with the ending <code><body></code> tag, for example.</p> + +<p>Our formatting of the document text (what programmers call the <dfn>source file</dfn>, or the text originally entered before it is displayed) does not always affect the appearance of the OEB document when it is displayed. We could have instead not entered any line breaks, making that section of the file look like this:</p> + +<blockquote> +...<br /> +<code><html></code><code><body></code><code><p></code>Years ago...<code></p></code><code></body></code><code></html></code> +</blockquote> + +<p>Any <dfn>whitespace</dfn> between elements, such as space, tab, and line breaks, are ignored when the document is displayed.</p> + +<ul> + <li><strong>XML Rule 4:</strong> Whitespace characters between elements are ignored; spaces, tabs, and line breaks can therefore be used arbitrarily to aid in text entry.</li> +</ul> + +<p>What about whitespace that appears in displayed sections, such as inside the beginning and ending <code><p></code> tags? They obviously aren't ignored; when your document is displayed, spaces appear between words. However, multiple whitespace characters are replaced by a single space before being displayed.</p> + +<ul> + <li><strong>OEB Rule 1:</strong> (<em>Display of Whitespace</em>) If two or more whitespace characters (such as spaces, tabs, and line breaks) appear in a row, they will be <dfn>collapsed</dfn> into (that is, replaced by) a single space character before being displayed.</li> +</ul> + +<p>This means that the following examples will all be displayed identically:</p> + +<blockquote> +<code><p></code>Years ago, when strange creatures ruled the earth...<code></p></code> +</blockquote> + +<blockquote> +<pre><code><p></code>Years ago,<br /> when strange creatures<br />ruled the earth...<code></p></code></pre> +</blockquote> + +<p>Both of these examples will collapse all spaces, tabs, and line breaks into single spaces, displaying the following:</p> + +<blockquote>Years ago, when strange creatures ruled the earth...</blockquote> + +<h3 id="oebpackage">An OEB Package</h3> + +<p>Half of the job is now done and you have an OEB document. The other half of an OEB publication, as you learned earlier, is an OEB package. The package is where an <dfn>OEB Reading System</dfn> (such as a software reader or a separate eBook device) will look to find out information about your book. What sort of things would a reading system need to know before displaying your book? At minimum, there are three things that a reading system <em>must</em> know:</p> + +<ol> + <li>Which book is this?</li> + <li>What files are in the book?</li> + <li>In what order should the files be displayed?</li> +</ol> + +<p>Although the first item sounds reasonable, for your short masterpiece the last two items may seem ridiculous; there is, after all, only one document — and it's obvious in what order it should be displayed! As we discussed at the beginning of this chapter, though, many people will have several documents and even pictures in their masterpieces. While OEB certainly could have created an exception for one-document publications (and may even decide to do this in a future version of the specification), currently you still need to specifically supply information you may think is obvious. Besides, you may want more than one document in your sequel, so you would have had to learn this information anyway!</p> + +<p>The OEB package is an XML file just like the OEB document, and accordingly follows XML rules, including the ones you've learned already. Instead of using HTML tags (as the OEB document does), it will use a special set of tags made especially for an OEB package.</p> + +<p>The first two lines look very similar to the first two lines of an OEB document. The first one says, "I'm an XML file, too:"</p> + +<blockquote> +<code><?xml version='1.0'?></code> +</blockquote> + +<p>The second one says, "I'm not an OEB document, though; I'm an OEB <em>package</em>:"</p> + +<blockquote> +<code><!DOCTYPE package PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Package//EN" "http://openebook.org/dtds/oeb-1.0.1/oebpkg101.dtd"></code> +</blockquote> + +<p>Like all XML files, there is a beginning and ending tag which together contain the main part of the file. In the OEB document, it was the <code><html></code> tag. In contrast, the OEB package uses the <code><package></code> tag (for obvious reasons), making the "outside" portion of the package look like this:</p> + +<blockquote> +<code><?xml version='1.0'?></code><br /> +<code><!DOCTYPE package PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Package//EN" "http://openebook.org/dtds/oeb-1.0.1/oebpkg101.dtd"></code><br /> +<code><package></code><br /> + <em>Actual package goes here...</em><br /> +<code></package></code> +</blockquote> + +<p>Inside the package are several required sections; each one answers one of the questions raised above. Each section has its corresponding tag which reflects the function of that section: <code><metadata></code>, <code><manifest></code>, and <code><spine></code>:</p> + +<blockquote> +<code><?xml version='1.0'?></code><br /> +<code><!DOCTYPE package PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Package//EN" "http://openebook.org/dtds/oeb-1.0.1/oebpkg101.dtd"></code><br /> +<code><package></code> + <blockquote> + <code><metadata></code><br /> + <em>Which book is this?</em><br /> + <code></metadata></code> + </blockquote> + <blockquote> + <code><manifest></code><br /> + <em>What files are in the book?</em><br /> + <code></manifest></code> + </blockquote> + <blockquote> + <code><spine></code><br /> + <em>In what order should the files be displayed?</em><br /> + <code></spine></code> + </blockquote> +<code></package></code> +</blockquote> + +<p>As we examine the structure of the OEB package, we'll display the text using spaces and tabs so as to make the sections easier to read. When you create your document, you can enter the package in any way you like, using spaces, tabs, or new lines. In fact, XML (and OEB) doesn't even care if everything is entered on one line — it's just harder for you to read that way, so we've decided not to do that here.</p> + +<h4 id="packageelement">The <code><package></code> Element</h4> + +<p>The surrounding <code><package></code> element, made up of the <code><package></code> and <code></package></code> tags, is pretty straightforward except that it specifies a unique identifier which will be used later for identifying the document. The exact unique identifier you used is up to you. In this case, it might be appropriate to use the identifier, "karlpackage", like this:</p> + +<blockquote> +<code><package unique-identifier="karlpackage"></code> +</blockquote> + +<p>You'll notice that we specify the identifier inside the tag itself! In XML terms, <code>unique-identifier</code> is referred to an <dfn>attribute</dfn> of the tag.</p> + +<ul> + <li><strong>XML Rule 5:</strong> An element's beginning tag may have one or more attributes in the form <code>attributeName="value"</code> or <code>attributeName='value'</code>.</li> +</ul> + +<p>The value can be surrounded by single or double quotes, as long as you are consistent on both sides of the value.</p> + +<h4 id="packagemetadata">The Package Metadata</h4> + +<p>The first section inside the <code><package></code> element contains metadata. In answering the question, "Which document is this?" the <code><metadata></code> element contains several elements, each of which specify something about the book, such as its title and author(s). These items are called <dfn>metadata</dfn> items, hence the name of the element.</p> + +<p>In an added twist, the elements in the metadata section are inside another element named <code><dc-metadata></code>. The OEB Authoring Group did not create these metadata identifiers from scratch; instead, they used a set of metadata identifiers already defined by a group named the <a href="http://purl.org/dc/">Dublin Core</a>. Since the OEB publication structure allows you to create your own metadata items, the Authoring Group decided to group together the special metadata items from the Dublin core inside its own <code><dc-metadata></code> element. Moreover, the <code><dc-metadata></code> element takes certain attributes that specify that these metadata are Dublin Code metadata. Your book's metadata section, therefore, might turn out to look something like this:</p> + +<blockquote> +<code><metadata></code> + <blockquote> + <code><dc-metadata xmlns:dc="http://purl.org/dc/elements/1.0/" xmlns:oebpackage="http://openebook.org/namespaces/oeb-package/1.0/"></code> + <blockquote> + <code><dc:Title></code>Karl the Kreature<code></dc:Title></code><br /> + <code><dc:Identifier id="karlpackage" scheme="ISBN"></code>123456789X<code></dc:Identifier></code><br /> + <code><dc:Creator role="aut"></code>Jane Doe<code></dc:Creator></code> + </blockquote> + <code></dc-metadata></code> + </blockquote> +<code></metadata></code> +</blockquote> + +<p>The parts from the above example that will change for each book are the metadata elements: the required elements <code><dc:Title></code> and <code><dc:Identifier></code>, and the optional (but important to you!) element <code><dc:Creator></code>. The metadata elements in this section all begin with "dc:", another requirement that simply specifies that these are Dublin Core metadata.</p> + +<p>The <code><dc:Title></code> element is simple enough: it holds the title of the book. Similarly, the <code><dc:Identifier></code> element holds an identifier that hopefully uniquely identifies the book in the world, even if two books by two separate authors have identical titles. Since there are several methods of identifying books uniquely, the <code>scheme</code> attribute is necessary to specify the identifier used. In this case, we're using an ISBN for the identifier, so we set <code>scheme="ISBN"</code>.</p> + +<p>As there are several methods of uniquely identifying a single book, the OEB Authoring Group allowed for several methods to be used together in the same package. However, one identifier must be chosen as the main identifer; this identifier's element must have an <code>id</code> attribute set to the unique ID we specified earlier in the beginning <code><package></code> tag. Here we only have one identifier, and we've appropriately set the <code>id</code> attribute to <code>id="karlpackage"</code>.</p> + +<p>You can identify yourself as the creator of the work using the <code><dc:Creator></code> element. The <code>role</code> attribute, is optional, specifying what role you played during the creation of the book. Common values are <code>"aut"</code> (representing "author"), <code>"edt"</code> ("editor"), and <code>"trl"</code> ("translator"). Probably the role used the most, and the one recommended here that should always be included, is <code>"aut"</code>. As with <code><dc:Identifier></code>, you can include several <code><dc:Creator></code> elements to identify several creators of your work.</p> + +<h4 id="packagemanifest">The Package Manifest</h4> + +<p>The next section of the package is referred to as the <dfn>manifest</dfn>, holding information about which files should be included with the book. The Open eBook specification was designed to be distributed and read on a variety of systems and platforms; the manifest guarantees that each system can have a complete list of the minimum files that will be needed to display the contents of the book.</p> + +<p>Each item in the manifest specifies three things:</p> + +<ul> + <li>A unique identifier for the item, so that other parts of the book can unambiguously refer to it.</li> + <li>The name of the file in which the actual item is stored.</li> + <li>The type of the item (such as a document or a picture).</li> +</ul> + +<p>The manifest of our example, then, will be quite simple:</p> + +<blockquote> +<code><manifest></code> + <blockquote> + <code><item id="karl" href="karl.html" media-type="text/x-oeb1-document"></code> + </blockquote> +<code></manifest></code> +</blockquote> + +<p>Each item in the book will be represented by an <code><item></code> element. Here, there is only one item in the book, the OEB document we created earlier. You can choose any unique ID you like; here we'll use <code>id="karl"</code>. For the <code>href</code> attribute (so-named from the hypertext references used in HTML), specify the filename you gave the OEB document. There are a standard set of <code>media-type</code> attribute values you can use, such as <code>"image/jpeg"</code> and <code>"image/png"</code> for certain types of images. In this case, the item is an OEB document, so we must state as much by setting <code>media-type="text/x-oeb1-document"</code>.</p> + +<h4 id="packagespine">The Package Spine</h4> + +<p>Now that we've given information about the book and specified which items are in the book, the last required step is to specify the order in which the book should be read, and this is done inside the <code><spine></code> element. Although electronic books bring all sorts of possibilities as far as interaction and reader-influenced reading orders, there must still be one default reading order specified, or what the OEB specification refers to as the <dfn>primary linear reading order</dfn>. (Writers of adventure stories that have no predetermined reading order are in luck; how to format such interactive stories will be explained in a later version of this work.)</p> + +<p>The <dfn>spine</dfn> is even simpler than the manifest, because the information about each item has already been specified in the manifest. Therefore, the spine only needs to identify which items from the manifest appear in what order. This implies that only items defined in the manifest can appear in the spine. Furthermore, only OEB documents (that is, items included in the manifest that are of type "text/x-oeb1-document") can appear in the spine. Specifically, only those OEB documents that should be displayed as part of the normal linear reading order of the book should be included in the spine.</p> + +<p>The spine of our book is certainly straightforward. Its one item reference (the <code><itemref></code> element) identifies the one item in the manifest by referencing the unique ID we assigned it: <code>idref="karl"</code>.</p> + +<blockquote> +<code><spine></code> + <blockquote> + <code><itemref idref="karl"></code> + </blockquote> +<code></spine></code> +</blockquote> + +<p>With that, we've answered all three questions a reading system requires, and are thus finished with the OEB package. The complete listings of both the finished document and package appear at the end of this chapter.</p> + +<h3 id="xmlrepresentdata">Using XML to Represent Data</h3> + +<p>You've probably noticed at least two different ways in which we've used XML tag pairs, or elements. The first was to specify formatting: the <code><em></code> element made a section of text appear in italics. The second was to represent data, or information about the work: we used the <code><dc:Creator></code> element to specify the author of the book, without specifying how (or if) the author's name would actually be displayed. The latter is simply for storing information about the book.</p> + +<p>A closer examination reveals that the uses of both of these elements, <code><em></code> and <code><dc:Creator></code>, are actually virtually identical. As it turns out, the <code><em></code> element does not specify that italics should be used; it rather specifies that the text should be emphasized without specifying exactly <em>how</em> the text should be emphasized. Although the default display method for text inside an <code><em></code> element is to use italics, it's certainly conceivable that you could decide later to display emphasis using the color red, so that your book displays, "Being <span style="color: red;">extremely</span> smaller..." instead of "Being <span style="font-style: italic;">extremely</span> smaller..."</p> + +<p>If you consistently use <code><em></code> to represent emphasis, it's relatively simple using XML (and, by definition, OEB) to change how emphasized text appears — without changing the actual text of your book! This is an important concept in creating documents, and it's often referred to as a <dfn>separation of content and presentation</dfn>. As you'll learn soon, the way a document appears should be kept distinct (in a completely separate file, in fact) from the actual content of your book.</p> + +<ul> + <li><strong>OEB Tip 1:</strong> (<em>Separation of Content and Presentation</em>) Do not use an element to specify how text should appear, but rather use elements to specify the content or meaning of sections of your work.</li> +</ul> + +<p>To provide an example of how useful it is to encode <em>meaning</em> into a document rather than trying to specify how a document should be displayed, consider the following extract:</p> + +<blockquote> +<p>In the Urdu language, there is a class of descriptive words called <span style="font-style: italic;">postpositions</span>. These are similar to English prepositions except that they come <span style="font-style: italic;">after</span> the words they modify; hence the name "post"+"position".</p> +</blockquote> + +<p>Since we want "postposition" to be displayed (or <dfn>rendered</dfn>) in italics, it would be tempting at first to use the <code><em></code> tag like this: <code><em></code>postposition<code></em></code>. However, if you take a moment to think about why we want the word "postposition" displayed differently, you'll realize that we really don't want to emphasize the word but want rather to indicate that we are defining the word for the first time.</p> + +<p>There so happens to be an OEB tag that does just that — the <code><dfn></code> tag specifies that a new word is being defined or used for the first time. Text which uses the <code><dfn></code> tag is also usually displayed in italics as well, so you might wonder why it matters which tag is used. The concept of separation of content and presentation answers this question. What if we make a reading system that automatically generates a glossary in the back of the book, listing all the new terms introduced and where they were first defined? If we have used the <code><dfn></code> tag in the correct places, these terms could be found easily and placed in the glossary automatically.</p> + +<p>It's important to note that, in the section above, we would not want to use the <code><dfn></code> tag for the second italicized word, "after." Instead, we would want to use the <code><em></code> tag; we are not wanting to define the word "after," but merely emphasize the position of a "postposition". Keeping in mind our concept of separation of content and presentation, we'd probably enter the above section like this:</p> + +<blockquote> +<p><p>In the Urdu language, there is a class of descriptive words called <dfn>postpositions</dfn>. These are similar to English prepositions except that they come <em>after</em> the words they modify; hence the name "post"+"position".</p></p> +</blockquote> + +<p>As you will see later, there are several methods of displaying italics in OEB. A popular method in the past was the <code><i></code> tag, which actually means "italics". This is now considered bad practice, considering the need to separate content from presentation. Unfortunately, since OEB uses many tags from HTML, the <code><i></code> tag is available to use in OEB documents. For reasons we've just explained, we strongly recommend against using the <code><i></code> tag in your documents, and using the <code><em></code> instead in most cases.</p> + +<p>The concept of separation of content and presentation is a very important one, and we'll revisit this topic.</p> + +<p>You now know the basic structure of an OEB publication. There are several tags which we haven't covered yet which you'll want to use when you create real-world documents. After discussing <a href="chapter3.html">styles and style sheets</a>, we'll cover the <a href="chapter4.html">tags you'll normally need</a> when working in the real world.</p> + +<h3 id="review">Review</h3> + +<h4 id="summary">Summary</h4> +<ul> + <li>An OEB Publication consists of an OEB Package, one or more OEB Documents, and other related files such as images.</li> + <li>The OEB Publication Structure is a markup language which follows the rules of XML; therefore, all OEB files are XML files.</li> + <li>OEB in its basic form specifies a set of tags which should be used, always following the rules of XML. OEB also contains the flexibility to use custom tags.</li> + <li>The set of basic tags specified by OEB is very similar to, for better or for worse, the set of tags specified by HTML.</li> +</ul> + +<h4 id="xmlrules">XML Rules</h4> +<ul> + <li><strong>XML Rule 1:</strong> Every beginning tag must be matched by an ending tag which has the same name, except that it begins with a forward slash (/). (Special <a href="chapter4.html#emptyElement">empty tags</a> will be discussed later.)</li> + <li><strong>XML Rule 2:</strong> A nested tag must have both its beginning and ending tags inside the tag in which it is found; that is, two tags cannot be crossed.</li> + <li><strong>XML Rule 3:</strong> A general entity takes the form <code>&<em>entityName</em>;</code> and represents one or more characters by name. XML defines five general entities that may always be used: &amp; (&), &lt; (<), &gt; (>), &apos; ('), and &quot; (").</li> + <li><strong>XML Rule 4:</strong> Whitespace characters between elements are ignored; spaces, tabs, and line breaks can therefore be used arbitrarily to aid in text entry.</li> + <li><strong>XML Rule 5:</strong> An element's beginning tag may have one or more attributes in the form <code>attributeName="value"</code> or <code>attributeName='value'</code>.</li> +</ul> + +<h4 id="oebrules">OEB Rules</h4> +<ul> + <li><strong>OEB Rule 1:</strong> (<em>Display of Whitespace</em>) If two or more whitespace characters (such as spaces, tabs, and line breaks) appear in a row, they will be <dfn>collapsed</dfn> into (that is, replaced by) a single space character before being displayed.</li> + <li><strong>OEB Tip 1:</strong> (<em>Separation of Content and Presentation</em>) Do not use an element to specify how text should appear, but rather use elements to specify the content or meaning of sections of your work.</li> +</ul> + +<h4 id="oebtags">OEB Tags</h4> +<ul> + <li><code><dfn></code> Specifies that a term is being used for the first time; usually rendered in italics.</li> + <li><code><em></code> Emphasizes text; usually rendered in italics.</li> +</ul> + +<h3 id="exampleoebdocument">Completed Example OEB Document (<code>karl.html</code>)</h3> + +<blockquote> +<code><?xml version='1.0'?></code><br /> +<code><!DOCTYPE html PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Document//EN" "http://openebook.org/dtds/oeb-1.0.1/oebdoc101.dtd"></code><br /> +<code><html></code><br /> +<code><body></code><br /> + <code><p></code>Years ago, when strange creatures ruled the earth, the seas were beginning to form, and humans had yet to appear, there lived a young blovjus named Karl. Karl had three siblings: Kris, Krista, and Karla. Being <code><em></code>extremely<code></em></code> smaller than other blovji his age, Karl constantly ran into trouble at the dinner table.<code></p></code><br /> +<code></body></code><br /> +<code></html></code> +</blockquote> + +<h3 id="exampleoebpackage">Completed Example OEB Package (<code>karl.opf</code>)</h3> + +<blockquote> +<code><?xml version='1.0'?></code><br /> +<code><!DOCTYPE package PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Package//EN" "http://openebook.org/dtds/oeb-1.0.1/oebpkg101.dtd"></code><br /> +<code><package unique-identifier="karlpackage"></code> + + <blockquote> + <code><metadata></code> + <blockquote> + <code><dc-metadata xmlns:dc="http://purl.org/dc/elements/1.0/" xmlns:oebpackage="http://openebook.org/namespaces/oeb-package/1.0/"></code> + <blockquote> + <code><dc:Title></code>Karl the Kreature<code></dc:Title></code><br /> + <code><dc:Identifier id="karlpackage" scheme="ISBN"></code>123456789X<code></dc:Identifier></code><br /> + <code><dc:Creator role="aut"></code>Jane Doe<code></dc:Creator></code> + </blockquote> + <code></dc-metadata></code> + </blockquote> + <code></metadata></code> + </blockquote> + <blockquote> + <code><manifest></code> + <blockquote> + <code><item id="karl" href="karl.html" media-type="text/x-oeb1-document"></code> + </blockquote> + <code></manifest></code> + </blockquote> + <blockquote> + <code><spine></code> + <blockquote> + <code><itemref idref="karl"></code> + </blockquote> + <code></spine></code> + </blockquote> +<code></package></code> +</blockquote> + +</body> +</html> diff --git a/lib/ebooks/understandingoeb/chapter3.html b/lib/ebooks/understandingoeb/chapter3.html new file mode 100644 index 00000000..31f71d8b --- /dev/null +++ b/lib/ebooks/understandingoeb/chapter3.html @@ -0,0 +1,230 @@ +<?xml version='1.0'?> +<!DOCTYPE html PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Document//EN" "http://openebook.org/dtds/oeb-1.0.1/oebdoc101.dtd"> +<?xml-stylesheet href="understandingoeb.css" type="text/x-oeb1-css"?> + +<html> +<head> + <link rel="stylesheet" type="text/x-oeb1-css" href="understandingoeb.css" /> +<title>Understanding OEB Chapter 3</title> + <meta name="author" content="Garret Wilson" /> + <meta name="copyright" content="Copyright (c) 2000-2001 Garret Wilson. All rights reserved." /> +</head> + +<body> + +<h2 id="chapter3">3. Styles and Style Sheets</h2> + +<p>One of the most integral parts of OEB is the concept of <dfn>style sheets</dfn>. A style sheet is a tool that helps to separate content from presentation and is used not only with OEB but with XML and (increasingly) with HTML web pages as well. You've been told that the separation of content and presentation is a "Good Thing" — after you understand style sheets, you'll begin to see why this concept is so important.</p> + +<p>Style sheets have a few unusual properties: you could write OEB-compliant eBooks all your life and never use a stylesheet. Stranger still, someone might create a style sheet that could be used with your work long after you've written it. That's what makes stylesheets so useful: they represent the <dfn>encapsulation</dfn> (or bundling) of the presentation part of the <em>publication=content+presentation</em> equation, and therefore help keep the two completely separate. Your OEB document, with its text and tags, is the content and holds the meaning of what you're written; the style sheet(s) hold how your work is presented to the user.</p> + +<p>How is this supposed to work? Imagine that you're writing a book to be published by the Happy Publishing Company. Happy has its own ideas about how your book should look — that is, which fonts it should have, how it should be spaced, etc. (Happy Publishing Company might have ideas about what your book should <em>say</em> as well, but that's another story; it should be clear to you by now that these are two separate concepts.) If you write a book and concentrate on the content, Happy Publishing Company can simply use its style sheet with your work after you're finished, and the book will look just like Happy wants it to. What happens when you change publishers? Your new publisher can simply substitute their standard style sheet and your book will suddenly take on its new look, without your having to make one single change to the actual content of the book — <em>if</em> you've correctly separated the content from the presentation.</p> + +<p>That's a big "if", and one that takes a little thinking on your part, at least to begin with. Since OEB comes from a legacy of HTML which didn't stress as strongly such a separation of content and presentation, OEB in some cases makes it easier for you to put style information where it doesn't belong: mixed in with the content of your work. It is hoped that you'll be able not only to overcome these temptations, but to understand why the current emphasis of information storage and retrieval formats is going in a direction that stresses that these elements be separated.</p> + +<p>Before going any further into the theory of style sheets, we'll examine a few examples of using styles, from the least desired to the most appropriate.</p> + +<h3 id="emphasisrevisited">Emphasis Revisited</h3> + +<p>The previous chapter hinted that OEB has a tag named <code><i></code> which causes the specified text to be rendered (or displayed) in italics. We've told you that this is not recommended.</p> + +<ul> + <li><strong>Not Recommended:</strong> <code><p></code>Being <code><i></code>extremely<code></i></code> smaller than other blovji his age...<code></p></code></li> +</ul> + +<blockquote>Being <span style="font-style: italic;">extremely</span> smaller than other blovji his age...</blockquote> + +<p>What's the alternative? We've stressed that in many places, the <code><em></code> tag, specifying "emphasis", can be used in place of the <code><i></code> tag for the same effect. We've answered the question, "If they both have the same effect, what's the difference?" by saying that <code><em></code> specifies simply that a section of text should be emphasized, not <em>how</em> the text should be emphasized.</p> + +<ul> + <li><strong>Recommended:</strong> <code><p></code>Being <code><em></code>extremely<code></em></code> smaller than other blovji his age...<code></p></code></li> +</ul> + +<blockquote>Being <span style="font-style: italic;">extremely</span> smaller than other blovji his age...</blockquote> + +<p>The point is that, although <code><em></code> is usually rendered in italics by default, there's nothing that prevents you from changing how <code><em></code> gets displayed — nothing except a lack of knowledge, of course. We'll now address how that's done.</p> + +<p>OEB has specified that every element has an optional <code>style</code> attribute. As you might guess, you can use this attribute to override the style of that element. We'll explain later the specifics of the style information, but here's a quick example of how you could guarantee that <code><em></code> is displayed in italics:</p> + +<ul> + <li><strong>Not Recommended:</strong> <code><p></code>Being <code><em style="font-style: italic"></code>extremely<code></em></code> smaller than other blovji his age...<code></p></code></li> +</ul> + +<blockquote>Being <span style="font-style: italic;">extremely</span> smaller than other blovji his age...</blockquote> + +<p>If you wanted the emphasized text to not only be displayed in italics but also in red, you'd use the following:</p> + +<ul> + <li><strong>Not Recommended:</strong> <code><p></code>Being <code><em style="color: red"></code>extremely<code></em></code> smaller than other blovji his age...<code></p></code></li> +</ul> + +<blockquote>Being <span style="font-style: italic; color: red">extremely</span> smaller than other blovji his age...</blockquote> + +<p>Notice that the text is still displayed in italics, because we didn't specify that the italics should be removed (there's a way to do this, which you'll see later). Instead, we specified that the color red should be added to whatever style was there already.</p> + +<p>As you can see, we don't recommend this method, and it's not hard to figure out why. If you specify the style of the tag directly, you've gained nothing over just using the <code><i></code> tag and manually making changes. After all, this method still mixes our presentation information inside the content of our book.</p> + +<p>Let's continue with the assumption that we'd like all emphasized text to be displayed using not only italics, but also the color red. We'll also assume you've followed the recommendations here and used the <code><em></code> tag for emphasized text. The secret to style sheets is that they use the same format you just saw used inside the <code>style</code> attribute, only that they've been removed from the content and placed in a separate location. This is the first way we could do it:</p> + +<ul> + <li><strong>Recommended:</strong></li> +</ul> + +<blockquote> +<code><?xml version='1.0'?></code><br /> +<code><!DOCTYPE html PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Document//EN" "http://openebook.org/dtds/oeb-1.0.1/oebdoc101.dtd"></code><br /> +<code><html></code><br /> +<code><head></code><br /> + <code><title></code>Karl the Creature<code></title></code><br /> + <code><style></code>em {color: red}<code></style></code><br /> +<code></head></code><br /> +<code><body></code><br /> + <code><p></code>...Being <code><em></code>extremely<code></em></code> smaller than other blovji his age...<code></p></code><br /> +<code></body></code><br /> +<code></html></code> +</blockquote> + +<blockquote>Being <span style="font-style: italic; color: red">extremely</span> smaller than other blovji his age...</blockquote> + +<p>This example correctly specifies that <em>all</em> occurrences of the <code><em></code> element should be displayed in red. Furthermore, the actual body of the document does not need to be changed; all text marked as emphasized will be shown with the new style.</p> + +<p>In the previous chapter we touched on the essential components of an OEB document. In the above example you'll notice several elements we didn't discuss. OEB specifies that the <code><head></code> element is optional in a document, but if included it should contain a <code><title></code> element. The element we're interested in, <code><style></code> must be inside the <code><head></code> element. This means that whenever we include a <code><style></code> element, we'll have to include both a <code><head></code> and a <code><title></code> element as well. Both of these elements will be discussed in depth later. For now, note simply that we are specifying style information outside the actual body of the document, in a separate element named <code><style></code>.</p> + +<p>You might wonder at this point, if we were to take our concept of separation of content and presentation to the extreme, why we place any style information at all in the same file as the document. Wouldn't it be better to store presentation information in a completely separate location? Yes, in many circumstances it would. We'll explain how a little later; for now, to make things simple, we'll keep the style information in the same file as the document.</p> + +<h3 id="cascadingstylesheets">Cascading Style Sheets (CSS)</h3> + +<p>You've seen how OEB has used XML to create a set of tags and rules to use those tags, in many instances borrowing tags from HTML. Similarly, there is a set of rules for specifying style information in an OEB document. Here, OEB borrowed the format of a specification for <dfn>Cascading Style Sheets</dfn> (CSS). Although there are a few differences between OEB's version of CSS and standard CSS, these differences are very minor; in most instances, OEB simply specifies which CSS constructs cannot be used. There's only one instance where OEB actually creates new identifiers. For the most part, then, if you're familiar with CSS at all you can apply your knowledge to OEB.</p> + +<p>XML, on which OEB is based, uses a set of elements, each of which have a beginning and ending tag. CSS, on the other hand, uses different constructs. In general, CSS styles consist of <dfn>selectors</dfn> and <dfn>declarations</dfn>, the latter of which contains one or more sets of a <dfn>property</dfn> and a <dfn>value</dfn>. Although this sounds complicated, it's quite simple in practice; once you understand these basic parts, there isn't much more to learn for most things you'll want to do.</p> + +<div class="sidebar" id="cssvsxsl"> +<h4 class="sidebarTitle">More Information: CSS vs. XSL</h4> + +<p>OEB uses XML to store content, but uses a separate language named CSS to store style (presentation) information. Why must one use two separate formats? Why doesn't OEB simply use XML for storing both content and presentation information, even if these things are stored separately?</p> + +<p>That's a legitimate and important question. It so happens that there is a method for specifying style and formatting information using XML — it's called <dfn>XML Style Language</dfn> (XSL). Since it uses XML, XSL doesn't force one to learn another format just to create style information, and XSL is even more powerful than CSS</p> + +<p>Why doesn't OEB use XSL instead of CSS, then? There are several reasons. When the OEB Publication Structure 1.0 specification was being written, there were not any tools available specifically for viewing OEB documents. Since an OEB document is very similar to a normal HTML document, it was possible however to view OEB documents using a web browser. The OEB Authoring Group chose to use CSS, which most browsers at the time supported, rather than to use XSL, which most browsers couldn't handle.</p> + +<p>More importantly, the XSL specification was not yet finalized at the time the OEB specification was being written, so any use of XSL would have had to predict the final form in which XSL would appear. OEB therefore relies primarily on CSS, although future version of OEB may well rely on XSL. It's even possible to use XSL stylesheets with OEBPS 1.0, as long as an appropriate CSS stylesheet is included for those reading systems that do not understand XSL.</p> + +</div> + +<p>The particular style we specified for <code><em></code> looks like this:</p> + +<blockquote><code>em {color: red}</code></blockquote> + +<p>This style represents how most styles you specify will appear. Each will have the same parts introduced earlier:</p> + +<ul> + <li><strong>selector</strong> - <code>em</code> - Specifies which elements will be "selected" to receive this style. In this case, we indicate that this style applies to every <code><em></code> element.</li> + <li><strong>declaration</strong> - <code>{color: red}</code> - Specifies the style of the selected element(s). In this case, we've specified that the color of the text should be red. As noted earlier, the declaration is divided up into one or more properties and corresponding values.</li> + <li><strong>property</strong> - <code>color</code> - Specifies a particular property to be modified. Here the color of the text is being modified. Each declaration could modify several properties — both the color and the size of the text could be changed, for example.</li> + <li><strong>value</strong> - <code>red</code> - The new value of the property. Each property will have at least one value, although more than one value can be specified in some instances in which the first value might not be available.</li> +</ul> + +<p>There are, of course, a few more intricacies which we'll go into later, especially concerning the selector part of the equation. There are probably a couple of questions about exactly what's happening here that should probably be cleared up first.</p> + +<p><em class="rhetoricalQuestion">Why does my emphasized text show up both in red <em>and</em> italics, even though I specified just the color red?</em> If you specify no styles at all, there is a default style which will be applied to text between OEB tags. In OEB, the <code><em></code> tag is usually rendered in italics by default. In fact, the effect is exactly as if you had specified the following style in your document:</p> + +<blockquote><code>em {font-style: italic}</code></blockquote> + +<p>In other words, there's effectively a default style sheet used which specifies the standard style of OEB elements. In our example, specifying that the color red should be used did not state that the default style of italics should not be used. The color red was therefore added to the existing default style of italics, giving all text between <code><em></code> tags both the italic style and the color red.</p> + +<p><em class="rhetoricalQuestion">If styles can be specified in multiple places, such as on the actual tag and elsewhere in the document, what happens when I declare the same style in multiple places?</em> This question relates to the previous one. If you specify in the document's <code><style></code> tag, for example, the style <code>em {color: red}</code>, then every occurrence of the <code><em></code> tag will be rendered in red. If you specify, using the <code>style</code> attribute, that a particular <code><em></code> tag should have be underlined using <code><em style="text-decoration: underline"></code>, then that particular portion of text will be underlined. But it will also be shown in red, because you've already specified that <em>all</em> occurrences of the <code><em></code> tag should be in red.</p> + +<p>Each particular instance of the <code><em></code> tag, therefore, <dfn>inherits</dfn> the properties already defined for it. Since you specified a property for <em>all</em> <code><em></code> tags, this property <dfn>cascades</dfn> down to each of the individual <code><em></code> tags similar to the way water from a waterfall cascades down to each level of rocks before it reaches the pool below. In fact, that's why CSS uses the name "Cascading Style Sheets."</p> + +<p><em class="rhetoricalQuestion">What happens if the properties I specify in several places conflict with each other?</em> As a rule of thumb, the most specific declaration is used. If you've specified, for example, that all <code><em></code> elements should be red, but then in a particular instance specified that a particular <code><em></code> element should instead be blue, the blue wins.</p> + +<h4 id="cssselectors">CSS Selectors</h4> + +<p>A selector determines (or selects) the element(s) to which a particular style declaration applies. In our example above, <code>em {color: red}</code>, the selector is simple: this style will be applied to every <code><em></code> element. There are several other additions to the selector syntax that make it easy to select exactly which element(s) you prefer.</p> + +<p><strong>Select Multiple Elements:</strong> You could always duplicate a style declaration for several elements with different names, but CSS has an easier way to select several elements for the same style. Just place several element names in a row, separated by commas (,). For example, <code>em, dfn {color: red}</code> would make all emphasized text (<code><em></code>) <em>and</em> all defined words (<code><dfn></code>) appear in red.</p> + +<p><strong>Select Elements Only in Certain Contexts:</strong> So far, we've only seen the <code><em></code> element appear inside a paragraph (<code><p></code>). As we'll see later, emphasized text could appear in several places, such as inside a list or a heading. To specify that <em>only</em> emphasized text inside a paragraph should be red, you would list the nested elements in the correct order, separated by whitespace.: <code>p em {color: red}</code>. This would mean that emphasized text inside a paragraph (e.g. <code><p><em></em></p></code>) would appear in red, but not emphasized text inside a list (e.g. <code><li><em></em></li></code>). Again, we'll discuss lists later; for now, simply realize that an element can appear in different contexts, and CSS provides a way to specify these situations.</p> + +<p><strong>Select Elements by Class</strong> CSS allows a style to be created and given a name, and then later used with any element you decide. After specifying a name (or <dfn>class</dfn>) for a style, you can use the style with a particular element simply by specifying the style name in the <code>class</code> attribute of an element. The <code>class</code> attribute, like the <code>style</code> attribute, is an optional attribute that can be used with many elements.</p> + +<p>For example, instead of explicitly specifying that every <code><em></code> element should appear in red, we could create a class that would allow you to specify to which <code><em></code> element the style applied. A style class is always preceded by a period or full stop character (.), like this: <code>em.colorful {color: red}</code>. We could then specify that a particular emphasized portion of text would use this style:"this is <code><em class="colorful"></code>emphasized<code></em></code> text".</p> + +<p>A style class can be made even more generic by omitting an element designation altogether. A modification of the previous example yields <code>.colorful {color: red}</code> (don't forget the '.' character), a style class which can apply to <em>any</em> element. This change still allows the <code><em></code> tag be made colorful as in the previous example: <code><em class="colorful"></code>emphasized<code></em></code>. Furthermore, the class can be applied to other elements, such as the <code><p></code> tag: <code><p class="colorful"></code>emphasized<code></em></code> would assure that all the text in the specified paragraph appeared in the color red. Note, however, that the text would not appear in italics, since the <code><p></code> tag does not have an italic style by default, as does the <code><em></code> tag.</p> + +<h3 id="linkingstylesheets">Linking to Style Sheets</h3> + +<p>As we've seen, there are several places where we can store style information, from the most specific to the most general:</p> + +<ol> + <li>By putting style information in an element's <code>style</code> attribute.</li> + <li>By specifying a style class in an element's <code>class</code> attribute.</li> + <li>By defining styles in a <code><style></code> element inside the document <code><head></code>.</li> + <li>By defining styles in separate style sheet file linked to the document.</li> +</ol> + +<p>The last method, linking to an external style sheet, has only been touched upon briefly. Using this method is straightforward: simply take the style information from inside the <code><style></code> element and place it inside a separate file (preferably with a ".css" extension). The entire <code><style></code> element can then be removed, and the document can simply specify that it uses the external stylesheet.</p> + +<p>By placing style information in a separate file, we've arrived at our ultimate goal of separating content from presentation. If there are multiple documents in a given book, the style information does not have be be duplicated inside each document; each document can rather <dfn>link</dfn> to one style sheet, which contains all relevant presentation information. Furthermore, a book's style can be changed simply by making the document link to another style sheet. To carry on the example at the beginning of this chapter, if Happy Publishing Company decides it wants to redesign the appearance of its entire selection of books, none of the books' contents need to be changed. Instead, Happy can simply supply an updated style sheet.</p> + +<h4 id="linkelement">Linking Style Sheets with the <code><link></code> Element</h4> + +<p>There are several ways to actually link a style sheet to a document, reflecting the evolution of HTML and markup languages in general. When HTML first allowed style sheets, it specified a <code><link></code> element that appears inside the <code><head></code> element in place of <code><style></code>. After moving our style information out of our sample document, our style link information might look like this:</p> + +<blockquote><code><link href="karl.css" type="text/x-oeb1-css"></code></blockquote> + +<p>As before, the <code>href</code> attribute specifies the style sheet to which the document is linking. The <code>type</code> attribute specifies the type of the style sheet. Although normal CSS style sheets have the type <code>text/css</code>, OEB requires that your standard style sheet have the type <code>text/x-oeb1-css</code> to indicate it meets the modified requirements of OEB style information.</p> + +<p>Using <code><link></code> will make your document compatible with HTML and allow your style information to show up in a typical HTML browser. The <code><link></code> tag is not, however, a standard way of linking XML documents in general, which is why OEB allows (and the authors of this work recommend) another linking mechanism which is standardized for XML.</p> + +<h4 id="linkxml">Linking Style Sheets with XML</h4> + +<p>XML now defines a standard method of linking style sheets to any XML document, which includes OEB documents. This method was still being standardized while the OEB Publication Structure specification was first being written, and that's why OEBPS 1.0 does not give examples of XML style linking. However, on 29 June 1999, version 1.0 of "Associating Style Sheets with XML documents" became an official W3C recommendation, and can be found at <a href="http://www.w3.org/TR/xml-stylesheet/">http://www.w3.org/TR/xml-stylesheet/</a>. This new development was unfortunately missed as OEB was released, so the OEB specification still states that the final form of XML style association has yet to be finalized.</p> + +<p>With the final recommendation of XML style association by the W3C, we can recommend that all OEB books use this method for linking to style sheets. Doing so will ensure that OEB works are standard XML documents that can endure as older versions of HTML fade. Using the XML style association mechanism is very similar to the HTML method:</p> + +<blockquote><code><?xml-stylesheet href="karl.css" type="text/x-oeb1-css"?></code></blockquote> + +<p>The attributes here are identical to those in the <code><link></code> element, and have the same usage. The location in the document, however, is different: the <code><?xml-stylesheet></code> instruction appears before the <code><html></code> element.</p> + +<h3 id="review">Review</h3> + +<h4 id="summary">Summary</h4> +<ul> + <li>OEB allows style sheets to be defined which specify how parts of an OEB document should be displayed or rendered.</li> + <li>Style sheets, when correctly used, help separate the content of a document from its presentation information.</li> + <li>OEB by default uses a modified form of CSS to specify style information.</li> + <li>A particular CSS style consists of a selector (such as <code>em</code>) and a style declaration which consists of one or more properties (e.g. <code>color:</code>) and associated values (e.g. <code>red</code>), such as <code>em {color: red}</code>.</li> + <li>A style can specify a style class that can be used for particular elements inside the <code>class</code> attribute. The style <code>em.colorful {color: red}</code>, for example, can be used with a particular <code><em></code> element: <code><em class="colorful"></code>...<code></em></code>.</li> + <li>Although not normally recommended, style information can be specified for a particular element inside its <code>style</code> attribute, such as <code><em style="color: red"></code>...<code></em></code>.</li> + <li>External style sheets can be associated with the document using the <code><link></code> element, a carryover from HTML, inside the <code><head></code> element.</li> + <li>The recommended standard way for associating a style sheet with a document is to instead use the <code><?xml-stylesheet></code> instruction before the <code><head></code> element.</li> +</ul> + +<h4 id="cssproperties">CSS Properties</h4> +<ul> + <li><code>font-style:</code> Specifies the style of the font; although several values are available, we only addressed <code>italic</code>.</li> + <li><code>color:</code> Specifies the color of the font; although several values are available, we only addressed <code>red</code>.</li> +</ul> + +<h3 id="exampleoebdocument">Completed Example OEB Document with Styles (<code>karl.html</code>)</h3> + +<blockquote> +<code><?xml version='1.0'?></code><br /> +<code><!DOCTYPE html PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Document//EN" "http://openebook.org/dtds/oeb-1.0.1/oebdoc101.dtd"></code><br /> +<code><?xml-stylesheet href="karl.css" type="text/x-oeb1-css"></code><br /> +<code><html></code><br /> +<code><body></code><br /> + <code><p></code>Years ago, when strange creatures ruled the earth, the seas were beginning to form, and humans had yet to appear, there lived a young blovjus named Karl. Karl had three siblings: Kris, Krista, and Karla. Being <code><em></code>extremely<code></em></code> smaller than other blovji his age, Karl constantly ran into trouble at the dinner table.<code></p></code><br /> +<code></body></code><br /> +<code></html></code> +</blockquote> + +<h3 id="examplestylesheet">Completed Example Style Sheet (<code>karl.css</code>)</h3> + +<blockquote> + em {color: red} +</blockquote> + +</body> +</html> diff --git a/lib/ebooks/understandingoeb/chapter4.html b/lib/ebooks/understandingoeb/chapter4.html new file mode 100644 index 00000000..3cf8e130 --- /dev/null +++ b/lib/ebooks/understandingoeb/chapter4.html @@ -0,0 +1,442 @@ +<?xml version='1.0'?> +<!DOCTYPE html PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Document//EN" "http://openebook.org/dtds/oeb-1.0.1/oebdoc101.dtd"> +<?xml-stylesheet href="understandingoeb.css" type="text/x-oeb1-css"?> + +<html> +<head> + <link rel="stylesheet" type="text/x-oeb1-css" href="understandingoeb.css" /> +<title>Understanding OEB Chapter 4</title> + <meta name="author" content="Garret Wilson" /> + <meta name="copyright" content="Copyright (c) 2000-2001 Garret Wilson. All rights reserved." /> +</head> + +<body> + +<h2 id="chapter4">4. Essential OEB Elements</h2> + +<p>You now know the minimum structural requirements of creating a publication in OEB format. You're beginning to understand some of the reasoning behind latest directions of information storage formats such as XML, which OEB is based on. Right now, you could place almost any work in a few OEB documents and an OEB package, and it would at least be legal OEB and work with a compliant OEB reading system. You also know how to create style sheets and associate them with your documents.</p> + +<p>What you've learned so far will work fine for your one-paragraph masterpiece. But once you try to use OEB to create a slightly longer sequel, you'll probably very soon run into some very real needs: "How do I display lists?" "How do I change the font?" "How so I create links from one section of my book to another?" The OEB Publication Structure has some very real answers to these questions. Even better yet, since OEB is built upon XML, the following chapters will show you how to create your own answers in areas that OEB does not yet address.</p> + +<p>You've had a glance at a few elements defined by OEB, such as <code><p></code>, <code><em></code> and <code><dfn></code>. OEB has a substantial number of other tags already defined for you to use; obviously, you'll need to know at least some of the others to do anything useful with OEB. We'll now look at essential elements and styles that you'll need in day-to-day use of OEB. If you've already started putting together an OEB publication, hopefully we'll answer some of the issues you've already encountered. Otherwise, we'll get a lot of common questions out of the way and prepare you for the real-world OEB creation project found in the next chapter.</p> + +<p>It's important to note that the OEB elements discussed here are a basic set of elements defined by OEB. OEB is flexible enough to allow extended documents that include user-defined elements, and this process is likely to be enhanced even more in future OEB versions. Creating user-defined elements is beyond the scope of this current edition, but will likely be addressed in an upcoming version of this book.</p> + +<h3 id="inlineelements">Inline Elements</h3> + +<p>Although XML allows any number of elements to be defined, OEB has defined a certain set of elements to be used in documents. You've seen and used a few of those, such as <code><p></code>, <code><em></code> and <code><dfn></code>. Besides defining which tags can be used, OEB also specifies the location and contexts in which these elements can appear. You've probably understood intuitively, for example, that emphasized text goes inside a paragraph, like this:</p> + +<blockquote><code><p></code>This is <code><em></code>emphasized<code></em></code> text.<code></p></code></blockquote> + +<p>You probably didn't even consider putting a paragraph inside of emphasized text:</p> + +<blockquote><strong>Illegal!</strong> <code><p></code>This is <code><em></code>emphasized text with a <code><p></code>paragraph<code></p></code> inside<code></em></code> the emphasized text.<code></p></code></blockquote> + +<p>As you might have guessed, this sort of construction is not allowed. The elements <code><em></code> and <code><dfn></code> can only appear inside paragraphs (and lists and other similar elements), and are therefore considered <em>inline</em> elements. Those are the elements we'll examine here.</p> + +<div class="sidebar" id="xmlcontentmodels"> +<h4 class="sidebarTitle">More Information: XML Content Models</h4> + +<p>XML could be considered a general markup language that acts as a toolkit for creating other markup languages. OEB uses XML to create its own markup language called the OEB Publication Structure. OEB uses XML not only to create a set of elements to be used (the <dfn>tag set</dfn>), but also to specify where the elements may appear. The specification of the correct locations of elements is called a <dfn>content model</dfn>.</p> + +<p>HTML uses a very lenient content model; a web browser will read HTML files that have elements that appear just about anywhere. This is not only notoriously hard to process, it also results in many ambiguities in what was actually meant by the author of the document. Since we'd like to follow the trend in encoding data and meaning into documents, this ambiguity is not acceptable.</p> + +<p>The content model used by OEB is therefore more strict than traditional HTML, and closely follows <a href="http://www.w3.org/TR/xhtml1/">XHTML</a>, a new version of HTML created specifically to be used with XML. This means that some constructs which could be used in HTML are not allowed in OEB. For example, the inline element <code><em></code> could be used in HTML to make several paragraphs emphasized:</p> + +<blockquote><strong>Legal HTML, Illegal OEB:</strong><br /> + <code><em></code><br /> + <code><p></code>Paragraph 1<code></p></code><br /> + <code><p></code>Paragraph 2<code></p></code><br /> + <code></em></code> +</blockquote> + +<p>Since <code><em></code> is an inline element, this will not work in an OEB document. Fixing this problem is simple, however: just bring the <code><em></code> back inside each <code><p></code> element:</p> + +<blockquote><strong>Legal HTML, Legal OEB:</strong><br /> + <code><p><em></code>Paragraph 1<code></em></p></code><br /> + <code><p><em></code>Paragraph 2<code></em></p></code><br /> +</blockquote> + +<p>The actual OEB content model is not discussed explitely in the OEB specification, but it is defined in the OEB XML Document Type Declaration (DTD), which will be discussed later. Many times, such as in the case of the <code><em></code> element, the you can probably tell intuitively where an element can appear. In all cases, OEB validation software will be able to check your document against the OEB DTD and tell you whether or not your document has all its elements in the correct places.</p> + +</div> + +<h4 id="emelement">The <code><em></code> Element</h4> + +<p>You've already seen the <code><em></code> element — perhaps more than you've wanted. It bears repeating that the <code><em></code> element should be used instead of the <code><i></code> (italics) element in most cases, designating that the text should be emphasized but not specifying how the emphasized text should appear. An example of how specific text could be emphasized might be this:</p> + +<blockquote><code><p></code>Although the venture capital company seemed <code><em></code>really<code></em></code> interested in our project, perhaps the representative only <code><em></code>seemed<code></em></code> really interested.<code></p></code></blockquote> + +<blockquote>Although the venture capital company seemed <span style="font-style: italic">really</span> interested in our project, perhaps the representative only <span style="font-style: italic">seemed</span> really interested.</blockquote> + +<h4 id="strongelement">The <code><strong></code> Element</h4> + +<p>The <code><strong></code> element is similarly to the <code><em></code> in that it specifies that a section of text should be emphasized, but is used in most cases where bold text would be used. In fact, the default rendering of the <code><strong></code> element is using a bold font, although we've seen that any default rendering can be changed using styles.</p> + +<p>Also similar to the <code><em></code> tag, OEB has a carryover tag from HTML that functions similar to the <code><strong></code> tag but that specifies actual formatting: the <code><b></code> tag, representing bold text. For reasons we've explained earlier, we don't recommend using tags that specify presentation information within a document itself. Therefore, you should in most cases use <code><strong></code> rather than <code><b></code> whenever marking up text usually rendered in bold.</p> + +<blockquote><code><p></code>The Hindi letter "ka" is pronounced similarly to the first part of the English word, "<code><strong></code>cu<code></strong></code>p".<code></p></code></blockquote> + +<blockquote>The Hindi letter "ka" is pronounced similarly to the first part of the English word, "<span style="font-weight: bolder">cu</span>p".<code></p></code></blockquote> + +<h4 id="dfnelement">The <code><dfn></code> Element</h4> + +<p>We've already discussed using the <code><dfn></code> element to represent a word or words that are being defined for the first time.</p> + +<blockquote><code><p></code>The Hindi alphabet is usually specified as being a <code><dfn></code>syllabary<code></dfn></code>, since each letter of a word represents a syllable.<code></p></code></blockquote> + +<blockquote>The Hindi alphabet is usually specified as being a <dfn>syllabary</dfn>, since each letter of a word represents a syllable.</blockquote> + +<h4 id="codeelement">The <code><code></code> Element</h4> + +<p>OEB has several inline elements, some of which you'll use and some of which you'll never need unless creating certain esoteric documents. We mention that <code><code></code> element here because, since OEB was created by the computer-using community, it's likely that the first applications of OEB (this work included) will refer to computer programs or software.</p> + +<p>The <code><code></code> element was created to represent a section of computer program code, or data that should be entered by the user. This element is usually rendered in a monospaced font such as Courier, but as we've repeatedly stressed, you can change this behavior using styles.</p> + +<blockquote><code><p></code>In many programming languages, the statement <code><code></code>variable=16<code></code></code> represents an assignment operation, assigning the value on the right to the variable on the left of the equals sign.<code></p></code></blockquote> + +<blockquote>In many programming languages, the statement <code>variable=16</code> represents an assignment operation, assigning the value on the right to the variable on the left of the equals sign.</blockquote> + +<h4 id="citeelement">The <code><cite></code> Element</h4> + +<p>Many nonfiction works include information from other sources, and when they do so it is proper to cite the source from which the material was derived. The <code><cite></code> provides a standard way to indicate a cited source.</p> + +<blockquote> + <code><p></code>"The UN, like the League of Nations before it, was designed around the concept of state sovereignty" (<code><cite></code>Calvocoressi 1996<code></cite></code>). +</blockquote> + +<blockquote> + "The UN, like the League of Nations before it, was designed around the concept of state sovereignty" (<cite>Calvocoressi 1996</cite>). +</blockquote> + +<h4 id="spanelement">The <code><span></code> Element</h4> + +<p>Our discussion of inline elements has thus far assumed that, if you looked hard enough, you could find an OEB element that represented more or less the meaning of the section of text to which you're referring. We've stressed that you can always later change the style of the particular element you chose.</p> + +<p>What if you can't find an element that's appropriate, but still want to specify a style for a section of text? OEB provides (again borrowed from HTML) a generic element, <code><span></code>, that has no meaning other than to specify a section of text. The <code><span></code> element has the normal <code>style</code> and <code>class</code> attributes, allowing you to specify style for an arbitrary section of text. For example, imagine you want to somehow highlight the vowels in an alphabet, but don't want to use <code><em></code> because you'd like to use some separate style. You could always create a specific style class for <code><em></code>, but you might rather specify style information from scratch using <code><span></code>, like this:</p> + +<blockquote><code><p></code>English Alphabet: <code><span style="color: red"></code>A<code></span></code> B C D <code><span style="color: red"></code>E<code></span></code> F G...<code></p></code></blockquote> + +<blockquote>English Alphabet: <span style="color: red">A</span> B C D <span style="color: red">E</span> F G...</blockquote> + +<p>You should immediately protest that actual style information should not be included in the document itself. A slight modification resolves this problem and makes the use of <code><span></code> acceptable. First specify a style class, such as <code>.vowel {color:red}</code>, and then use this class in the <code><span></code> element:</p> + +<blockquote><strong>Style Sheet:</strong> <code>.vowel {color:red}</code></blockquote> + +<blockquote><strong>Document:</strong> <code><p></code>English Alphabet: <code><span class="vowel"></code>A<code></span></code> B C D <code><span class="vowel"></code>E<code></span></code> F G...<code></p></code></blockquote> + +<blockquote>English Alphabet: <span style="color: red">A</span> B C D <span style="color: red">E</span> F G...</blockquote> + +<div class="sidebar" id="customelements"> +<h4 class="sidebarTitle">More Information: Creating Custom Elements</h4> + +<p>Using the <code><span></code> element in the way we've just outlined is remarkably close to creating a new element named <code><vowel></code>; instead, we've used the <code><span></code> element with a style class named "vowel", which ends of serving the same function.</p> + +<p>The <code><span></code> element was introduced in HTML before XML was available, and is therefore the only way standard HTML can add what may be called pseudo-elements into an HTML document. XML, on the other hand, includes a method (which will be discussed later) for creating real custom elements from scratch. Since OEB is based on XML, it does allow one to create something called an <dfn>extended</dfn> OEB document which includes custom-built tags, meaning that the <code><span></code> element is little more than an a clumsy, inefficient way to do something that is much more elegantly done using standard XML techniques.</p> + +<p>Why then does OEB include the <code><span></code> element? One of the reasons should be quite familiar by now: since this tag is included in HTML, it was brought over into OEB so that standard HTML pages could be converted to OEB with minimal modification. The creation of custom elements using XML is furthermore more difficult than using the <code><span></code> element. Another reason should also be familiar: custom XML elements do not display correctly on HTML browsers.</p> + +<p>The majority of the OEB Authoring Group therefore felt it a higher priority to quickly release a specification that would bring about consensus in a quickly growing eBook industry than to force the adoption of barely released technologies such as custom XML elements. Happily, the OEBPS 1.0.1 still allows those who wish to follow useful standardization trends can still use XML to create custom elements. A discussion of how this is done is outside the scope of the current release of this book.</p> + +</div> + +<h4 id="brelement">The <code><br></code> Element</h4> + +<p>You learned in an earlier chapter that multiple adjacent whitespace characters, such as spaces and line breaks, are always replaced with a single space character before the text is displayed. This seems reasonable until you encounters a situation in which you'd like to display text on a separate line, perhaps like this:</p> + +<blockquote> +<code><p></code>...Karl had three siblings:<br /> +Kris<br /> +Krista<br /> +Karla<code></p></code> +</blockquote> + +<p>As you'll soon realize, if you've forgotten our earlier discussion about whitespace, what is displayed is not exactly what was entered:</p> + +<blockquote>...Karl had three siblings: Kris Krista Karla</blockquote> + +<p>You could always put the name of each of Karl's siblings in a separate paragraph, but they aren't really separate paragraphs. Besides, you don't want to risk their being formatted like paragraphs when displayed (either indented or separated by blank lines, depending on the reading system).</p> + +<p>The real solution here is to use a separate list element, which you'll learn about later in this chapter. But you might insist that these items should go <em>inside</em> the paragraph, and you want to choose where the line breaks appear. A better example might be a poem, in which you'd like to guarantee that a line break appears after each line:</p> + +<blockquote> +<code><p></code>There was a young creature named Karl<br /> +Whose siblings would say with a snarl<br /> +We'll share what we eat:<br /> +Just some bones from the meat<br /> +And a little of "ic" from the "garl".<code></p></code> +</blockquote> + +<p>Here again, it would be more preferable if there were a <code><poem></code> element in OEB. There isn't. Short of creating your own tag for this situation, OEB provides an element that specifies that a line break should appear: the <code><br></code> element.</p> + +<p>The <code><br></code> element is different than the elements examined so far in that it cannot have content; since it signifies a line break at a particular location in the text, it doesn't display text and has no need to hold text. The <code><br></code> element is therefore referred to as an <dfn>empty element</dfn>. You might expect the <code><br></code> element to simply have a beginning and ending tag with nothing in between (<code><br></code><code></br></code>). However, XML specifies a special format for empty elements by combining the beginning and ending tags into one tag: <code><br /></code></p> + +<ul> + <li id="emptyElement"><strong>XML Rule 6:</strong> (<em>Empty Elements</em>) An element that cannot have text between its beginning and ending tags is classified as a <dfn>empty element</dfn>, and has a special form of a single tag with the element name followed by a slash (/): <code><name /></code></li> +</ul> + +<p><strong>Important:</strong> While not required by XML, OEB specifies that all empty tags must have a space between the tag name and the slash character. This is to ensure that OEB documents can be displayed more or less correctly in HTML browsers.</p> + +<p>The <code><br></code> element might therefore be used in a re-write of Lewis Carroll's <i>Alice's Adventures in Wonderland</i>:</p> + +<blockquote> +<code><p></code>Alice fell down the rabbit hole...<code><br /></code><br /> +Down...<code><br /></code><br /> +Down...<code><br /></code><br /> +Down...<code></p></code> +</blockquote> + +<p>This would be correctly displayed as expected:</p> + +<blockquote> +Alice fell down the rabbit hole...<br /> +Down...<br /> +Down...<br /> +Down... +</blockquote> + +<p>The <code><br></code> element, however, has the potential of being abused and overused. In most places, items might more appropriately be placed in separate paragraphs, or perhaps in a list. In keeping with our goal of using markup to encode meaning into a document, it would probably be better to place a poem inside a <code><poem></code> element or something similar, although in this case we would have to define such an element before it could be used. The use of <code><br></code> to show the plight of Alice, above, is certainly the easiest and perhaps even an appropriate way to create the desired visual effect. We'd just like to encourage you to make sure that the <code><br></code> element is appropriate for the situation before using it.</p> + +<h4 id="aelement">The <code><a></code> Element</h4> + +<p>The anchor element, <code><a></code>, was first made popular by HTML. Since the <code><a></code> element is responsible for linking documents and sections of documents, this element is responsible for the "hypertext" part of HTML. Without <code><a></code>, HTML might otherwise have only been "TML", a text markup language with no linking capabilities. The OEB Publication Structure incorporated <code><a></code> into its tag set with hardly any modifications to its fundamental form.</p> + +<p>With its linking capabilites, <code><a></code> is the first tag we've discussed that starts to allow static pages in a book to come to life, to allow interaction with the user. The Open eBook specification begins with the assumption that a user will be provided with a paging function that will allow traversal through the contents of a book. The most fundamental purpose for hypertext anchors might be to link to reference sections or a glossary; however, the <code><a></code> element allows the author to provide many more complex navigation capabilites, allowing readers to even choose an arbitrary path through the book as they read.</p> + +<p>The most important attribute of the <code><a></code> element is <code>href</code>. As you've seen in elements both in the OEB package and in OEB style sheets, the <code>href</code> attribute specifies a "hypertext reference" location. Usually, the value of this attribute refers to a file; in other instances is can refer to a specific location within a file.</p> + +<p>Let's revisit a section from the first work we created.</p> + +<blockquote> + <code><p></code>Years ago, when strange creatures ruled the earth, the seas were beginning to form, and humans had yet to appear, there lived a young blovjus named Karl.<code></p></code> +</blockquote> + +<p>Now, some uninformed readers may not know what a "blovjus" is. You may wish to provide a definition a reader can read. Having a definition in the text is unacceptable; you don't want to bother your many readers who know exactly what a blovjus is and do not want to be told again. Instead, you elect to place the definition in a separate OEB document file named <code>blovjus.html</code>:</p> + +<blockquote> +<code><?xml version='1.0'?></code><br /> +<code><!DOCTYPE html PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Document//EN" "http://openebook.org/dtds/oeb-1.0.1/oebdoc101.dtd"></code><br /> +<code><html></code><br /> +<code><body></code><br /> + <code><p><strong></code>blovjus<code></strong></code> A strange, mythical creature which lived many years ago; sometimes it stole supper from its siblings.<code></p></code><br /> +<code></body></code><br /> +<code></html></code> +</blockquote> + +<p>Using the <code><a></code> tag, it's a simple job to link "blovjus" in the text to its definition:</p> + +<blockquote> + <code><p></code>Years ago, when strange creatures ruled the earth, the seas were beginning to form, and humans had yet to appear, there lived a young <code><a href="blovjus.html"></code>blovjus<code></a></code> named Karl.<code></p></code> +</blockquote> + +<p>Anchor elements can also be used to mark, or <dfn>anchor</dfn>, a section of text in a document (although this function is less important since each element in OEB contains an <code>id</code> attribute). This way, two <code><a></code> elements can be used together, one to mark a location and another to link to that location. This allows links not only to files, but to a specific location in a file. The tag serving as an anchor will use the <code>id</code> tag to provide a name for the anchor. The tag serving as a link will use the <code>href</code> as before to refer to a file, except that a pound sign (#) will be appended followed by the id of the anchor which serves as the link <dfn>target</dfn>.</p> + +<p>This is actually quite simple in practice. Assume that you have so many uninformed readers that you've created an entire glossary with many definitions. This glossary replaces the <code>blovjus.html</code> document file you created earlier, containing "blovjus" and other terms:</p> + +<blockquote> +<code><?xml version='1.0'?></code><br /> +<code><!DOCTYPE html PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Document//EN" "http://openebook.org/dtds/oeb-1.0.1/oebdoc101.dtd"></code><br /> +<code><html></code><br /> +<code><body></code><br /> + <code><p><a id="blovjus"><strong></code>blovjus<code></strong></a></code> A strange, mythical creature which lived many years ago; sometimes it stole supper from its siblings.<code></p></code><br /> + <code><p><a id="earth"><strong></code>earth<code></strong></a></code> The third planet from the sun.<code></p></code><br /> +<code></body></code><br /> +<code></html></code> +</blockquote> + +<p>Note that we've placed an <code><a></code> element around each term to serve as an anchor to mark the link targer. We've specified a name for each target using the <code>id</code> attribute. Here, we've used names that match the terms we're defining, but we could have used any names as long as they are unique and we use the same names in the links. Here's what the links look like in our original file:</p> + +<blockquote> + <code><p></code>Years ago, when strange creatures ruled the <code><a href="glossary.html#earth"></code>earth<code></a></code>, the seas were beginning to form, and humans had yet to appear, there lived a young <code><a href="glossary.html#blovjus"></code>blovjus<code></a></code> named Karl.<code></p></code> +</blockquote> + +<p>In each link, we specify the document in which the definitions reside (<code>glossary.html</code> in this example), followed by a pound sign (#) and then the ID of the appropriate definition (here, <code>earth</code> and <code>blovjus</code>). It is here that we must always make sure the name in the <code>href</code> attribute always matches the name in the target anchor tag's <code>id</code> attribute.</p> + +<p>This application of the anchor tag as a true anchor is less useful since OEB provides an <code>id</code> attribute for most elements. Instead of adding an <code><a></code> element and <code>id</code> attribute to serve as an anchor, you can instead add an <code>id</code> to the element to which you want to link. The above example, then, would appear like this:</p> + +<blockquote> +<code><?xml version='1.0'?></code><br /> +<code><!DOCTYPE html PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Document//EN" "http://openebook.org/dtds/oeb-1.0.1/oebdoc101.dtd"></code><br /> +<code><html></code><br /> +<code><body></code><br /> + <code><p id="blovjus"><strong></code>blovjus<code></strong></code> A strange, mythical creature which lived many years ago; sometimes it stole supper from its siblings.<code></p></code><br /> + <code><p id="earth"><strong></code>earth<code></strong></code> The third planet from the sun.<code></p></code><br /> +<code></body></code><br /> +<code></html></code> +</blockquote> + +<p>This version of specifying a link target is the recommended one — there is no need to specify an anchor for the target because almost any OEB element can contain an ID attribute. The <code><a></code> element will still be needed, of course, to link <em>to</em> the referenced location.</p> + +<p>Anchor tags are the first step in leveraging the capabilities of electronic books which static books do not have. Hypertext linking has many uses, from creating tables of contents to providing user-initiated changes in a plot. We'll address some of these uses in the following chapters.</p> + +<h3 id="blockelements">Block Elements</h3> + +<p>Block elements could be considered the opposite of inline elements. They are the enclosing elements within which inline elements are placed. That is, inline elements have to have some element to be inside; this element is ultimately a block element (although inline elements can appear inside other inline elements). You've already seen one example of a block element, the <code><p></code> element representing a paragraph. Block elements could also be classified as elements that automatically have a line break before and after them; they might therefore also be appropriately called "out-of-line" elements.</p> + +<p>Traditionally, block elements in HTML also had a blank line immediately before and immediately after them, but OEB reading systems may prefer to display block elements differently, indenting the first line of text in a <code><p></code> element, for example.</p> + +<h4 id="pelement">The <code><p></code> Element</h4> + +<p>The <code><p></code> element is probably the most straightforward block-level element, and probably the most common. Every paragraph in OEB should be surrounded by <code><p></code>...<code></p></code>. As we've certainly used plenty of paragraphs up to this point, we won't give any examples here. Instead, we'll just give one precaution: be careful not to <em> overuse</em> the <code><p></code> tag. Make sure the block of text you're marking up is really a paragraph and not, say, a list or a heading, both of which are covered in the sections below.</p> + +<h4 id="headingelements">The <code><h1></code>...<code><h6></code> Heading Elements</h4> + +<p>Perhaps the second most common block element is actually a group of similar elements: <code><h1></code>, <code><h2></code>, <code><h3></code>, <code><h4></code>, <code><h5></code>, and <code><h6></code>. These elements represent different levels of headings in your document.</p> + +<p>What does "heading" mean? It represents whatever you want it to represent. You could use <code><h1></code> to represent the title of your book on the title page, and use <code><h2></code> to represent the title of each chapter. Alternatively, you could use <code><h1></code> to represent each chapter title, <code><h2></code> to represent each chapter subtitle, and use a completely separate style class (or custom XML element) to represent the book title on the title page.</p> + +<p>All this is at your discretion because the heading elements do not directly correspond to any particular division of a book; they do not have a particular meaning, such as "chapter title" or "subtitle". The only thing that you can be sure of is that the default rendering method for each higher-numbered heading (such as <code><h1></code>) will be larger than a lower-numbered heading (such as <code><h2></code>).</p> + +<p>The lack of a particular meaning for the <code><hX></code> elements makes them slightly less useful than one might expect. Some early eBook reading systems assigned meanings to the <code><hX></code> elements, allowing the reading system to automatically find and understand when chapters begin, for example. Other markup languages have specific tags that represent chapters and other divisions. OEBPS 1.0, however, has no elements that specifically indicate book structure, so you'll have to make do with the heading elements. While OEB may introduce such elements in the future, for now using the heading elements is highly preferable to specifying the styles of headings manually, of course. Just remember that the meanings assigned to the heading elements are completely up to you. You might choose, for example, to use them like this:</p> + +<blockquote> + <code><h1></code>Karl the Creature<code></h1></code><br /> + <code><h2></code>Chapter 1: Karl as a Kid<code></h2></code><br /> + <code><p></code>Years ago...<code></p></code><br /> +</blockquote> + +<blockquote> + <h1>Karl the Creature</h1> + <h2>Episode 1: Karl as a Kid</h2> + <p>Years ago...</p> +</blockquote> + +<h4 id="lists">Lists, Ordered (<code><ol></code>) and Unordered (<code><ul></code>)</h4> + +<p>Almost every work, especially non-fiction educational works (like this one), have instances in which a list of items must be displayed. Many times the items in these lists are shown in a particular order, each item with a particular number. These lists are called <dfn>ordered lists</dfn>:</p> + +<blockquote> +The names of the first three planets from the sun, in order, are:<br /> +1. Mercury<br /> +2. Venus<br /> +3. Earth +</blockquote> + +<p>Not only must the numbers of each item in the list be carefully considered, care must be taken to ensure that the list is formatted correctly. Whenever the list is modified or reordered, care must be taken in modifying the numbering involved. Furthermore, there's no indication encoded in the file that this is a list; no meaning has been added to text that a computer or data-retrieval program could extract.</p> + +<p>OEB provides elements that solves all of these problems. In this case, we can use markup to specify that we have an ordered list (using the <code><ul></code> element), and that each item in the list is (as you would expect) a list item (using the <code><li></code> element). Ordered lists in OEB therefore consist of two separate elements, <code><ol></code> and <code><li></code>, used in conjunction like this:</p> + +<blockquote> +<code><p></code>The names of the first three planets from the sun, in order, are:<code></p></code><br /> +<code><ol></code><br /> +<code><li></code>Mercury<code></li></code><br /> +<code><li></code>Venus<code></li></code><br /> +<code><li></code>Earth<code></li></code><br /> +<code></ol></code> +</blockquote> + +<blockquote> +<p>The names of the first three planets from the sun, in order, are:</p> +<ol> +<li>Mercury</li> +<li>Venus</li> +<li>Earth</li> +</ol> +</blockquote> + +<p>Notice two things: first, the number of each list item does not need to be specified; it is supplied automatically when the list is displayed. Second, the introductory statement, "The names of the first three planets...", is not technically part of the list, so it is not placed within the <code><ol></code>...<code></ol></code> tags. The OEB publication structure allows you to specify the formatting, the type, and even a language-specific representation of the numbers used in a list.</p> + +<p>Some types of lists do not have numbers associated with them; they are <dfn>unordered lists</dfn>. If you're listing items in a grocery list, for example, you may not care about the order in which they are purchased. You would therefore use the <code><ul></code> for the unordered list, which functions exactly like the <code><ol></code> element used for ordered lists:</p> + +<blockquote> +<code><p></code>Please purchase the following items:<code></p></code><br /> +<code><ul></code><br /> +<code><li></code>Bread<code></li></code><br /> +<code><li></code>Eggs<code></li></code><br /> +<code><li></code>Milk<code></li></code><br /> +<code></ul></code> +</blockquote> + +<blockquote> +<p>Please purchase the following items:</p> +<ul> +<li>Bread</li> +<li>Eggs</li> +<li>Milk</li> +</ul> +</blockquote> + +<p>The default rendering method for unordered lists is to display a small round circle next to each item. You'll learn later how to use styles to modify this behavior. Most importantly, we've specified that the information is actually a list of items, and we can later, if we wish, arbitrarily change the way this list is displayed using styles, without changing the actual text of the document.</p> + +<h4 id="divelement">The <code><div></code> Element</h4> + +<p>The <code><span></code> element, as you saw earlier, provided a convenient way to specify style information about an arbitrary set of characters inside a block element. That last aspect somewhat limits its applicability, though: since <code><span></code> is an inline element, it can't be used to specify style information for more than one block element. That's why <code><div></code> in included in OEB.</p> + +<p>The <code><div></code> element is the block-level equivalent to the inline <code><span></code> span. It has no meaning in itself; its sole purpose is to group several block-level elements for the purpose of applying styles, for example. To see an example of where the <code><div></code> element could be applied, let's revisit an example of an inappropriate use of the <code><em></code> element:</p> + +<blockquote><strong>Illegal:</strong><br /> + <code><em></code><br /> + <code><p></code>Paragraph 1<code></p></code><br /> + <code><p></code>Paragraph 2<code></p></code><br /> + <code></em></code> +</blockquote> + +<p>As we noted when discussing the OEB content model, the <code><em></code> element, being an inline element, cannot enclose the <code><p></code> element, a block element. We explained that the <code><em></code> element could simply be moved inside the <code><p></code>, like this:</p> + +<blockquote><strong>Legal OEB:</strong><br /> + <code><p><em></code>Paragraph 1<code></em></p></code><br /> + <code><p><em></code>Paragraph 2<code></em></p></code><br /> +</blockquote> + +<p>The same effect could be achieved using the <code><div></code> element in a similar manner to that used in the first example. An emphasis style class could be created and applied to a surrounding <code><div></code> element:</p> + +<blockquote><strong>Style Sheet:</strong> <code>.emphasis {font-style: italic}</code></blockquote> + +<blockquote><strong>Document:</strong><br /> + <code><div class="emphasis"></code><br /> + <code><p></code>Paragraph 1<code></p></code><br /> + <code><p></code>Paragraph 2<code></p></code><br /> + <code></div></code> +</blockquote> + +<p>As with the <code><span></code> element, the <code><div></code> element is another carryover from HTML that allows one to simulate the creation of a custom tag. Also similarly to how the <code><span></code> element is used, XML allows true custom elements to be created, making <code><div></code>, although convenient, somewhat redundant. It's this convenience that makes <code><div></code> quite attractive and perhaps acceptable in some situations. Before using it, however, make sure that a custom XML element wouldn't be more appropriate.</p> + +<h4 id="centerelement">The <code><center></code> Element (deprecated)</h4> + +<p>OEB includes <code><center></code> but marks it as <dfn>deprecated</dfn>: its use is allowed so that HTML documents will not require much modification, but its use is discouraged. In fact, the <code><center></code> element is mentioned here only because its use has become <em>very</em> popular over the years in HTML documents. We echo the exhortation of the OEBPS specification (and the latest version of HTML) that the <code><center></code> element should not be used in new OEB document; explicitly specifying that a section of text should be centered goes against the concept of separation of content and presentation.</p> + +<blockquote> + <strong>Deprecated:</strong> <code><center></code>Chapter 1: Karl as a Kid<code></center></code> +</blockquote> + +<blockquote> + <div style="text-align: center">Chapter 1: Karl as a Kid</div> +</blockquote> + +<p>As an alternative, OEB (and HTML) allow text to be centered using styles. Specifically, the <code>text-align</code> property, which we'll discuss later in this chapter, allows a <code>"center"</code> value that gives the desired effect. Using style classes with the <code><div></code> element we just discussed might yield something like this:</p> + +<blockquote><strong>Style Sheet:</strong> <code>.chapterhead {text-align: center}</code></blockquote> + +<blockquote><strong>Document:</strong> + <code><div class="chapterhead"></code>Chapter 1: Karl as a Kid<code></div></code> +</blockquote> + +<p>As is usually the case with <code><div></code>, there are better ways to specify which text should be centered. If you're already using <code><h1></code> for chapter headings, for example, specifying that the chapter headings should be centered is quite easy using styles, and illustrates how convenient and appropriate style sheets can be:</p> + +<blockquote><strong>Style Sheet:</strong> <code>h1 {text-align: center}</code></blockquote> + +<blockquote><strong>Document:</strong> + <code><h1></code>Chapter 1: Karl as a Kid<code></h1></code> +</blockquote> + +<p>Whatever method you choose to use to center text, we encourage you that it not be the <code><center></code> element.</p> + +<h4 id="blockquoteelement">The <code><blockquote></code> Element</h4> + +<p>In contrast to the <code><center></code> element, <code><blockquote></code> is a good example of how elements should encode meaning into a document and assist in separating content from presentation. Many nonfiction works have sentences quoted from other works. If a quote is several sentences or even several paragraphs long, it is usually placed in a separate, indented paragraph or group of paragraphs. The <code><blockquote></code> element allows text to be specified as a block of quoted text without worrying how it will be formatted. Usually, the default indented style is acceptable, but this can easily be changed using styles.</p> + +<p>The <code><blockquote></code> element has one optional attribute, <code>cite</code>, which allows the web address location of the quote to be specified. Note that the inline element with the same name as the attribute, <code><cite></code>, is often used in conjunction with the <code><blockquote></code> element:</p> + +<blockquote> + <code><blockquote cite="http://www.un.org/Overview/rights.html"></code><br /> + Everyone is entitled to all the rights and freedoms set forth in this Declaration, without distinction of any kind, such as race, colour, sex, language, religion, political or other opinion, national or social origin, property, birth or other status. Furthermore, no distinction shall be made on the basis of the political, jurisdictional or international status of the country or territory to which a person belongs, whether it be independent, trust, non-self-governing or under any other limitation of sovereignty. + (<code><cite></code>UN Declaration of Universal Human Rights, Article 2, December 10, 1948<code></cite></code>)<br /> + <code></blockquote></code> +</blockquote> + +<blockquote cite="http://www.un.org/Overview/rights.html"> +Everyone is entitled to all the rights and freedoms set forth in this Declaration, without distinction of any kind, such as race, colour, sex, language, religion, political or other opinion, national or social origin, property, birth or other status. Furthermore, no distinction shall be made on the basis of the political, jurisdictional or international status of the country or territory to which a person belongs, whether it be independent, trust, non-self-governing or under any other limitation of sovereignty. (<cite>UN Declaration of Universal Human Rights, Article 2, December 10, 1948</cite>) +</blockquote> + +</body> +</html> diff --git a/lib/ebooks/understandingoeb/chapter5.html b/lib/ebooks/understandingoeb/chapter5.html new file mode 100644 index 00000000..439df0a2 --- /dev/null +++ b/lib/ebooks/understandingoeb/chapter5.html @@ -0,0 +1,156 @@ +<?xml version='1.0'?> +<!DOCTYPE html PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Document//EN" "http://openebook.org/dtds/oeb-1.0.1/oebdoc101.dtd"> +<?xml-stylesheet href="understandingoeb.css" type="text/x-oeb1-css"?> + +<html> +<head> + <link rel="stylesheet" type="text/x-oeb1-css" href="understandingoeb.css" /> +<title>Understanding OEB Chapter 5</title> + <meta name="author" content="Garret Wilson" /> + <meta name="copyright" content="Copyright (c) 2000-2001 Garret Wilson. All rights reserved." /> +</head> + +<body> + +<h2 id="chapter5">5. Essential OEB Styles</h2> + +<p>You've learned the essentials of styles in OEB, but you would be hard-pressed at this point to put this knowledge to use without knowing which styles are actually allowed. You probably have visions of how you'd like to change the appearance of your document: its fonts, its indentation, even its color. Here we'll address some of the most important style properties available for your use. Keep in mind that OEB style sheets are little more (and a little more less) than a subset of Cascading Style Sheets (CSS); what you'll learn here will in large part be transferable (although somewhat restricted) to CSS as it is used in general.</p> + +<h3 id="styleunits">Style Units</h3> + +<p>The styles you have seen so far in the examples have been qualitative, specifying whether a particular property applies to a particular section of text. We've seen how to specify italics: the <code>font-style</code> of text is either <code>italic</code> or it isn't. Similarly with color, the CSS <code>color</code> property can take color names such as <code>black</code> and <code>red</code>.</p> + +<p>Other style values can be quantitative, specifying numerical values for style properties. There are many cases in which you would want to specify the length, the height, or the width of something such as a font size or an indentation amount. Implicit in each of these cases is a <dfn>unit</dfn> of measurement: if you want a font of size <code>12</code>, does that "12" represent a height of 12 pixels, 12 centimeters, or 12 kilometers?</p> + +<p>When a <dfn>length</dfn> (the CSS term for instances of numeric value) is used, CSS requests that you specify a <dfn>unit</dfn>, unless in specific cases which we'll discuss later. A percentage, for example, does not need a unit specified, nor does a property which takes a count of something rather than a measurement. In all other cases, a unit will be used from the following list of those supported by CSS (and by OEB):</p> + +<ul> + <li><strong><code>px</code></strong> (pixels) The length represents a number of pixels.</li> + <li><strong><code>ex</code></strong> (x-height) The length represents multiples of the height of the lowercase letter "x" in the current font.</li> + <li><strong><code>em</code></strong> (m-width) The length represents the size of the font. (The name comes from its originally representing multiples of the width of the letter "M" in the current font.)</li> + <li><strong><code>pt</code></strong> (points) The length represents a number of points, with one point being equal to 1/72 of an inch.</li> + <li><strong><code>cn</code></strong> (centimeters) The length represents a number of centimeters.</li> + <li><strong><code>mm</code></strong> (millimeters) The length represents a number of millimeters.</li> + <li><strong><code>pc</code></strong> (picas) The length represents a number of picas, with one pica being equal to 12 points.</li> +</ul> + +<p>This list can be used as a short reference; the units themselves will become more straightforward in their actual use.</p> + +<h3 id="fontproperties">Font Properties</h3> + +<p>CSS font-related properties specify how a portion of text looks: the size, the type family, and the style, for instance. Specifically, we'll consider <code>font-family</code>, <code>font-size</code>, <code>font-style</code>, and <code>font-weight</code>, throwing <code>text-decoration</code>, <code>color</code> and <code>background-color</code> in for good measure.</p> + +<h4 id="fontfamilyproperty">The <code>font-family</code> Property</h4> + +<p>When you think of changing a font in a word processor, you usually think of specifying its name: "Times New Roman" and "Arial" are common examples. These names do not really specify the entire font itself (remember, the font includes the size, style and everything else about the font), but instead indicates the <dfn>font family</dfn>, the group of fonts of varying styles and sizes that look similar.</p> + +<p>The <code>font-family</code> property allows you to specify the name of a font family in the normal CSS way, specifying the property and value in a declaration:</p> + +<blockquote><code>{font-family: "Times New Roman"}</code></blockquote> + +<p>Since this particular font family, "Times New Roman", has spaces in its name, we've placed it inside quotes. Family names without spaces do not need quotes.</p> + +<p>In a real style sheet, you would also need to specify one or more elements to which to apply the style, using a selector. For example, you might wish to specify the default font for the entire OEB document. Since all text in an OEB document appears inside an enclosing <code><body></code> element, you can specify a default font by using <code>body</code> as the selector:</p> + +<blockquote><code>body {font-family: "Times New Roman"}</code></blockquote> + +<p>The font family "Times New Roman" is quite popular and comes installed on many computer operating platforms. There's no way to guarantee that it will be installed on the device or software the person reading your book is using, however. You might even decide to use a font family that no one else is using (after all, style sheets are about specifying custom styles). Perhaps you've created a custom font family, and it only exists on your machine! Your book will look quite nice on your own computer or reading device, but what about on other systems?</p> + +<p>CSS defines several generic font families (or more accurately, generic divisions of font families), three of which OEB uses. These font familes are guaranteed to be present on any OEB compliant reading system. They are:</p> + +<ul> + <li><strong>serif</strong> A font family with serifs present (such as "Times New Roman").</li> + <li><strong>sans-serif</strong> A font family without serifs present (such as "Arial").</li> + <li><strong>monospace</strong> A font family in which each character takes up the same amount of horizontal space (such as "Courier").</li> +</ul> + +<p>Using one of these three fonts will guarantee that your text will be assigned a font with the same properties you intended on every OEB compliant reading system. But what about customization? OEB does not yet specify a way to deliver custom fonts to a reading system, but there is a middle ground: CSS allows one to specify the preferred font family, yet also specify the font family to use if the preferred font is not present.</p> + +<p>Specify a list of preferred <code>font-family</code> values by separating them with commas (,) with the most preferred font first. If you use "Book Antiqua", a serif font family, you might specify the following as the default font:</p> + +<blockquote><code>body {font-family: "Book Antiqua", "Times New Roman", serif}</code></blockquote> + +<p>Notice that we've specified <code>serif</code>, the generic font family guaranteed to be present, as our last choice. We always want the text displayed, and even if the reading system offers no frills whatsoever, this font family is guaranteed to be present. In fact, it is recommended that you <em>always</em> provide one of the generic font families as your last choice in your fallback list.</p> + +<ul> + <li><strong>CSS Tip 1:</strong> (<em>Supplying Default Generic Font Family Names</em>) Always provide one of the generic font family names in your <code>font-family</code> fallback list.</li> +</ul> + +<h4 id="fontsizeproperty">The <code>font-size</code> Property</h4> + +<p>CSS allows a font size to be specified absolutely, using the <code>font-size</code> property and one of the units specified earlier. (Note that there is no whitespace between the value and the unit name.) A 12 point font could be selected as the default using the following:</p> + +<blockquote><code>body {font-size: 12pt}</code></blockquote> + +<p>While it might be appropriate to specify the absolute size of the default font, which applies to everything inside the <code><body></code> tag (and thereby everything in the document), it's not wise to specify an absolute value for elements within the document. For example, to make all emphasized text a little larger than the surrounding text, an absolute value might be used like this:</p> + +<blockquote><strong>Not Recommended:</strong> <code>em {font-size: 14pt}</code></blockquote> + +<p>There are several reasons this isn't a good idea. What if you were to later change the default font for <code><body></code> to 16 points? You'd then have to make sure that every other absolute value, such as that for <code><em></code>, was changed as well, or the emphasized text would be <em>smaller</em> than the surrounding text — the 14-point emphasized text didn't change, but the surrounding text changed to 16 points. Furthermore, remember that the <code><em></code> element can appear several places, such as within an <code><h1></code> element, which traditionally is larger than the default text. You'd want the emphasized text even larger than the 14 points you specified. In short, it would be ideal to be able to specify that a particular element's size in relation to its surrounding text (or rather, relative to the size of the enclosing element's font).</p> + +<p>One way CSS allows this to be done is using percentages. If you want emphasized text to be slightly larger than the text that surrounds it, it would be better to use something like this:</p> + +<blockquote><code>em {font-size: 120%}</code></blockquote> + +<p>In this case, if the <code><em></code> tag appeared inside an element of 12-point text, it would be rendered in a 14.4-point font (12 multiplied by 120% is 14.4). If the <code><em></code> element were to appear inside 16-point text, it would be rendered in a 19.2-point font. The following example shows how using a percentage can make relative sizes appear correctly in several locations:</p> + +<p>Style Sheet:</p> + +<blockquote> + <code>body {font-size: 12pt}</code><br /> + <code>em {font-size: 120%}</code> +</blockquote> + +<p>Document Extract:</p> + +<blockquote> + <code><h2></code>The <code><em></code>Extremely<code></em></code> Small Blovjus<code></h2></code><br /> + <code><p></code>...Being <code><em></code>extremely<code></em></code> smaller than other blovji his age...<code></p></code><br /> +</blockquote> + +<blockquote> + <h2>The <em style="font-size: 120%">Extremely</em> Small Blovjus</h2> + <p>...Being <em style="font-size: 120%">extremely</em> smaller than other blovji his age...</p> +</blockquote> + +<p>There are several other ways to represent relative sizes. You can use the units "em" or "ex", which specifies that the font should be so many multiples of the width of the "m" character or the height of the "ex" character, respectively, in the current font. We won't discuss these methods here.</p> + +<p>Just like <code>font-family</code>, which allows certain pre-defined font family names to be used, the <code>font-size</code> property has several pre-defined sizes. Some of these are relative sizes, functioning exactly as if percentages were used, and others are absolute, functioning exactly as if absolute sizes were used.</p> + +<p>Predefined relative <code>font-size</code> values:</p> + +<ul> + <li><strong>smaller</strong> Specifies the font size should be smaller than that of the enclosing element.</li> + <li><strong>larger</strong> Specifies the font size should be larger than that of the enclosing element.</li> +</ul> + +<p>CSS recommends that a difference of 120% be used, which would make using <code>font-size: larger</code> equivalent to using <code>font-size: 120%</code>, for example, but this difference is not guaranteed.</p> + +<p>The other pre-defined <code>font-size</code> values are the following:</p> + +<ul> + <li><strong>xx-small</strong></li> + <li><strong>x-small</strong></li> + <li><strong>small</strong></li> + <li><strong>medium</strong></li> + <li><strong>large</strong></li> + <li><strong>x-large</strong></li> + <li><strong>xx-large</strong></li> +</ul> + +<p>Although these are equivalent to using absolute font sizes, the actual font sizes these values stand for may very from platform to platform. CSS does say that you can expect values of <code>larger</code> and <code>smaller</code> to change between these absolute values. That is, for a current font size of <code>small</code>, an element with <code>font-size: larger</code> would give the equivalent of a font of size <code>medium</code>.</p> + +<h4 id="fontstyleproperty">The <code>font-style</code> Property</h4> + +<p>The <code>font-style</code>, as implemented by OEB, allows a font to be specified as <code>italic</code> or <code>normal</code> (that is, not italic). Although CSS allows another value, <code>oblique</code>, OEB reading systems are not required to support it, and may represent it as synonymous with <code>italic</code>.</p> + +<h4 id="fontweightproperty">The <code>font-weight</code> Property</h4> + +<p>Although CSS allows several values to be used with the <code>font-weight</code> property, OEB eliminates all but two of them, making <code>font-weight</code> simply a way to designate that text should be rendered as bold, in much the same way that <code>font-style</code> represented italics. The two values OEB allows for <code>font-weight</code> are <code>bold</code> and <code>normal</code>.</p> + +<h4 id="textdecorationproperty">The <code>text-decoration</code> Property</h4> + +<p>The <code>text-decoration</code> property allows underlining to be specified, in much the same way that previous properties allowed italics and bold to be specified. The two values allowed are <code>none</code> (the default), and <code>underline</code>.</p> + +</body> +</html> diff --git a/lib/ebooks/understandingoeb/chapter6.html b/lib/ebooks/understandingoeb/chapter6.html new file mode 100644 index 00000000..a9987f69 --- /dev/null +++ b/lib/ebooks/understandingoeb/chapter6.html @@ -0,0 +1,626 @@ +<?xml version='1.0'?> +<!DOCTYPE html PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Document//EN" "http://openebook.org/dtds/oeb-1.0.1/oebdoc101.dtd"> +<?xml-stylesheet href="understandingoeb.css" type="text/x-oeb1-css"?> + +<html> +<head> + <link rel="stylesheet" type="text/x-oeb1-css" href="understandingoeb.css" /> +<title>Understanding OEB Chapter 6</title> + <meta name="author" content="Garret Wilson" /> + <meta name="copyright" content="Copyright (c) 2000-2001 Garret Wilson. All rights reserved." /> +</head> + +<body> + +<h2 id="chapter6">6. Real-World OEB: Charter of the United Nations</h2> + +<p>At this point you should be able to create a fairly complex real-world OEB publication. We could demonstrate creating an OEB publication from the ground up by writing a book-length work from scratch, but it will probably be more illustrative to take a publication that already exists and convert it to OEB.</p> + +<p>Here, we'll take the Charter of the United Nations — available on the Internet at <a href="http://www.un.org/aboutun/charter/">http://www.un.org/aboutun/charter/</a> — and convert it into an OEB publication in the same step-by-step manner you would use with your own publication, or one you are converting. You can find the finished product at <a href="http://www.globalmentor.com/bookstore/search?text=un+charter">http://www.globalmentor.com/bookstore/search?text=un+charter</a>.</p> + +<p>It's best to first take a broad look of how the work is organized, so that we can correctly model its structure using OEB elements. In general, the UN Charter is organized in the following hierarchy:</p> + +<ul> + <li>Charter of the United Nations<br /> + <ul> + <li>Chapters<br /> + <ul> + <li>Articles</li> + </ul> + </li> + </ul> + </li> +</ul> + +<p>Since OEB, being modeled so closely after HTML, has no concept of hierarchical divisions, we'll divide the UN Charter using whatever method we feel appropriate. While we could certainly put the entire Charter into one OEB document, it will probably be easier for us to keep track of things if we use several OEB document files. We'll place each chapter and all its article into a separate OEB document file, and do the same with the Introductory Note and the Preamble.</p> + +<p>Without specific elements to represent hierarchical divisions, we'll use own arbitrary method of representing headings within each division. There are a number of ways the division headings could be represented, none really being any better than the others, so we'll choose the following representation:</p> + +<ul> + <li><strong><code><h1></code></strong> Title of entire UN Charter.</li> + <li><strong><code><h2></code></strong> Title of each chapter.</li> + <li><strong><code><h3></code></strong> Title of each article.</li> +</ul> + +<h3 id="uncharterchapter2">UN Charter Chapter 2: <code>chapter2.html</code></h3> + +<p>Since we're using separate document files for each chapter, this makes it easy to analyze different parts of the Charter separately. Although it might seem strange that we're not starting from the beginning, it's probably best to first jump into the midst of the document and see how the "mundane" structures will be implemented; we can look at the "Introductory Note", "Preamble", and trimmings such as a table of contents later, after you're comfortable with producing more common OEB elements.</p> + +<p>The second chapter of the UN charter begins with the chapter name and title, then proceeds with each separate article title and the article's contents:</p> + +<blockquote> +<p>CHAPTER II</p> +<p>MEMBERSHIP</p> +<p>Article 3</p> +<p>The original Members of the United Nations shall be the states which, having participated in the United Nations Conference on International Organization at San Francisco, or having previously signed the Declaration by United Nations of 1 January 1942, sign the present Charter and ratify it in accordance with Article 110.</p> +<p>Article 4</p> +<p>1. Membership in the United Nations is open to all other peace-loving states which accept the obligations contained in the present Charter and, in the judgment of the Organization, are able and willing to carry out these obligations.</p> +<p>2. The admission of any such state to membership in the United Nations will be effected by a decision of the General Assembly upon the recommendation of the Security Council.</p> +<p><em>. . .</em></p> +</blockquote> + +<p>We've already decided to represent the chapter title using the <code><h2></code> element, and the title for each article using the <code><h3></code> element. After this is done, the first part of our converted text looks like this:</p> + +<blockquote> + <code><h2></code>Chapter II: Membership<code></h2></code><br /> + <code><h3></code>Article 3<code></h3></code> +</blockquote> + +<p>The text of "Article 3", being a simple paragraph, will simply go inside a <code><p></code> element:</p> + +<blockquote> + <code><h2></code>Chapter II: Membership<code></h2></code><br /> + <code><h3></code>Article 3<code></h3></code><br /> + <code><p></code>The original Members of the United Nations shall be the states which, having participated in the United Nations Conference on International Organization at San Francisco, or having previously signed the Declaration by United Nations of 1 January 1942, sign the present Charter and ratify it in accordance with Article 110.<code></p></code> +</blockquote> + +<p>The title of "Article 4" can obviously be placed inside a <code><h3></code> element, as was "Article 3", but what about the article's contents? While we could simply use two <code><p></code> elements, these two paragraphs are numbered; it would be more appropriate to use an ordered list, with each paragraph appearing inside one of the items in the list:</p> + +<blockquote> +<p><em>. . .</em></p> + <code><h3></code>Article 4<code></h3></code><br /> + <code><ol></code><br /> + <code><li><p></code>Membership in the United Nations is open to all other peace-loving states which accept the obligations contained in the present Charter and, in the judgment of the Organization, are able and willing to carry out these obligations.<code></p></li></code><br /> + <code><li><p></code>The admission of any such state to membership in the United Nations will be effected by a decision of the General Assembly upon the recommendation of the Security Council.<code></p></li></code><br /> + <code></ol></code> +</blockquote> + +<p>Note that we remove the literal numbers in each paragraph; the <code><ol></code> element combined with the <code><li></code> elements will add the correct numbers automatically when the book is displayed.</p> + +<p>Markup added to articles five and six will be identical to that added to the first article. The last step is even more important than the others: add the <code><body></code> element and the other required OEB document markup. The resulting document file <code>chapter2.html</code> appears below:</p> + +<blockquote> +<code><?xml version='1.0'?></code><br /> +<code><!DOCTYPE html PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Document//EN" "http://openebook.org/dtds/oeb-1.0.1/oebdoc101.dtd"></code><br /> +<code><html></code><br /> +<code><body></code><br /> + <code><h2></code>Chapter II: Membership<code></h2></code><br /> + <code><h3></code>Article 3<code></h3></code><br /> + <code><p></code>The original Members of the United Nations shall be the states which, having participated in the United Nations Conference on International Organization at San Francisco, or having previously signed the Declaration by United Nations of 1 January 1942, sign the present Charter and ratify it in accordance with Article 110.<code></p></code><br /> + <code><h3></code>Article 4<code></h3></code><br /> + <code><ol></code><br /> + <code><li><p></code>Membership in the United Nations is open to all other peace-loving states which accept the obligations contained in the present Charter and, in the judgment of the Organization, are able and willing to carry out these obligations.<code></p></li></code><br /> + <code><li><p></code>The admission of any such state to membership in the United Nations will be effected by a decision of the General Assembly upon the recommendation of the Security Council.<code></p></li></code><br /> + <code></ol></code> + <code><h3></code>Article 5<code></h3></code><br /> + <code><p></code>A Member of the United Nations against which preventive or enforcement action has been taken by the Security Council may be suspended from the exercise of the rights and privileges of membership by the General Assembly upon the recommendation of the Security Council. The exercise of these rights and privileges may be restored by the Security Council.<code></p></code><br /> + <code><h3></code>Article 6<code></h3></code><br /> + <code><p></code>A Member of the United Nations which has persistently violated the Principles contained in the present Charter may be expelled from the Organization by the General Assembly upon the recommendation of the Security Council.<code></p></code><br /> +<code></body></code><br /> +<code></html></code> +</blockquote> + +<p>When this chapter is displayed, here's how it will appear:</p> + +<blockquote> + <h2>Chapter II: Membership</h2> + <h3>Article 3</h3> + <p>The original Members of the United Nations shall be the states which, having participated in the United Nations Conference on International Organization at San Francisco, or having previously signed the Declaration by United Nations of 1 January 1942, sign the present Charter and ratify it in accordance with Article 110.</p> + <h3>Article 4</h3> + <ol> + <li><p>Membership in the United Nations is open to all other peace-loving states which accept the obligations contained in the present Charter and, in the judgment of the Organization, are able and willing to carry out these obligations.</p></li> + <li><p>The admission of any such state to membership in the United Nations will be effected by a decision of the General Assembly upon the recommendation of the Security Council.</p></li> + </ol> + <h3>Article 5</h3> + <p>A Member of the United Nations against which preventive or enforcement action has been taken by the Security Council may be suspended from the exercise of the rights and privileges of membership by the General Assembly upon the recommendation of the Security Council. The exercise of these rights and privileges may be restored by the Security Council.</p> + <h3>Article 6</h3> + <p>A Member of the United Nations which has persistently violated the Principles contained in the present Charter may be expelled from the Organization by the General Assembly upon the recommendation of the Security Council.</p> +</blockquote> + +<h3 id="uncharterchapter3">UN Charter Chapter 3: <code>chapter3.html</code></h3> + +<p>After applying markup to the second chapter of the UN Charter, doing the same for the first chapter is straightforward; we'll therefore examine the following chapter, chapter three:</p> + + +<blockquote> +<p>CHAPTER III</p> +<p>ORGANS</p> +<p>Article 7</p> +<p>1. There are established as the principal organs of the United Nations:<br /> +a General Assembly<br /> +a Security Council<br /> +an Economic and Social Council<br /> +a Trusteeship Council<br /> +an International Court of Justice<br /> +and a Secretariat. +</p> +<p>2. Such subsidiary organs as may be found necessary may be established in accordance with the present Charter.</p> +<p>Article 8</p> +<p>The United Nations shall place no restrictions on the eligibility of men and women to participate in any capacity and under conditions of equality in its principal and subsidiary organs.</p> +</blockquote> + +<p>Since we've already established a consistent way to use heading elements, the chapter and article titles can be converted as before:</p> + +<blockquote> + <code><h2></code>Chapter III: Organs<code></h2></code><br /> + <code><h3></code>Article 7<code></h3></code><br /> + <p><em>. . .</em></p> +</blockquote> + +<p>Similar to Chapter II, Article 4, the individual items in Chapter II, Article 7 are numbered (ordered) items in a list. We'll therefore begin the text as follows:</p> + +<blockquote> + <p><em>. . .</em></p> + <code><ol></code><br /> + <code><li><p></code>There are established as the principal organs of the United Nations:<code></p></li></code><br /> + <p><em>. . .</em></p> +</blockquote> + +<p>At this point there seems to be a problem: The first listed item, beginning with "There are established...," itself contains a list of items, including "a General Assembly," "a Security Council," etc. These items are unordered (that is, they have no number beside them), but they represent a list nonetheless. It seems as if the first list item itself contains a list.</p> + +<p>These <dfn>nested lists</dfn> present no problem any more than common nested elements. They do require that you take special care in making sure which list elements appear in which other elements. We should first decide which type of list element to use for the list of "principal organs." As before, we'll present each of these items using the <code><li></code> tag. Together, these tags go inside an enclosing list element, but these particular items shouldn't be listed in any particular order; more precisely, we don't want these items to be represented with numbers beside them. We'll therefore use an unordered list <code><ul></code> instead of an ordered list <code><ul></code>.</p> + +<p>We'll therefore put the <code><li></code> list items of the unordered list <code><ui></code> inside the first <code><li></code> list item of the ordered list <code><ol></code>. Looking at the finished product should help to understand how this works:</p> + +<blockquote> + <code><h2></code>Chapter III: Organs<code></h2></code><br /> + <code><h3></code>Article 7<code></h3></code><br /> + <code><ol></code><br /> + <code><li><p></code>There are established as the principal organs of the United Nations:<code></p></code><br /> + <blockquote> + <code><ul></code><br /> + <code><li></code>a General Assembly<code></li></code><br /> + <code><li></code>a Security Council<code></li></code><br /> + <code><li></code>an Economic and Social Council<code></li></code><br /> + <code><li></code>a Trusteeship Council<code></li></code><br /> + <code><li></code>an International Court of Justice<code></li></code><br /> + <code><li></code>and a Secretariat.<code></li></code><br /> + <code></ul></code> + </blockquote> + <code></li></code> + <p><em>. . .</em></p> +</blockquote> + +<p>Notice that the ending tag <code></li></code> of the first item in the ordered list comes <em>after</em> the end of the entire unordered list <code><ul></code>. This means that the entire unordered list <code><ul></code> is actually part of one list item element: the first list item in the ordered list <code><ol></code></p> + +<p>We're still not finished with Article 7; we still must add the second item, beginning with, "Such subsidiary organs...:"</p> + +<blockquote> + <code><h2></code>Chapter III: Organs<code></h2></code><br /> + <code><h3></code>Article 7<code></h3></code><br /> + <code><ol></code><br /> + <code><li><p></code>There are established as the principal organs of the United Nations:<code></p></code><br /> + <blockquote> + <code><ul></code> + <code><li></code>a General Assembly<code></li></code><br /> + <code><li></code>a Security Council<code></li></code><br /> + <code><li></code>an Economic and Social Council<code></li></code><br /> + <code><li></code>a Trusteeship Council<code></li></code><br /> + <code><li></code>an International Court of Justice<code></li></code><br /> + <code><li></code>and a Secretariat.<code></li></code><br /> + <code></ul></code> + </blockquote> + <code></li></code><br /> + <code><li><p></code>Such subsidiary organs as may be found necessary may be established in accordance with the present Charter.<code></p></li></code><br /> + <code></ol></code> +</blockquote> + +<p>The following article, Article 8, which ends this chapter of the UN Charter, is quite simple structurally. As with any OEB document file, we'll also need to add the enclosing <code><html></code> and <code><body> elements:</code></p> + +<blockquote> +<code><?xml version='1.0'?></code><br /> +<code><!DOCTYPE html PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Document//EN" "http://openebook.org/dtds/oeb-1.0.1/oebdoc101.dtd"></code><br /> +<code><html></code><br /> +<code><body></code><br /> + <code><h2></code>Chapter III: Organs<code></h2></code><br /> + <code><h3></code>Article 7<code></h3></code><br /> + <code><ol></code><br /> + <code><li><p></code>There are established as the principal organs of the United Nations:<code></p></code><br /> + <blockquote> + <code><ul></code> + <code><li></code>a General Assembly<code></li></code><br /> + <code><li></code>a Security Council<code></li></code><br /> + <code><li></code>an Economic and Social Council<code></li></code><br /> + <code><li></code>a Trusteeship Council<code></li></code><br /> + <code><li></code>an International Court of Justice<code></li></code><br /> + <code><li></code>and a Secretariat.<code></li></code><br /> + <code></ul></code> + </blockquote> + <code></li></code><br /> + <code><li><p></code>Such subsidiary organs as may be found necessary may be established in accordance with the present Charter.<code></p></li></code><br /> + <code></ol></code><br /> + <code><h3></code>Article 8<code></h3></code><br /> + <code><p></code>The United Nations shall place no restrictions on the eligibility of men and women to participate in any capacity and under conditions of equality in its principal and subsidiary organs.<code></p></code><br /> +<code></body></code><br /> +<code></html></code> +</blockquote> + +<p>The chapter will then appear like this when it's displayed:</p> + +<blockquote> + <h2>Chapter III: Organs</h2> + <h3>Article 7</h3> + <ol> + <li><p>There are established as the principal organs of the United Nations:</p> + <ul> + <li>a General Assembly</li> + <li>a Security Council</li> + <li>an Economic and Social Council</li> + <li>a Trusteeship Council</li> + <li>an International Court of Justice</li> + <li>and a Secretariat.</li> + </ul> + </li> + <li><p>Such subsidiary organs as may be found necessary may be established in accordance with the present Charter.</p></li> + </ol> + <h3>Article 8</h3> + <p>The United Nations shall place no restrictions on the eligibility of men and women to participate in any capacity and under conditions of equality in its principal and subsidiary organs.</p> +</blockquote> + +<h3 id="uncharterchapter1">UN Charter Chapter 1: <code>chapter1.html</code></h3> + +<p>Now that we've examined chapters two and three, we can return to Chapter One. At first the structure of the content looks relatively straightforward compared to the chapters we've already examined.</p> + +<blockquote> +<p>CHAPTER I</p> +<p>PURPOSES AND PRINCIPLES</p> +<p>Article 1</p> +<p>The Purposes of the United Nations are:</p> +<p><em>. . .</em></p> +<p>Article 2</p> +<p>The Organization and its Members, in pursuit of the Purposes stated in Article 1, shall act in accordance with the following Principles.</p> +<p><em>. . .</em></p> +</blockquote> + +<p>You should be able to easily mark up the information using the OEB publication structure, resulting in something similar to the following:</p> + +<blockquote> + <code><h2></code>Chapter I: Purposes and Principles<code></h2></code><br /> + <code><h3></code>Article 1<code></h3></code><br /> + <code><p></code>The Purposes of the United Nations are:<code></p></code><br /> + <p><em>. . .</em></p><br /> + <code><h3></code>Article 2<code></h3></code><br /> + <code><p></code>The Organization and its Members, in pursuit of the Purposes stated in Article 1, shall act in accordance with the following Principles.<code></p></code><br /> + <p><em>. . .</em></p> +</blockquote> + +<p>It is at this point that the power of OEB can be put to use to store information within the document. Since these are the first places that the UN <dfn>Purposes</dfn> and <dfn>Principles</dfn> are being defined, we can make good use of the <code><dfn></code> element to indicate this:</p> + +<blockquote> + <code><p></code>The <code><dfn></code>Purposes<code></dfn></code> of the United Nations are:<code></p></code><br /> + <p><em>. . .</em></p><br /> + <code><p></code>The Organization and its Members, in pursuit of the Purposes stated in Article 1, shall act in accordance with the following <code><dfn></code>Principles<code></dfn></code>.<code></p></code><br /> + <p><em>. . .</em></p> +</blockquote> + +<p>Adding the <code><dfn></code> tag encodes meaning into the document, explicitly stating that these two concepts are being defined for the first time. We can go one step further and mark these definitions with anchors, in case we want to refer to these specific definitions later in the document (remember that, instead of using actual <code><a></code> elements for anchors, we can simply add <code>id</code> attributes to the target elements):</p> + +<blockquote> + <code><p></code>The <code><dfn id="purposesDefinition"></code>Purposes<code></dfn></code> of the United Nations are:<code></p></code><br /> + <p><em>. . .</em></p><br /> + <code><p></code>The Organization and its Members, in pursuit of the Purposes stated in Article 1, shall act in accordance with the following <code><dfn id="principlesDefinition"></code>Principles<code></dfn></code>.<code></p></code><br /> + <p><em>. . .</em></p> +</blockquote> + +<p>In fact, it's a good idea if we place anchors on every heading in the document so that the respective sections can be linked to later. For example, adding anchors to the sections of this chapter results in the markup below. (If we were to use actual anchor elements for anchors, we would place the anchor element, <code><a></code>, inside the heading element, <code><h2></code>. This order cannot be reversed, for the same reason that the <code><p></code> element cannot go inside an <code><em></code> element: inline elements must go inside block elements, and not vice-versa. Here we don't even use anchor elements at all, but simply add <code>id</code> attributes to the <code><h2></code> and <code><h3></code> elements.)</p> + +<blockquote> + <code><h2 id="chapter1"></code>Chapter I: Purposes and Principles<code></h2></code><br /> + <code><h3 id="article1"></code>Article 1<code></h3></code><br /> + <code><p></code>The Purposes of the United Nations are:<code></p></code><br /> + <p><em>. . .</em></p><br /> + <code><h3 id="article2"></code>Article 2<code></h3></code><br /> + <code><p></code>The Organization and its Members, in pursuit of the Purposes stated in Article 1, shall act in accordance with the following Principles.<code></p></code><br /> + <p><em>. . .</em></p> +</blockquote> + +<p></p> + +<p>Assuming we add anchor elements to every division in the entire UN Charter, and assuming Chapter VII is placed in a file named <code>chapter7.html</code>, we can provide links from this chapter. The last principle in Article 2 states that "this principle shall not prejudice the application of enforcement measures under Chapter Vll."; with anchor tags appropriately placed throughout our documents, we can provide a direct hypertext link to the chapter by using the anchor element <code><a></code> like this:</p> + +<blockquote> + <code><p></code>...this principle shall not prejudice the application of enforcement measures under <code><a href="chapter7.html#chapter7"></code>Chapter Vll<code></a></code>.<code><p></code> +</blockquote> + +<p>Notice that we've not only linked to the file, <code>chapter7.html</code>, we've also provided the ID of the anchor, <code>#chapter7</code>, which marks the beginning of the actual chapter in the file. Since Chapter 7 is at the beginning of <code>chapter7.html</code>, we could have simply linked to the document file itself: <code><a href="chapter7.html"></code>. However, in many cases the target anchor within the file will be important as well when the anchor is not at the beginning of the document — in the case of articles, for instance.</p> + +<h3 id="uncharterintro">UN Charter Introductory Note: <code>intro.html</code></h3> + +<p>Moving back another step to the UN Charter's Introductory Note provides more examples of linking, provided the appropriate anchor elements have been placed at the start of every chapter and article:</p> + +<blockquote> + <code><h2 id="chapter1"></code>Introductory Note<code></h2></code><br /> + <code><p></code>The Charter of the United Nations was signed on 26 June 1945, in San Francisco, at the conclusion of the United Nations Conference on International Organization, and came into force on 24 October 1945. The Statute of the International Court of Justice is an integral part of the Charter.<code></p></code><br /> + <code><p></code>Amendments to <code><a href="chapter5.html#article23"></code>Articles 23<code></a></code>, <code><a href="chapter5.html#article27"></code>27<code></a></code> and <code><a href="chapter10.html#article61"></code>61<code></a></code> of the Charter were adopted by the General Assembly on 17 December 1963 and came into force on 31 August 1965. A further amendment to <code><a href="chapter10.html#article61"></code>Article 61<code></a></code> was adopted by the General Assembly on 20 December 1971, and came into force on 24 September 1973. An amendment to <code><a href="chapter18.html#article109"></code>Article 109<code></a></code>, adopted by the General Assembly on 20 December 1965, came into force on 12 June 1968.<code></p></code><br /> + <p><em>. . .</em></p> +</blockquote> + +<p>Note that we had to first check and see in which document files the articles appear before we could link to them.</p> + +<h3 id="unchartertoc">Table of Contents: <code>toc.html</code></h3> + +<p>The first version of the Open eBook Publication Structure has no specific elements for creating a table of contents; this means that, outside of creating a new set of elements specifically for a table of contents, we'll be forced to use generic elements to do the job. Here we'll use the standard elements to create a table of contents inside a normal OEB document.</p> + +<p>A table of contents is usually one of the last things you'll add to your OEB publication, for good reason: not only does it provide a hierarchical view of the structure of the publication, it provides links to each one of publication sections. You may, however, elect to create a table of contents early and use it as a working design of your entire publication, if you are writing the work from scratch; you'd still have to wait until the document was finished to test all of the hyperlinks, though.</p> + +<p>The table of contents therefore has two elements: its reflection of the publication's structure, as well as hyperlinks to parts of the publication. Reflecting the work's structure can be accomplished in several ways; here we'll use unordered list <code><ol></code> elements. An OEB document displaying the top-level UN Charter structure (that is, the level containing the Introductory Note, Preamble, and chapters), might be marked up like this:</p> + +<blockquote> +<code><ul></code><br /> + <code><li></code>Introductory Note<code></li></code><br /> + <code><li></code>Preamble<code></li></code><br /> + <code><li></code>Chapter I: Purposes and Principles<code></li></code><br /> + <code><li></code>Chapter II: Membership<code></li></code><br /> + <em>. . .</em><br /> +<code></ul></code> +</blockquote> + +<p>This would appear something like this:</p> + +<blockquote> +<ul> + <li>Introductory Note</li> + <li>Preamble</li> + <li>Chapter I: Purposes and Principles</li> + <li>Chapter II: Membership</li> + <li><em>. . .</em></li> +</ul> +</blockquote> + +<p>Displaying the second level of organization, the level containing the articles, requires a bit more concentration on details. It's evident that each list of articles that appear within a chapter will be marked up using a separate list element, but it's important to remember that all of these lists are actually sub-lists of the chapter item in which they appear. Each chapter item is enclosed within a list item <code><li></code><em>...</em><code></li></code> beginning and ending tag pair. Each sub-list of articles must appear <em>inside</em> that list item's beginning and ending tags. OEB's content model does not allow lists to appear between list items; sub-lists must appear inside the list item to which they belong.</p> + +<blockquote> +<code><ul></code><br /> + <code><li></code>Introductory Note<code></li></code><br /> + <code><li></code>Preamble<code></li></code><br /> + <code><li></code>Chapter I: Purposes and Principles<br /> + <blockquote> + <code><ul></code><br /> + <code><li></code>Article 1<code></li></code><br /> + <code><li></code>Article 2<code></li></code><br /> + <code></ul></code> + </blockquote> + <code></li></code><br /> + <code><li></code>Chapter II: Membership<br /> + <blockquote> + <code><ul></code><br /> + <code><li></code>Article 3<code></li></code><br /> + <code><li></code>Article 4<code></li></code><br /> + <code><li></code>Article 5<code></li></code><br /> + <code><li></code>Article 6<code></li></code><br /> + <code></ul></code> + </blockquote> + <code></li></code><br /> + <em>. . .</em><br /> +<code></ul></code> +</blockquote> + +<p>When displayed, the table of contents would now appear like this:</p> + +<blockquote> +<ul> + <li>Introductory Note</li> + <li>Preamble</li> + <li>Chapter I: Purposes and Principles + <ul> + <li>Article 1</li> + <li>Article 2</li> + </ul> + </li> + <li>Chapter II: Membership + <ul> + <li>Article 3</li> + <li>Article 4</li> + <li>Article 5</li> + <li>Article 6</li> + </ul> + </li> + <li><em>. . .</em></li> +</ul> +</blockquote> + +<p>That's all we need to do regarding structure, since the UN Charter has only these levels of hierarchy. The other issue to address is hyperlinking: each item in the table of contents must link to the respective section of the publication. If that section lies somewhere in the middle of the physical document file in which it appears, we must have first provided anchors with unique IDs for the table of contents to link to.</p> + +<p>After adding hyperlinks, our table of contents is basically finished:</p> + +<blockquote> +<code><ul></code><br /> + <code><li><a href="intro.html"></code>Introductory Note<code></a></li></code><br /> + <code><li><a href="preamble.html"></code>Preamble<code></a></li></code><br /> + <code><li><a href="chapter1.html"></code>Chapter I: Purposes and Principles</a><br /> + <blockquote> + <code><ul></code><br /> + <code><li><a href="chapter1.html#article1"></code>Article 1<code></a></li></code><br /> + <code><li><a href="chapter1.html#article2"></code>Article 2<code></a></li></code><br /> + <code></ul></code> + </blockquote> + <code></li></code><br /> + <code><li><a href="chapter2.html"></code>Chapter II: Membership</a><br /> + <blockquote> + <code><ul></code><br /> + <code><li><a href="chapter2.html#article3"></code>Article 3<code></a></li></code><br /> + <code><li><a href="chapter2.html#article4"></code>Article 4<code></a></li></code><br /> + <code><li><a href="chapter2.html#article5"></code>Article 5<code></a></li></code><br /> + <code><li><a href="chapter2.html#article6"></code>Article 6<code></a></li></code><br /> + <code></ul></code> + </blockquote> + <code></li></code><br /> + <em>. . .</em><br /> +<code></ul></code> +</blockquote> + +<h3 id="uncharterpackage">UN Charter Package File: <code>uncharter.opf</code></h3> + +<p>From the examples covered so far, marking up the rest of the UN Charter should be a simple task. There's still one more file we need to create, however, to tie all the pieces together and make our series of OEB documents into a complete OEB publication: the OEB package file.</p> + +<p>Creating the package file, as you know by now, requires less thinking and planning than cutting, pasting, and altering to match the particular publication you're working with. In this example, we'll simply start from the top of the file and work our way downwards — although we'll include ending tags when appropriate, which may occur at the end of the file. The first part should be familiar — it appears at the top of every package file:</p> + +<blockquote> +<code><?xml version='1.0'?></code><br /> +<code><!DOCTYPE package PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Package//EN" "http://openebook.org/dtds/oeb-1.0.1/oebpkg101.dtd"></code><br /> +<code><package unique-identifier="uncharterpackage"></code> + + <blockquote> + <em>. . .</em> + </blockquote> + +<code></package></code> +</blockquote> + +<p>Inside the <code><package></code> element, we'll place the metadata. In particular, we'll include the title of the publication (<em>Charter of the United Nations</em>) and we'll create our own type of "charter", although this particular type of document has not been standardized.</p> + +<p>The <code><dc:Identifier></code> element requires particular attention. Notice that we've given the <code>id</code> attribute the value <code>"uncharterpackage"</code> to match the <code>unique-identifier</code> attribute in the earlier <code><package></code> element. Furthermore, we've used a <code>scheme</code> of <code>"url"</code>, although this value is not standard. It would be better to include a <code>scheme</code> of <code>ISBN</code> or some other similar identifier more useful to third parties such as bookstores and libraries.</p> + +<p>There are two <code><dc:Creator></code> elements; one specifies an author (<code>"aut"</code>) of <code>United Nations</code> and a book publisher (<code>"bkp"</code>) of <code>Mentor Publishing</code>. The <code><dc:Date</code> element contains the date this package file was created, July 11, 2001.</p> + +<p>Three arbitrary subjects have been added using the <code><ds:Subject></code> element: <code>United Nations</code>, <code>Historical Documents</code>, and <code>International Politics</code>. Lastly, a <code><dc:Source></code> element shows that we originally found the content at <code><a href="http://www.un.org/aboutun/charter/">http://www.un.org/aboutun/charter/</a></code>.</p> + +<blockquote> + <code><dc-metadata xmlns:dc="http://purl.org/dc/elements/1.0/" xmlns:oebpackage="http://openebook.org/namespaces/oeb-package/1.0/"></code><br /> + <code><dc:Title></code>Charter of the United Nations<code></dc:Title></code><br /> + <code><dc:Type></code>charter<code></dc:Type></code><br /> + <code><dc:Identifier id="uncharterpackage" scheme="url"></code>http://www.un.org/aboutun/charter/<code></dc:Identifier></code><br /> + <code><dc:Creator role="aut"></code>United Nations<code></dc:Creator></code><br /> + <code><dc:Creator role="bkp"></code>Mentor Publishing<code></dc:Creator></code><br /> + <code><dc:Date></code>2001-07-11<code></dc:Date></code><br /> + <code><dc:Subject></code>United Nations<code></dc:Subject></code><br /> + <code><dc:Subject></code>Historical Documents<code></dc:Subject></code><br /> + <code><dc:Subject></code>International Politics<code></dc:Subject></code><br /> + <code><dc:Source></code>http://www.un.org/aboutun/charter/<code></dc:Source></code><br /> + <code></dc-metadata></code> +</blockquote> + +<p>We next need to specify the files which will be included in the publication; this information will appear inside the <code><manifest></code> element. Since our version of the the UN Charter has no images associated with it, each <code><item></code> element in the manifest will represent an OEB document file, with <code>media-type="text/x-oeb1-document"</code>. It doesn't matter what order we present the files, just so we include all the files used in the publication. This includes the table of contents, the introduction, the preamble, and all the chapters, including chapters we haven't listed here.</p> + +<blockquote> + <code><manifest></code><br /> + <code><item id="toc" href="toc.html" media-type="text/x-oeb1-document" /></code><br /> + <code><item id="intro" href="intro.html" media-type="text/x-oeb1-document" /></code><br /> + <code><item id="preamble" href="preamble.html" media-type="text/x-oeb1-document" /></code><br /> + <code><item id="chapter1" href="chapter1.html" media-type="text/x-oeb1-document" /></code><br /> + <code><item id="chapter2" href="chapter2.html" media-type="text/x-oeb1-document" /></code><br /> + <em>. . .</em><br /> + <code></manifest></code> +</blockquote> + +<p>It is inside the <code><spine></code> element that we specify the reading order of the documents we listed in the <code><manifest></code> section. The order here is all that's important; having already listed the essential information about each document, we simply reference the unique ID we've assigned each item earlier:</p> + +<blockquote> + <code><spine></code><br /> + <code><itemref idref="toc" /></code><br /> + <code><itemref idref="intro" /></code><br /> + <code><itemref idref="preamble" /></code><br /> + <code><itemref idref="chapter1" /></code><br /> + <code><itemref idref="chapter2" /></code><br /> + <em>. . .</em><br /> + <code></spine></code> +</blockquote> + +<p>That's all that OEB requires for a complete OEB publication, and we could at this point read the UN Charter on any OEB-compliant reading system. As an example of optional OEB functionality that we can add to allow future OEB reading systems to manipulate our work in various ways, we'll add a <code><guide></code> element and specify that our table of contents is one of the <dfn>guide</dfn> types recognized by OEB; specifically, it is a <code>"toc"</code>, a table of contents. In short, we're simply identifying a particular document as a table of contents; other types of guides may be found in the <em>Open eBook Publication Structure 1.0.1 Specification</em>.</p> + +<p>There is currently no guarantee that a particular OEB reading system will recognize guides, but it's still a good idea to include at least the table of contents. More information on guides and a related concept, <dfn>tours</dfn>, can be found in the <em>Open eBook Publication Structure 1.0 Specification</em>, and will likely be covered in depth in a later edition of this book.</p> + +<blockquote> + <code><guide></code><br /> + <code><reference type="toc" title="Table of Contents" href="toc.html" /></code><br /> + <code></guide></code> +</blockquote> + +<p>At this point, we've finished the package file, completing our publication. Assuming the rest of the chapters have been marked up and included, the group of files can be presented to an OEB-compliant reading system and, based upon the function of the reading system, either be presented to a user or passed along the chain to another piece of software and/or hardware for further manipulation. The complete package file, <code>uncharter.opf</code>, is presented below:</p> + + +<blockquote> +<code><?xml version='1.0'?></code><br /> +<code><!DOCTYPE package PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Package//EN" "http://openebook.org/dtds/oeb-1.0.1/oebpkg101.dtd"></code><br /> +<code><package unique-identifier="uncharterpackage"></code><br /> + + <blockquote> + <code><dc-metadata xmlns:dc="http://purl.org/dc/elements/1.0/" xmlns:oebpackage="http://openebook.org/namespaces/oeb-package/1.0/"></code><br /> + <code><dc:Title></code>Charter of the United Nations<code></dc:Title></code><br /> + <code><dc:Type></code>charter<code></dc:Type></code><br /> + <code><dc:Identifier id="uncharterpackage" scheme="url"></code>http://www.un.org/aboutun/charter/<code></dc:Identifier></code><br /> + <code><dc:Creator role="aut"></code>United Nations<code></dc:Creator></code><br /> + <code><dc:Creator role="bkp"></code>Mentor Publishing<code></dc:Creator></code><br /> + <code><dc:Date></code>2001-07-11<code></dc:Date></code><br /> + <code><dc:Subject></code>United Nations<code></dc:Subject></code><br /> + <code><dc:Subject></code>Historical Documents<code></dc:Subject></code><br /> + <code><dc:Subject></code>International Politics<code></dc:Subject></code><br /> + <code><dc:Source></code>http://www.un.org/aboutun/charter/<code></dc:Source></code><br /> + <code></dc-metadata></code> + </blockquote> + + <blockquote> + <code><manifest></code><br /> + <code><item id="toc" href="toc.html" media-type="text/x-oeb1-document" /></code><br /> + <code><item id="intro" href="intro.html" media-type="text/x-oeb1-document" /></code><br /> + <code><item id="preamble" href="preamble.html" media-type="text/x-oeb1-document" /></code><br /> + <code><item id="chapter1" href="chapter1.html" media-type="text/x-oeb1-document" /></code><br /> + <code><item id="chapter2" href="chapter2.html" media-type="text/x-oeb1-document" /></code><br /> + <code><item id="chapter3" href="chapter3.html" media-type="text/x-oeb1-document" /></code><br /> + <code><item id="chapter4" href="chapter4.html" media-type="text/x-oeb1-document" /></code><br /> + <code><item id="chapter5" href="chapter5.html" media-type="text/x-oeb1-document" /></code><br /> + <code><item id="chapter6" href="chapter6.html" media-type="text/x-oeb1-document" /></code><br /> + <code><item id="chapter7" href="chapter7.html" media-type="text/x-oeb1-document" /></code><br /> + <code><item id="chapter8" href="chapter8.html" media-type="text/x-oeb1-document" /></code><br /> + <code><item id="chapter9" href="chapter9.html" media-type="text/x-oeb1-document" /></code><br /> + <code><item id="chapter10" href="chapter10.html" media-type="text/x-oeb1-document" /></code><br /> + <code><item id="chapter11" href="chapter11.html" media-type="text/x-oeb1-document" /></code><br /> + <code><item id="chapter12" href="chapter12.html" media-type="text/x-oeb1-document" /></code><br /> + <code><item id="chapter13" href="chapter13.html" media-type="text/x-oeb1-document" /></code><br /> + <code><item id="chapter14" href="chapter14.html" media-type="text/x-oeb1-document" /></code><br /> + <code><item id="chapter15" href="chapter15.html" media-type="text/x-oeb1-document" /></code><br /> + <code><item id="chapter16" href="chapter16.html" media-type="text/x-oeb1-document" /></code><br /> + <code><item id="chapter17" href="chapter17.html" media-type="text/x-oeb1-document" /></code><br /> + <code><item id="chapter18" href="chapter18.html" media-type="text/x-oeb1-document" /></code><br /> + <code><item id="chapter19" href="chapter19.html" media-type="text/x-oeb1-document" /></code><br /> + <code></manifest></code> + </blockquote> + + <blockquote> + <code><spine></code><br /> + <code><itemref idref="toc" /></code><br /> + <code><itemref idref="intro" /></code><br /> + <code><itemref idref="preamble" /></code><br /> + <code><itemref idref="chapter1" /></code><br /> + <code><itemref idref="chapter2" /></code><br /> + <code><itemref idref="chapter3" /></code><br /> + <code><itemref idref="chapter4" /></code><br /> + <code><itemref idref="chapter5" /></code><br /> + <code><itemref idref="chapter6" /></code><br /> + <code><itemref idref="chapter7" /></code><br /> + <code><itemref idref="chapter8" /></code><br /> + <code><itemref idref="chapter9" /></code><br /> + <code><itemref idref="chapter10" /></code><br /> + <code><itemref idref="chapter11" /></code><br /> + <code><itemref idref="chapter12" /></code><br /> + <code><itemref idref="chapter13" /></code><br /> + <code><itemref idref="chapter14" /></code><br /> + <code><itemref idref="chapter15" /></code><br /> + <code><itemref idref="chapter16" /></code><br /> + <code><itemref idref="chapter17" /></code><br /> + <code><itemref idref="chapter18" /></code><br /> + <code><itemref idref="chapter19" /></code><br /> + <code></spine></code> + </blockquote> + + <blockquote> + <code><guide></code><br /> + <code><reference type="toc" title="Table of Contents" href="toc.html" /></code><br /> + <code></guide></code> + </blockquote> + +<code></package></code> +</blockquote> + +</body> +</html> diff --git a/lib/ebooks/understandingoeb/foreword.html b/lib/ebooks/understandingoeb/foreword.html new file mode 100644 index 00000000..03d4dbe5 --- /dev/null +++ b/lib/ebooks/understandingoeb/foreword.html @@ -0,0 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE html PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Document//EN" "http://openebook.org/dtds/oeb-1.0.1/oebdoc101.dtd"> +<?xml-stylesheet href="understandingoeb.css" type="text/x-oeb1-css"?> + +<html> +<head> + <link rel="stylesheet" type="text/x-oeb1-css" href="understandingoeb.css" /> +<title>Understanding OEB Foreword</title> + <meta name="author" content="Garret Wilson" /> + <meta name="copyright" content="Copyright (c) 2000-2001 Garret Wilson. All rights reserved." /> +</head> + +<body> + +<h2 id="foreword">Foreword</h2> + +<p>When Garret told me he was writing this book, I thought "Thank, God!" The world really needs a good book about the Open eBook Publication Structure. And when I read a draft, I was even happier. It's clear and concise, direct and thorough and addresses a crucial audience. The authors of the publication structure did a great job designing and writing the technical specification, but the specification is, well, let's just say it's not gentle prose you'd read at night to relax! It's unforgivingly hard-nosed, technical and (usually!) unambiguous. And that's what a technical specification needs to be. The primary audience for the specification is software developers who are building tools and reading systems, and the +hyper-concise form is needed for those folks.</p> + +<p>But that doesn't help the rest of the world understand what the specification is, what it allows, how it works and how it nails the needs of the eBook world on its head. <em>Understanding OEB</em> tackles this task.</p> + +<p><em>David Ornstein</em></p> +<p><em>President, Open eBook Forum</em></p> +<p><em>Manager of Planning and Architecture for eReading, Microsoft</em></p> + +</body> +</html> diff --git a/lib/ebooks/understandingoeb/preface.html b/lib/ebooks/understandingoeb/preface.html new file mode 100644 index 00000000..3aa69883 --- /dev/null +++ b/lib/ebooks/understandingoeb/preface.html @@ -0,0 +1,33 @@ +<?xml version='1.0'?> +<!DOCTYPE html PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Document//EN" "http://openebook.org/dtds/oeb-1.0.1/oebdoc101.dtd"> +<?xml-stylesheet href="understandingoeb.css" type="text/x-oeb1-css"?> + +<html> +<head> + <link rel="stylesheet" type="text/x-oeb1-css" href="understandingoeb.css" /> +<title>Understanding OEB Preface</title> + <meta name="author" content="Garret Wilson" /> + <meta name="copyright" content="Copyright (c) 2000-2001 Garret Wilson. All rights reserved." /> +</head> + +<body> + +<h2 id="preface">Preface</h2> + +<p>Last night the finishing touches were placed on the <em>Open eBook Publication Structure 1.0.1</em>, a revision of the original specification which had as its purpose the task of clearing up ambiguities, fixing errors, and ensuring that the specification could continue to be useful as the Open eBook Forum produces new specifications for the eBook industry. As the original <em>Open eBook Publication Structure 1.0</em> was produced by the Open eBook Authoring Group (most of whom now make up the new Open eBook Forum), this updated document is the first official specification to be released by the OEBF.</p> + +<p>As chair of the maintenance subgroup of the publication structure working group (yes, the OEBF has a more complicated hierarchy than our original group of authors), I was responsible for overseeing the relatively easy task of updating and correcting the existing specification. As it turned out, even such minor changes are never straightforward, with such last-minute issues as corrupted logo image files. I cannot help but feel admiration (and some pity) for Gene Golovchinsky and Jerry Dunietz, who are supervising the development subgroup which is working towards the next major version of the OEB PS: <em>Open eBook Publication Structure 2.0</em></p> + +<p>Version 2.0 will certainly require a new "Understanding" book to be written, but the OEBF believes version 1.0.1 to be an unambiguous foundation on which to build today, a foundation that won't render content useless when new versions add new features. From the experience that version 1.0 has brought, it appears the OEB Authoring Group was correct in choosing <em>its</em> foundations: open, standards-based international specifications that can be used by all. It's my wish that this book will allow you to understand the steps you need to take to be one of those who use the specification for your next eBook.</p> + +<p>Thanks to Horace Dediu, Dorothea Salo, Merv Matson and Roger Sperberg for all their help in reviewing and proofreading the early drafts. Thanks to Gunter Hille and David Ornstein for their support and encouragment. Scott Oaks and Henry Wong in their <em>Java Threads</em> (O'Reilly, 1999) provided excellent examples of using rhetorical questions in a tutorial. I'm grateful to Garth Conboy for introducing me to the very useful technical term, "Real Soon Now."</p> + +<p>All diagrams in this book use the <a href="http://www.uml.org">Unified Modeling Language (UML)</a> and were created using the <a href="http://www.magicdraw.com">MagicDraw UML</a> modeling software.</p> + +<p><em>Garret Wilson</em></p> +<p><em>President, GlobalMentor, Inc.</em></p> +<p><em><a href="http://www.globalmentor.com">http://www.globalmentor.com</a></em></p> +<p><em>14 June 2001</em></p> + +</body> +</html> diff --git a/lib/ebooks/understandingoeb/title.html b/lib/ebooks/understandingoeb/title.html new file mode 100644 index 00000000..4afef481 --- /dev/null +++ b/lib/ebooks/understandingoeb/title.html @@ -0,0 +1,26 @@ +<?xml version='1.0'?> +<!DOCTYPE html PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Document//EN" "http://openebook.org/dtds/oeb-1.0.1/oebdoc101.dtd"> +<?xml-stylesheet href="understandingoeb.css" type="text/x-oeb1-css"?> + +<html> +<head> + <link rel="stylesheet" type="text/x-oeb1-css" href="understandingoeb.css" /> +<title>Understanding OEB Title Page</title> + <meta name="author" content="Garret Wilson" /> + <meta name="copyright" content="Copyright (c) 2000-2001 Garret Wilson. All rights reserved." /> +</head> + +<body> + +<h1>Understanding OEB</h1> + +<h2>Revised and Updated for OEB PS 1.0.1</h2> + +<p>by <a href="mailto:garret@globalmentor.com">Garret Wilson</a></p> + +<p>Copyright © 2000-2001 Garret Wilson. All rights reserved.</p> + +<p>Published by <a href="http://www.globalmentor.com/publishing/">Mentor Publishing</a>, a division of <a href="http://www.globalmentor.com">GlobalMentor, Inc.</a></p> + +</body> +</html> diff --git a/lib/ebooks/understandingoeb/toc.html b/lib/ebooks/understandingoeb/toc.html new file mode 100644 index 00000000..1b6b8fff --- /dev/null +++ b/lib/ebooks/understandingoeb/toc.html @@ -0,0 +1,150 @@ +<?xml version='1.0'?> +<!DOCTYPE html PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Document//EN" "http://openebook.org/dtds/oeb-1.0.1/oebdoc101.dtd"> +<?xml-stylesheet href="understandingoeb.css" type="text/x-oeb1-css"?> + +<html> +<head> + <link rel="stylesheet" type="text/x-oeb1-css" href="understandingoeb.css" /> +<title>Understanding OEB Table of Contents</title> + <meta name="author" content="Garret Wilson" /> + <meta name="copyright" content="Copyright (c) 2000-2001 Garret Wilson. All rights reserved." /> +</head> + +<body> + +<h1>Table of Contents</h1> + +<ul> + <li><a href="foreword.html">Foreword</a></li> + <li><a href="preface.html">Preface</a></li> + <li><a href="chapter1.html">1. Defining a Beginning</a> + <ul> + <li><a href="chapter1.html#definingEBook">Defining "eBook"</a> + <ul> + <li><a href="chapter1.html#eText">Electronic Book as an "Etext"</a></li> + <li><a href="chapter1.html#eBookHype">"eBook" as a Marketing Tool</a></li> + <li><a href="chapter1.html#eBookInevitibility">The eBook as Inevitable</a></li> + </ul> + </li> + <li><a href="chapter1.html#oebMeaning">The Meaning of OEB</a></li> + <li><a href="chapter1.html#usingOEB">Using OEB</a></li> + <li><a href="chapter1.html#review">Review</a> + <ul> + <li><a href="chapter1.html#summary">Summary</a></li> + </ul> + </li> + </ul> + </li> + <li><a href="chapter2.html#chapter2">2. Understanding an OEB Publication</a> + <ul> + <li><a href="chapter2.html#oebdocument">An OEB Document</a> + <ul> + <li><a href="chapter2.html#needmarkup">The Need for Markup</a></li> + <li><a href="chapter2.html#markupalphabetsoup">More Information: Markup Alphabet Soup</a></li> + <li><a href="chapter2.html#usingxml">Using XML</a></li> + <li><a href="chapter2.html#creatingoebdocument">Creating an OEB Document</a></li> + <li><a href="chapter2.html#formattingoebtext">Formatting OEB Text</a></li> + </ul> + </li> + <li><a href="chapter2.html#oebpackage">An OEB Package</a> + <ul> + <li><a href="chapter2.html#packageelement">The <code><package></code> Element</a></li> + <li><a href="chapter2.html#packagemetadata">The Package Metadata</a></li> + <li><a href="chapter2.html#packagemanifest">The Package Manifest</a></li> + <li><a href="chapter2.html#packagespine">The Package Spine</a></li> + </ul> + </li> + <li><a href="chapter2.html#xmlrepresentdata">Using XML to Represent Data</a></li> + <li><a href="chapter2.html#review">Review</a> + <ul> + <li><a href="chapter2.html#summary">Summary</a></li> + <li><a href="chapter2.html#xmlrules">XML Rules</a></li> + <li><a href="chapter2.html#oebrules">OEB Rules</a></li> + <li><a href="chapter2.html#oebtags">OEB Tags</a></li> + </ul> + </li> + <li><a href="chapter2.html#exampleoebdocument">Completed Example OEB Document (<code>karl.html</code>)</a></li> + <li><a href="chapter2.html#exampleoebpackage">Completed Example OEB Package (<code>karl.opf</code>)</a></li> + </ul> + </li> + <li><a href="chapter3.html#chapter3">3. Styles and Style Sheets</a> + <ul> + <li><a href="chapter3.html#emphasisrevisited">Emphasis Revisited</a></li> + <li><a href="chapter3.html#cascadingstylesheets">Cascading Style Sheets (CSS)</a> + <ul> + <li><a href="chapter3.html#cssvsxsl">More Information: CSS vs. XSL</a></li> + <li><a href="chapter3.html#cssselectors">CSS Selectors</a></li> + </ul> + </li> + <li><a href="chapter3.html#linkingstylesheets">Linking to Style Sheets</a> + <ul> + <li><a href="chapter3.html#linkelement">Linking Style Sheets with the <code><link></code> Element</a></li> + <li><a href="chapter3.html#linkxml">Linking Style Sheets with XML</a></li> + </ul> + </li> + <li><a href="chapter3.html#review">Review</a> + <ul> + <li><a href="chapter3.html#summary">Summary</a></li> + <li><a href="chapter3.html#cssproperties">CSS Properties</a></li> + </ul> + </li> + <li><a href="chapter3.html#exampleoebdocument">Completed Example OEB Document with Styles (<code>karl.html</code>)</a></li> + <li><a href="chapter3.html#examplestylesheet">Completed Example Style Sheet (<code>karl.css</code>)</a></li> + </ul> + </li> + <li><a href="chapter4.html#chapter4">4. Essential OEB Elements</a> + <ul> + <li><a href="chapter4.html#inlineelements">Inline Elements</a> + <ul> + <li><a href="chapter4.html#xmlcontentmodels">More Information: XML Content Models</a></li> + <li><a href="chapter4.html#emelement">The <code><em></code> Element</a></li> + <li><a href="chapter4.html#strongelement">The <code><strong></code> Element</a></li> + <li><a href="chapter4.html#dfnelement">The <code><dfn></code> Element</a></li> + <li><a href="chapter4.html#codeelement">The <code><code></code> Element</a></li> + <li><a href="chapter4.html#citeelement">The <code><cite></code> Element</a></li> + <li><a href="chapter4.html#spanelement">The <code><span></code> Element</a></li> + <li><a href="chapter4.html#customelements">More Information: Creating Custom Elements</a></li> + <li><a href="chapter4.html#brelement">The <code><br></code> Element</a></li> + <li><a href="chapter4.html#aelement">The <code><a></code> Element</a></li> + </ul> + </li> + <li><a href="chapter4.html#blockelements">Block Elements</a> + <ul> + <li><a href="chapter4.html#pelement">The <code><p></code> Element</a></li> + <li><a href="chapter4.html#headingelements">The <code><h1></code>...<code><h6></code> Heading Elements</a></li> + <li><a href="chapter4.html#lists">Lists, Ordered (<code><ol></code>) and Unordered (<code><ul></code>)</a></li> + <li><a href="chapter4.html#divelement">The <code><div></code> Element</a></li> + <li><a href="chapter4.html#centerelement">The <code><center></code> Element (deprecated)</a></li> + <li><a href="chapter4.html#blockquoteelement">The <code><blockquote></code> Element</a></li> + </ul> + </li> + </ul> + </li> + <li><a href="chapter5.html#chapter5">5. Essential OEB Styles</a> + <ul> + <li><a href="chapter5.html#styleunits">Style Units</a></li> + <li><a href="chapter5.html#fontproperties">Font Properties</a> + <ul> + <li><a href="chapter5.html#fontfamilyproperty">The <code>font-family</code> Property</a></li> + <li><a href="chapter5.html#fontsizeproperty">The <code>font-size</code> Property</a></li> + <li><a href="chapter5.html#fontstyleproperty">The <code>font-style</code> Property</a></li> + <li><a href="chapter5.html#fontweightproperty">The <code>font-weight</code> Property</a></li> + <li><a href="chapter5.html#textdecorationproperty">The <code>text-decoration</code> Property</a></li> + </ul> + </li> + </ul> + </li> + <li><a href="chapter6.html#chapter6">6. Real-World OEB: Charter of the United Nations</a> + <ul> + <li><a href="chapter6.html#uncharterchapter2">UN Charter Chapter 2: <code>chapter2.html</code></a></li> + <li><a href="chapter6.html#uncharterchapter3">UN Charter Chapter 3: <code>chapter3.html</code></a></li> + <li><a href="chapter6.html#uncharterchapter1">UN Charter Chapter 1: <code>chapter1.html</code></a></li> + <li><a href="chapter6.html#uncharterintro">UN Charter Introductory Note: <code>intro.html</code></a></li> + <li><a href="chapter6.html#unchartertoc">Table of Contents: <code>toc.html</code></a></li> + <li><a href="chapter6.html#uncharterpackage">UN Charter Package File: <code>uncharter.opf</code></a></li> + </ul> + </li> +</ul> + +</body> +</html> diff --git a/lib/ebooks/understandingoeb/understandingoeb.css b/lib/ebooks/understandingoeb/understandingoeb.css new file mode 100644 index 00000000..9b63783a --- /dev/null +++ b/lib/ebooks/understandingoeb/understandingoeb.css @@ -0,0 +1,28 @@ +.sidebar, sidebarTitle
+{
+ display: block;
+ background-color: silver;
+}
+
+h1
+{
+ font-family: sans-serif;
+ font-size: 130%;
+}
+
+h2
+{
+ font-family: sans-serif;
+ font-size: 120%;
+}
+
+h3
+{
+ font-family: sans-serif;
+ font-size: 110%;
+}
+
+blockquote
+{
+ font-size: 90%;
+}
diff --git a/lib/ebooks/understandingoeb/understandingoeb.opf b/lib/ebooks/understandingoeb/understandingoeb.opf new file mode 100644 index 00000000..aa80f073 --- /dev/null +++ b/lib/ebooks/understandingoeb/understandingoeb.opf @@ -0,0 +1,65 @@ +<?xml version="1.0"?>
+<!DOCTYPE package PUBLIC "+//ISBN 0-9673008-1-9//DTD OEB 1.0.1 Package//EN" "http://openebook.org/dtds/oeb-1.0.1/oebpkg101.dtd">
+<package unique-identifier="understandingoebpackage">
+ <metadata>
+ <dc-metadata xmlns:dc="http://purl.org/dc/elements/1.0/" xmlns:oebpackage="http://openebook.org/namespaces/oeb-package/1.0/">
+ <dc:Title>Understanding OEB</dc:Title>
+ <dc:Type>Tutorial</dc:Type>
+ <dc:Identifier id="understandingoebpackage" scheme="url">http://www.globalmentor.com/publishing/understandingoeb/</dc:Identifier>
+ <dc:Creator role="aut">Garret Wilson</dc:Creator>
+ <dc:Creator role="bkp">Mentor Publishing</dc:Creator>
+ <dc:Creator role="spn">GlobalMentor, Inc.</dc:Creator>
+ <dc:Contributor role="aui">David Ornstein</dc:Contributor>
+ <dc:Rights>Copyright © 2000-2001 Garret Wilson. All Rights Reserved.</dc:Rights>
+ <dc:Date>2001-07-11</dc:Date>
+ <dc:Subject>OEB</dc:Subject>
+ <dc:Subject>eBooks</dc:Subject>
+ <dc:Subject>ePublishing</dc:Subject>
+ </dc-metadata>
+ </metadata>
+
+ <manifest>
+ <!--OEB Documents-->
+ <item id="title" href="title.html" media-type="text/x-oeb1-document" />
+ <item id="toc" href="toc.html" media-type="text/x-oeb1-document" />
+ <item id="foreword" href="foreword.html" media-type="text/x-oeb1-document" />
+ <item id="preface" href="preface.html" media-type="text/x-oeb1-document" />
+ <item id="chapter1" href="chapter1.html" media-type="text/x-oeb1-document" />
+ <item id="chapter2" href="chapter2.html" media-type="text/x-oeb1-document" />
+ <item id="chapter3" href="chapter3.html" media-type="text/x-oeb1-document" />
+ <item id="chapter4" href="chapter4.html" media-type="text/x-oeb1-document" />
+ <item id="chapter5" href="chapter5.html" media-type="text/x-oeb1-document" />
+ <item id="chapter6" href="chapter6.html" media-type="text/x-oeb1-document" />
+ <!--Images-->
+ <item id="OEBActivityDiagram" href="OEBActivityDiagram.png" media-type="image/png" />
+ <item id="OEBClassDiagram" href="OEBClassDiagram.png" media-type="image/png" />
+ <item id="OEBPublicationClassDiagram" href="OEBPublicationClassDiagram.png" media-type="image/png" />
+ <item id="ReadingSystemClassDiagram" href="ReadingSystemClassDiagram.png" media-type="image/png" />
+ </manifest>
+
+ <spine>
+ <itemref idref="title" />
+ <itemref idref="toc" />
+ <itemref idref="foreword" />
+ <itemref idref="preface" />
+ <itemref idref="chapter1" />
+ <itemref idref="chapter2" />
+ <itemref idref="chapter3" />
+ <itemref idref="chapter4" />
+ <itemref idref="chapter5" />
+ <itemref idref="chapter6" />
+ </spine>
+
+ <guide>
+ <reference type="toc" title="Table of Contents" href="toc.html" />
+ <reference type="foreword" title="Foreword" href="foreword.html" />
+ <reference type="preface" title="Preface" href="preface.html" />
+ <reference type="other.chapter1" title="Chapter 1" href="chapter1.html" />
+ <reference type="other.chapter2" title="Chapter 2" href="chapter2.html" />
+ <reference type="other.chapter3" title="Chapter 3" href="chapter3.html" />
+ <reference type="other.chapter4" title="Chapter 4" href="chapter4.html" />
+ <reference type="other.chapter5" title="Chapter 5" href="chapter5.html" />
+ <reference type="other.chapter6" title="Chapter 6" href="chapter6.html" />
+ </guide>
+
+</package>
|
