diff options
Diffstat (limited to 'doc/context/sources/general/manuals/epub/epub-mkiv.tex')
| -rw-r--r-- | doc/context/sources/general/manuals/epub/epub-mkiv.tex | 466 |
1 files changed, 466 insertions, 0 deletions
diff --git a/doc/context/sources/general/manuals/epub/epub-mkiv.tex b/doc/context/sources/general/manuals/epub/epub-mkiv.tex new file mode 100644 index 000000000..6fc4ed9d4 --- /dev/null +++ b/doc/context/sources/general/manuals/epub/epub-mkiv.tex @@ -0,0 +1,466 @@ +% language=uk + +% todo: +% +% metadata +% properties +% \dontleavehmode before hbox +% cover page +% +% http://www.cnet.com/news/google-subtracts-mathml-from-chrome-and-anger-multiplies/ + +% \usemodule[luacalls] + +\usemodule[art-01,abr-02] + +\definehighlight[notabene][style=bold] + +\definecolor[darkorange] [.70(green,red)] +\definecolor[lightorange][.45(orange,white)] +\definecolor[lesswhite] [.90(white)] + +\setuptyping[color=darkorange] +\setuptype [color=darkorange] + +\starttext + +\startMPpage + +numeric w ; w := 21cm ; +numeric h ; h := 29.7cm ; +numeric ww ; ww := 9w/10 ; +numeric oo ; oo := (w-ww) / 2 ; +numeric hh ; hh := h/5.5 ; +path p ; p := unitsquare xysized(w,h) ; + +color orange ; orange := \MPcolor{darkorange} ; % .7[green,red] ; + +fill p enlarged 2mm withcolor orange ; + +draw image ( + draw anchored.top( + textext("\ttbf\setupinterlinespace[line=1.7ex]\framed[frame=off,align=middle,offset=0mm]{\smash{<div/>}\\\smash{<div >}\\\smash{</div>}}") + xsized w, + center topboundary p shifted (0,-12mm)) withcolor \MPcolor{lightorange} ; % 0.45[white,orange] ; + draw anchored.bot( + textext("\ssbf\setupinterlinespace[line=2.2ex]\framed[frame=off,align=middle]{exporting\\xml and epub\\from context}") + xsized w, + center bottomboundary p shifted (0,4mm)) withcolor \MPcolor {lesswhite} ; % 0.90white ; +) ; + +setbounds currentpicture to p ; + +\stopMPpage + +\startsection[title=Introduction] + +There is a pretty long tradition of typesetting math with \TEX\ and it looks like +this program will dominate for many more years. Even if we move to the web, the +simple fact that support for \MATHML\ in some browsers is suboptimal will drive +those who want a quality document to use \PDF\ instead. + +I'm writing this in 2014, at a time when \XML\ is widespread. The idea of \XML\ is +that you code your data in a very structured way, so that it can be manipulated and +(if needed) validated. Text has always been a target for \XML\ which is a follow|-|up +to \SGML\ that was in use by publishers. Because \HTML\ is less structured (and also +quite tolerant with respect to end tags) we prefer to use \XHTML\ but unfortunately +support for that is less widespread. + +Interestingly, documents are probably among the more complex targets of the +\XML\ format. The reason is that unless the author restricts him|/|herself or +gets restricted by the publisher, tag abuse can happen. At \PRAGMA\ we mostly +deal with education|-|related \XML\ and it's not always easy to come up with +something that suits the specific needs of the educational concept behind a +school method. Even if we start out nice and clean, eventually we end up with a +polluted source, often with additional structure needed to satisfy the tools used +for conversion. + +We have been supporting \XML\ from the day it showed up and most of our projects +involve \XML\ in one way or the other. That doesn't mean that we don't use \TEX\ +for coding documents. This manual is for instance a regular \TEX\ document. In +many ways a structured \TEX\ document is much more convenient to edit, especially +if one wants to add a personal touch and do some local page make|-|up. On the other hand, +diverting from standard structure commands makes the document less suitable for +output other than \PDF. There is simply no final solution for coding a document, +it's mostly a matter of taste. + +So we have a dilemma: if we want to have multiple output, frozen \PDF\ as well as +less-controlled \HTML\ output, we can best code in \XML, but when we want to code +comfortably we'd like to use \TEX. There are other ways, like Markdown, that can +be converted to intermediate formats like \TEX, but that is only suitable for +simple documents: the more advanced documents get, the more one has to escape +from the boundaries of (any) document encoding, and then often \TEX\ is not a bad +choice. There is a good reason why \TEX\ survived for so long. + +It is for this reason that in \CONTEXT\ \MKIV\ we can export the content in a +reasonable structured way to \XML. Of course we assume a structured document. It +started out as an experiment because it was relatively easy to implement, and it +is now an integral component. + +\stopsection + +\startsection[title=The output] + +The regular output is an \XML\ file but as we have some more related data it gets +organized in a tree. We also export a few variants. An example is given below: + +\starttyping +./test-export +./test-export/images +./test-export/images/... +./test-export/styles +./test-export/styles/test-defaults.css +./test-export/styles/test-images.css +./test-export/styles/test-styles.css +./test-export/styles/test-templates.css +./test-export/test-raw.xml +./test-export/test-raw.lua +./test-export/test-tag.xhtml +./test-export/test-div.xhtml +\stoptyping + +Say that we have this input: + +\starttyping +\setupbackend + [export=yes] + +\starttext + \startsection[title=First] + \startitemize + \startitem one \stopitem + \startitem two \stopitem + \stopitemize + \stopsection +\stoptext +\stoptyping + +The main export ends up in the \type {test-raw.xml} export file and looks like +the following (we leave out the preamble and style references): + +\starttyping +<document> <!-- with some attributes --> + <section detail="section" chain="section" level="3"> + <sectionnumber>1</sectionnumber> + <sectiontitle>First</sectiontitle> + <sectioncontent> + <itemgroup detail="itemize" chain="itemize" symbol="1" level="1"> + <item> + <itemtag><m:math ..><m:mo>•</m:mo></m:math></itemtag> + <itemcontent>one</itemcontent> + </item> + <item> + <itemtag><m:math ..><m:mo>•</m:mo></m:math></itemtag> + <itemcontent>two</itemcontent> + </item> + </itemgroup> + </sectioncontent> + </section> +</document> +\stoptyping + +This file refers to the stylesheets and therefore renders quite well in a browser +like Firefox that can handle \XHTML\ with arbitrary tags. + +The \type {detail} attribute tells us what instance of the element is used. +Normally the \type {chain} attribute is the same but it can have more values. +For instance, if we have: + +\starttyping +\definefloat[graphic][graphics][figure] + +..... + +\startplacefigure[title=First] + \externalfigure[cow.pdf] +\stopplacefigure + +..... + +\startplacegraphic[title=Second] + \externalfigure[cow.pdf] +\stopplacegraphic +\stoptyping + +we get this: + +\starttyping +<float detail="figure" chain="figure"> + <floatcontent>...</floatcontent> + <floatcaption>...</floatcaption> +</float> +<float detail="graphic" chain="figure graphic"> + <floatcontent>...</floatcontent> + <floatcaption>...</floatcaption> +</float> +\stoptyping + +This makes it possible to style specific categories of floats by using a +(combination of) \type {detail} and|/|or \type {chain} as filters. + +The body of the \type {test-tag.xhtml} file looks similar but it is slightly more +tuned for viewing. For instance, hyperlinks are converted to a way that \CSS\ and +browsers like more. Keep in mind that the raw file can be the base for conversion +to other formats, so that one stays closest to the original structure. + +The \type {test-div.xhtml} file is even more tuned for viewing in browsers as it +completely does away with specific tags. We explicitly don't map onto native +\HTML\ elements because that would make everything look messy and horrible, if only +because there seldom is a relation between those elements and the original. One +can always transform one of the export formats to pure \HTML\ tags if needed. + +\starttyping +<body> + <div class="document"> + <div class="section" id="aut-1"> + <div class="sectionnumber">1</div> + <div class="sectiontitle">First</div> + <div class="sectioncontent"> + <div class="itemgroup itemize symbol-1"> + <div class="item"> + <div class="itemtag"><m:math ...><m:mo>•</m:mo></m:math></div> + <div class="itemcontent">one</div> + </div> + <div class="item"> + <div class="itemtag"><m:math ...><m:mo>•</m:mo></m:math></div> + <div class="itemcontent">two</div> + </div> + </div> + <div class="float figure"> + <div class="floatcontent">...</div></div> + <div class="floatcaption">...></div> + </div> + <div class="float figure graphic"> + <div class="floatcontent">...</div></div> + <div class="floatcaption">...></div> + </div> + </div> + </div> +</body> +\stoptyping + +The default \CSS\ file can deal with tags as well as classes. The file +of additional styles contains definitions of so|-|called highlights. In the \CONTEXT\ source +one is better off using explicit named highlights instead of local font and color +switches because these properties are then exported to the \CSS. The images style +defines all images used. The templates file lists all the elements used and can +be used as a starting point for additional \CSS\ styling. + +Keep in mind that the export is \notabene{not} meant as a one|-|to|-|one visual +representation. It represents structure so that it can be converted to whatever +you like. + +In order to get an export you must start your document with: + +\starttyping +\setupbackend + [export=yes] +\stoptyping + +So, we trigger a specific (extra) backend. In addition you can set up the export: + +\starttyping +\setupexport + [svgstyle=test-basic-style.tex, + cssfile=test-extras.css, + hyphen=yes, + width=60em] +\stoptyping + +The \type {hyphen} option will also export hyphenation information so that the +text can be nicely justified. The \type {svgstyle} option can be used to specify +a file where math is set up; normally this would only contain a \type{bodyfont} setup, +and this option is only needed if you want to create an \EPUB\ file afterwards which +has math represented as \SVG. + +The value of \type {cssfile} ends up as a style reference in the exported files. +You can also pass a comma|-|separated list of names (between curly braces). These +entries come after those of the automatically generated \CSS\ files so you need +to be aware of default properties. + +\stopsection + +\startsection[title=Images] + +Inclusion of images is done in an indirect way. Each image gets an entry in a +special image related stylesheet and then gets referred to by \type {id}. Some +extra information is written to a status file so that the script that creates +\EPUB\ files can deal with the right conversion, for instance from \PDF\ to \SVG. +Because we can refer to specific pages in a \PDF\ file, this subsystem deals with +that too. Images are expected to be in an \type {images} subdirectory and because in \CSS\ +the references are relative to the path where the stylesheet resides, we use +\type {../images} instead. If you do some postprocessing on the files or relocate +them you need to keep in mind that you might have to change these paths in the +image|-|related \CSS\ file. + +\stopsection + +\startsection[title=Epub files] + +At the end of a run with exporting enabled you will get a message to the console that +tells you how to generate an \EPUB\ file. For instance: + +\starttyping +mtxrun --script epub --make --purge test +\stoptyping + +This will create a tree with the following organization: + +\starttyping +./test-epub +./test-epub/META-INF +./test-epub/META-INF/container.xml +./test-epub/OEBPS +./test-epub/OEBPS/content.opf +./test-epub/OEBPS/toc.ncx +./test-epub/OEBPS/nav.xhtml +./test-epub/OEBPS/cover.xhtml +./test-epub/OEBPS/test-div.xhtml +./test-epub/OEBPS/images +./test-epub/OEBPS/images/... +./test-epub/styles +./test-epub/styles/test-defaults.css +./test-epub/styles/test-images.css +./test-epub/styles/test-styles.css +./test-epub/mimetype +\stoptyping + +Images will be moved to this tree as well and if needed they will be converted, +for instance into \SVG. Converted \PDF\ files can have a \typ {page-<number>} in +their name when a specific page has been used. + +You can pass the option \type {--svgmath} in which case math will be converted to +\SVG. The main reason for this feature is that we found out that \MATHML\ support +in browsers is not currently as widespread as might be expected. The best bet is Firefox which +natively supports it. The Chrome browser had it for a while but it got dropped +and math is now delegated to \JAVASCRIPT\ and friends. In Internet Explorer +\MATHML\ should work (but I need to test that again). + +This conversion mechanism is +kind of interesting: one enters \TEX\ math, then gets \MATHML\ in the export, and +that gets rendered by \TEX\ again, but now as a standalone snippet that then gets +converted to \SVG\ and embedded in the result. + +\stopsection + +\startsection[title=Styles] + +One can argue that we should use native \HTML\ elements but since we don't have a nice +guaranteed|-|consistent mapping onto that, it makes no sense to do so. Instead, we +rely on either explicit tags with details and chains or divisions with classes +that combine the tag, detail and chain. The tagged variant has some more +attributes and those that use a fixed set of values become classes in the +division variant. Also, once we start going the (for instance) \type {H1}, \type +{H2}, etc.\ route we're lost when we have more levels than that or use a +different structure. If an \type {H3} can reflect several levels it makes no +sense to use it. The same is true for other tags: if a list is not really a list +than tagging it with \type {LI} is counterproductive. We're often dealing with +very complex documents so basic \HTML\ tagging becomes rather meaningless. + +If you look at the division variant (this is used for \EPUB\ too) you will notice +that there are no empty elements but \type {div} blocks with a comment as content. +This is needed because otherwise they get ignored, which for instance makes table +cells invisible. + +The relation between \type {detail} and \type {chain} (reflected in \type {class}) +can best be seen from the next example. + +\starttyping +\definefloat[myfloata] +\definefloat[myfloatb][myfloatbs][figure] +\definefloat[myfloatc][myfloatcs][myfloatb] +\stoptyping + +This creates two new float instances. The first inherits from the main float +settings, but can have its own properties. The second example inherits from +the \type {figure} so in fact it is part of a chain. The third one has a longer +chain. + +\starttyping +<float detail="myfloata">...</float> +<float detail="myfloatb" chain="figure">...</float> +<float detail="myfloatc" chain="figure myfloatb">...</float> +\stoptyping + +In a \CSS\ style you can now configure tags, details, and chains as well as +classes (we show only a few possibilities). Here, the \CSS\ element on the +first line of each pair is invoked by the \CSS\ selector on the second line. + +\starttyping +div.float.myfloata { } float[detail='myfloata'] { } +div.float.myfloatb { } float[detail='myfloatb'] { } +div.float.figure { } float[detail='figure'] { } +div.float.figure.myfloatb { } float[chain~='figure'][detail='myfloata'] { } +div.myfloata { } *[detail='myfloata'] { } +div.myfloatb { } *[detail='myfloatb'] { } +div.figure { } *[chain~='figure'] { } +div.figure.myfloatb { } *[chain~='figure'][detail='myfloatb'] { } +\stoptyping + +The default styles cover some basics but if you're serious about the export +or want to use \EPUB\ then it makes sense to overload some of it and|/|or +provide additional styling. You can find plenty about \CSS\ and its options +on the Internet. + +\stopsection + +\startsection[title=Coding] + +The default output reflects the structure present in the document. If that is not +enough you can add your own structure, as in: + +\starttyping +\startelement[question] +Is this right? +\stopelement +\stoptyping + +You can also pass attributes: + +\starttyping +\startelement[question][level=difficult] +Is this right? +\stopelement +\stoptyping + +But these will be exported only when you also say: + +\starttyping +\setupexport + [properties=yes] +\stoptyping + +You can create a namespace. The following will generate attributes +like \type {my-level}. + +\starttyping +\setupexport + [properties=my-] +\stoptyping + +In most cases it makes more sense to use highlights: + +\starttyping +\definehighlight + [important] + [style=bold] +\stoptyping + +This has the advantage that the style and color are exported to a special +\CSS\ file. + +Headers, footers, and other content that is part of the page builder are not +exported. If your document has cover pages you might want to hide them too. The +same is true when you create special chapter title rendering with a side +effect that content ends up in the page stream. If something shows up that you +don't want, you can wrap it in an \type {ignore} element: + +\starttyping +\startelement[ignore] +Don't export this. +\stopelement +\stoptyping + +\stopsection + +\stoptext |