IdeoType User Guide

Usage

The workflow is simple. Just get your manuscript ready and run the software.

Prepare manuscript.
Run IdeoType to generate PDF.

You can edit the manuscript and re-generate PDF as many times as you want. Clean up files when you are done. See the following sections for instruction.

Manuscript Preparation

IdeoType accepts XHTML-like manuscript format. Technically, it is a subset of XHTML + MathML, expanded using class, id, title and other attributes. (A kind of microformats.)

We use XHTML as manuscript format since (X)HTML is well supported by many people and software, and it can express rich information necessary for books. You can import HTML output from other tools such as word processors, blogs, Wikis, etc. (We will discuss it later.)

Note:

Manuscript should be valid XHTML.
Encoding must be UTF-8.
Filename suffix has to be .xhtml.
Table for layout, complex table, GIF images, ruby, etc. are not supported (yet).

Manuscript should look like this, for example:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0//EN"
 "http://www.w3.org/TR/MathML2/dtd/xhtml-math11-f.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-type" content="application/xhtml+xml;"/>
    <meta name="author" content="John Doe"/>
    <meta name="date" content="2038-02-31"/>
    <title>Title</title>
  </head>
  <body>
    ...
  </body>
</html>

See the notation section for detail.

Generating PDF from Manuscript

As of writing this, command-line interface is the default.

When your manuscript is foo.xhtml, type ideotype build foo.pdf to produce PDF.

You can try it out with the test data included in the distribution.

% cp -r /usr/share/doc/ideotype ./
% cd ideotype
% ls test/testdata.xhtml
test/testdata.xhtml
% ideotype build test/testdata.pdf
...
% ls test/testdata.pdf
test/testdata.pdf
%

Cleaning Up Files

To clean up intermediate files, type ideotype clean bookname.

% ideotype clean test/testdata

To clean up all the generated files including PDF, type ideotype distclean bookname.

% ideotype distclean test/testdata

Advanced Usage

Using Existing HTML Documents as Manuscript

To download HTML document accompanying images, etc. from the Web, type ideotype download URL.

% ideotype download http://example.org/foo.html

To import HTML document and accompanying images, etc., type ideotype import filename.

% ideotype import example.org/foo.html

Note that only clean HTML can be imported. This feature is still preliminary.

Render Specific Language Only

langs option lets you extract elements with specific xml:lang attribute (and language-independent common elements with no xml:lang attribute).

% ideotype --langs="en" build test/testdata.pdf
% ideotype --langs="all" build test/testdata.pdf

Note that invalid xml:lang value in the manuscript leads to inproper result.

Per-Project Customization

You can configure your project setting via project configuration files (still an experimental feature).

% ideotype initproject .
% cp .book/html2latex.xsl.example .book/html2latex.xsl
% $EDITOR .book/html2latex.xsl

Troubleshooting

Q.It does not convert my manuscript.

A.Make sure the manuscript is valid XHTML using validator.

A. Building intermediate files helps troubleshooting.
```
% ideotype build test/testdata.tex
```
Q.Is feature X supported?

A.Type ideotype --help to see the help message. If not found, sorry, not yet. Your help would be highly appreciated.