Solution:

• Check for iconv() function existence
• Use mb_convert_encoding() as an alternative
• Create a simple transliterator when both iconv() and mb_convert_encoding() are unavailable

By default, chapters have labels which results in Chapter 1, Chapter 2.

If you remove the labels because you have you own title in each chapter, it will be displayed:

Chapter
My Own Title

Which is ugly.

I propose to not display Chapter if there is no label (or at least create an option for that)

When I published a pdf book, I found some blank pages on which there was only one sentence:

This Page Intentionally Left Blank

I don't want this at all. At first I guessed it's for two-sided printing, but my config.yml:

two_sided:      false

should have disabled it. Is it a bug?

Trying to generate a book (print) with a preface or prologue gives the following error:

[Twig_Error_Runtime]
Item "label" for "Array" does not exist in "toc.twig" at line 15

publish [--dir[="..."]] slug edition

Replacing "prologue" by "chapter" solves the issue.

easybook includes just one single default theme for every edition type:

app/
  Resources/
    Themes/
        Epub2/
        Pdf/
        Html/
        HtmlChunked/

If you want to change the design of a book, you have to create your own theme (as explained in the documentation).

This proposal would bring a full-featured, powerful but easy to use theme engine to easybook. The initial available themes would be:

• base, base theme used by all the other themes.
• clean (default theme), simple and minimalistic.
• bright, vibrant and modern.
• dark, matte black, modern and elegant.
• latex, LaTeX style copycat (including the fonts).
• tech, modern theme suited for tech books
• novel, simple theme for novels and regular books.

The base theme can't be used, but is necessary to simplify the themes. Some themes (e.g. latex) will be complex, but most themes will only change their CSS stylesheet.

The user could select the theme for the whole book and/or for each edition:

book:
  # ...
  theme: bright
  # ...

  editions:
    ebook:
      type:  epub
      theme: tech
      # ...

    print:
      type:  pdf
      theme: latex
      # ...

    web:
      type:  html
      # no `theme` option. Use `book` value for `theme` option

Directory structure for the new themes:

app/
  Resources/
    Themes/
      Base/
          Epub2/
          Pdf/
          Html/
          HtmlChunked/
    Clean/
          Epub2/
          Pdf/
          Html/
          HtmlChunked/  
    Bright/
          Epub2/
          Pdf/
          Html/
          HtmlChunked/
      Dark/
          Epub2/
          Pdf/
          Html/
          HtmlChunked/
      Latex/
          Epub2/
          Pdf/
          Html/
          HtmlChunked/
      ...

There is no obligation to define all variants for each theme. One particular theme could focus solely on epub edition whereas another theme could be pdf only.

If you install easybook via GitHub cloning without reading installation instructions, you'll end up with the following error:

PHP Warning:  require(.../easybook/vendor/autoload.php): failed to open stream: No such file or directory in .../easybook/book on line 13
PHP Fatal error:  require(): Failed opening required '.../easybook/vendor/autoload.php' (include_path='.:/usr/local/php:/usr/local/lib/php') in .../easybook/book on line 13

book script should check vendor/autoload.php existence and display a more helpful error messages if dependencies aren't installed:

[ERROR] It seems that easybook dependencies aren't installed.
Perhaps you forgot to execute `php composer.phar install` before using easybook?

If you haven't installed Composer yet, execute first the following command:
curl -s http://getcomposer.org/installer | php

It should allow to define the most common admonitions using the following blockquote-like syntax:

    [note]
    ...

    [tip]
    ...

    [warning]
    ...

    [sidebar "The title of the sidebar"]
    ...

Footnotes are very common for printed books. easybook should support footnote definition with the [fn] ... [/fn] simple syntax:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. [fn]Mauris in nunc lectus.
Mauris luctus, nibh at varius blandit, nisl mauris volutpat nibh, at malesuada justo
tortor vel mauris. Donec dui nisi, lacinia rhoncus semper nec, vulputate eget nunc.
Donec eu odio elit. Curabitur quis purus in nisl laoreet malesuada non id
dolor.[/fn] In vulputate mi in risus tempus dapibus. Sed sed dolor
nulla, sed luctus nulla. Fusce lectus massa, laoreet in tincidunt facilisis, tempor
in massa. Duis pretium nunc dui, non vestibulum lorem. Ut at est diam, ac porttitor est.
Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac
turpis egestas.

In a print book, the content enclosed by [fn][/fn] will be displayed as a footnote in the same page and will be replaced by an autogenerated numeric callout.

TODO: think about how to display footnotes in the other formats (html, html_chunked, and epub).

Usually, part content only display a title:

book:
  # ...
  contents:
    - { element: part, title: "My first book section/part" }

In some special cases, parts could also display contents (like a chapter or an appendix). The following should work:

book:
  # ...
  contents:
    - { element: part, title: "My first book section/part", content: "my-part-content.md" }

easybook should be easier to update. Add a simple update mechanism inspired by Silex update utility:

Show the installed version:

$ php easybook.phar version

 easybook 4.4 2012-05-05 10:53:31 +0100

Check that your are using the latest version:

$ php easybook.phar check

 You are running the latest easybook version (4.4)
 The latest easybook version (4.8) is more recent than yours (4.4)

Update to the latest version:

$ php easybook.phar update

 Updating easybook to 4.8 version ...
 Congrats! Your are running the latest easybook version.

If easybook were distributed as a .phar file (see discussion on pull request #2), updating would be easier.

Technical books usually include notes, tips and sidebars. These elements are generally referred as admonitions. Markdown doesn't define a proper syntax for these elements, and books end up using strange hacks.

easybook will extend Markdown syntax to add support for the most common admonitions:

[note]
 ...
[/note]

[tip]
 ...
[/tip]

[caution]
 ...
[/caution]

[sidebar "The title of the sidebar"]
 ...
[/sidebar]

Inside each of these admonitions you can use any other Markdown syntax.

Blank pages inserted for proper two side formatting should show a message like "This page intentionally left blank".

Internal links or intralinks work great for html and pdf type editions. In html_chunked and epub type editions they don't work because href attribute only contains the fragment of the URL.

Solution: create a LinkPlugin which adds the chunk fileName part before the fragment of the URL.

Wrong: <a href="#my-section">my link</a>

Correct: <a href="another-chapter.html#my-section">my link</a>

Currently, the only input format that supports easybook for writing books and documents is Markdown. Although the built-in parser improves significantly the original features of Markdown, it may be better if easybook supported other input formats.

The following list describes the formats that will be added some day:

• html: adding support for this format should be trivial and could allow to transform legacy documentation and entire websites to printed books and ebooks.
• reStructuredText: very complex to parse and scarce PHP support. It has a very active and loyal fan support, specially among Python developers.
• pdf: ideally, with this format easybook could transform automatically a PDF file into an ebook.

Please, feel free to suggest any other input format and we'll evaluate its feasibility.

Besides basic markdown formatting, explain the main features of easybook Markdown:

• Code listing syntax highlighting
• Complex tables
• Internal links (with section reference)
• Admonitions ([note], [tip], ...)

It's not a common task, but advanced plugins may need to use external libraries and other assets.

TODO: think about a simple strategy to register resources

if i write:

$ php composer.phar install

The result is:

[ErrorException]                                                                                                                   
  file_put_contents(/home/alexis/.composer/cache/http---packagist.org/packages-dev-k.json): failed to open stream: Permiso denegado  

install [--prefer-source] [--dry-run] [--dev] [--no-scripts]

if i tray:

sudo php composer.phar install 

Result:

Installing dependencies
Your requirements could not be solved to an installable set of packages.

  Problem 1
    - The requested package symfony/console 2.1.* could not be found.
  Problem 2
    - The requested package symfony/event-dispatcher 2.1.* could not be found.
  Problem 3
    - The requested package symfony/filesystem 2.1.* could not be found.
  Problem 4
    - The requested package symfony/finder 2.1.* could not be found.
  Problem 5
    - The requested package symfony/yaml 2.1.* could not be found.

Potential causes:
 - A typo in the package name
 - The package is not available in a stable-enough version according to your minimum-stability setting
   see https://groups.google.com/d/topic/composer-dev/_g3ASeIFlrc/discussion for more details.

Running the following command from my easybook directory:

./book new "The Origin of Species"

Results in the following error:

Unsupported "/Book" template format (easybook only supports Twig)

Try https://github.com/antialize/wkhtmltopdf for generating PDF files instead of PrinceXML library.

Evaluate the use of wkhtmltopdf as a fallback for users who don't/can't use PrinceXML.

$ ./book
PHP Strict Standards: Declaration of Easybook\Console\Command\BaseCommand::initialize() should be compatible with Symfony\Component\Console\Command\Command::initialize(Symfony\Component\Console\Input\InputInterface $input, Symfony\Component\Console\Output\OutputInterface $output) in /usr/local/src/javiereguiluz-easybook-c1e4bbe/src/Easybook/Console/Command/BaseCommand.php on line 74

When overriding methods, the parameter signature should remain the same or PHP will generate an E_STRICT level error. This does not apply to the constructor, which allows overriding with different parameters.

$ vi src/Easybook/Console/Command/BaseCommand.php
// Add
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

// Modify
protected function initialize()
↓
protected function initialize(InputInterface $input = null, OutputInterface $output = null)

$ php -v
PHP 5.4.0RC6

easybook should provide a plugin command to bootstrap new plugin creation:

$ ./book plugin Text

The above command will create Resources/Plugins/TextPlugin.php file with the following skeleton:

<?php

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Easybook\Events\EasybookEvents as Events;
use Easybook\Events\ParseEvent;

class TextPlugin implements EventSubscriberInterface
{
    static public function getSubscribedEvents()
    {
        return array(
            // add this if you need to manipulate item content before being transformed to HTML
            Events::PRE_PARSE  => array('onItemPreParse', -500),

            // add this if you need to manipulate item content after being transformed to HTML
            Events::POST_PARSE => array('onItemPostParse', -500),
        );
    }

    /**
     * Modifies item content before transforming it to HTML.
     * Use this method when extending the original Markdown syntax.
     *
     * Access to any application property or method:
     *   $format  = $event->app->edition('format');
     *   $slugger = $event->app->get('slugger');
     *
     * Access to the item being parsed:
     *   $item = $event->getItem();
     *   $originalMarkdownContent = $item['original'];
     * 
     * @param  ParseEvent $event A special event object that eases the manipulation
     *                           of the object being parsed.
     */
    public function onItemPreParse(ParseEvent $event)
    {
        // get the item being parsed
        $item = $event->getItem();

        // modify the original Markdown item content
        $item['original'] = preg_replace_callback('...regexp...',
            function($matches) use ($event) {
                // ... manipulate content ...

                return $modifiedContent;
            },
            $item['original']
        );

        // save the modified content
        $event->setItem($item);
    }

    /**
     * Modifies item content after transforming it to HTML.
     * Use this method when tweaking or fixing the generated HTML output.
     *
     * Access to any application property or method:
     *   $format  = $event->app->edition('format');
     *   $slugger = $event->app->get('slugger');
     *
     * Access to the item being parsed:
     *   $item = $event->getItem();
     *   $transformedHTMLContent  = $item['content'];
     * 
     * @param  ParseEvent $event A special event object that eases the manipulation
     *                           of the object being parsed.
     */
    public function onItemPostParse(ParseEvent $event)
    {
        // get the item being parsed
        $item = $event->getItem();

        // modify the generated HTML item content
        $item['content'] = preg_replace_callback('...regexp...',
            function($matches) use ($event) {
                // ... manipulate content ...

                return $modifiedContent;
            },
            $item['content']
        );

        // save the modified content
        $event->setItem($item);
    }
}

An clear error message should be shown when the publish command is executed with a reference to a non-existent file. At the moment there is no clear indication of the error that occurred.

easybook allows ePub format books to use a custom cover image. In contrast, PDF format books cannot set custom covers automatically.

The solution to this issue is not as easy as it sounds:

• If the custom cover defined as a PDF file, easybook should merge two PDF files (using Zend_PDF component).
• If the custom cover is defined as an image file, it should be set as the background image of a blank cover, making sure it stretches to the full height and width of the cover (this isn't easy with PrinceXML PDF library).

First, look for pseudo official extensions made by others, such as the additions created by PHP Markdown extra

Following the tutorial, line by line on Fedora 17. Then trying:
./book publish easybook-doc-en ebook

It fails with the following error:

                     |              |    
 ,---.,---.,---.,   .|---.,---.,---.|__/ 
 |---',---|`---.|   ||   ||   ||   ||  \ 
 `---'`---^`---'`---|`---'`---'`---'`   `
                `---'


 Publishing ebook edition of easybook documentation book...




  [Twig_Error_Runtime]                                                                                                           
  An exception has been thrown during the rendering of a template ("DateTime::__construct(): It is not safe to rely on the syst  
  em's timezone settings. You are *required* to use the date.timezone setting or the date_default_timezone_set() function. In c  
  ase you used any of those methods and you are still getting this warning, you most likely misspelled the timezone identifier.  
   We selected the timezone 'UTC' for now, but please set date.timezone to select your timezone.") in "content.opf.twig" at lin  
  e 48.                                                                                                                          


  [Exception]                                                                                                                    
  DateTime::__construct(): It is not safe to rely on the system's timezone settings. You are *required* to use the date.timezon  
  e setting or the date_default_timezone_set() function. In case you used any of those methods and you are still getting this w  
  arning, you most likely misspelled the timezone identifier. We selected the timezone 'UTC' for now, but please set date.timez  
  one to select your timezone.                                                                                                   



publish [--dir[="..."]] slug edition

Running the interactive version of the publish command

./book publish

Results in a warning

Warning: array_key_exists() expects parameter 2 to be array, string given in /path/to/easybook/src/Easybook/Console/Command/BookPublishCommand.php on line 83

Instead of this:

$temp = tempnam(sys_get_temp_dir(), 'easybook_');

Hello,

I'm using Easybook to make a book of short stories:
https://github.com/ploum/cest-la-vie

Between stories (which used the "chapter" type), I would like to insert some interchapter text.

• The text of the interchapter has no title.
• The whole text is in
• An interchapter should not appear in the Toc.
• A blank page is not necessary after the previous chapter (but well before the next one)

Add the following steps in http://easybook-project.org/doc/chapter-1.html and http://easybook-project.org/es/doc/capitulo-1.html

curl -s http://getcomposer.org/installer | php
php composer.phar

When you publish a book repeatedly to monitor its progress, the book is completely regenerated each time. A much better strategy would be to watch for content changes and regenerate only the needed items.

This cache mechanism is extremely hard to implement, as content modifications may affect some other unchanged contents (think for example about internal book links). The proposal is to use the cache mechanism only when the user declares it explicitly via --use-cache option:

# regenerate the full book each time
$ ./book publish my-book my-edition

# regenerate only the changed contents
$ ./book publish my-book my-edition --use-cache

The cache should work as follows:

1. If the configuration is modified since last publication, regenerate the full book.
2. If the theme files have been modified, regenerate the full book.
3. Detect the changed items since last execution and regenerate them.

It must be taken into account that the time consumed by #1 and #2 mandatory checks may consume more time that the time gained by the cache itself.

Markdown / Markdown Extra don't support image alignment:

![Alt text](image01.png)

This may be sufficient for webpages, but real-world books need to align images to the right/left/center. New syntax proposals:

![Alt text](:image01.png)
![Alt text](image01.png:)
![Alt text](:image01.png:)

![Alt text](_image01.png)
![Alt text](image01.png_)
![Alt text](_image01.png_)

![Alt text](image01.png)<-
![Alt text](image01.png)->
![Alt text](image01.png)<->

![Alt text](image01.png)(left)
![Alt text](image01.png)(right)
![Alt text](image01.png)(center)

![Alt text](image01.png){ align: left }
![Alt text](image01.png){ align: right }
![Alt text](image01.png){ align: center }

HI/Hola Javier,

Sun 2010/08/12 16:00

• Win7 x64 Home
• PHP 5.3.15

git clone http://github.com/javiereguiluz/easybook.git easybook
curl -s http://getcomposer.org/installer | php
php composer.phar install

php book publish
easybook-doc-en
pdf

STOP

DateTime::__construct(): It is not safe to rely on the system's timezone setti
ngs. You are required to use the date.timezone setting or the date_default_tim
ezone_set() function. In case you used any of those methods and you are still ge
tting this warning, you most likely misspelled the timezone identifier. We selec
ted 'Europe/Paris' for '2.0/DST' instead

publish [--dir[="..."]] [--configuration[="..."]] slug edition

No output generated

Miguel Ruiz
Sevilla

SSIA

Hi, I am getting this error while trying to publish print, web or website.

[Twig_Error_Runtime]
An exception has been thrown during the rendering of a template ("DateTime::__construct(): It is not safe to rely on the system's timezone settings. You are required to use the date.timezone setting or the date_default_timezone_set() function. In case you used any of those methods and you are still getting this warning, you most likely misspelled the timezone identifier. We selected 'America/Los_Angeles' for 'PST/-8.0/no DST' instead").

[Exception]
DateTime::__construct(): It is not safe to rely on the system's timezone settings. You are required to use the date.timezone setting or the date_default_timezone_set() function. In case you used any of those methods and you are still getting this warning, you most likely misspelled the timezone identifier. We selected 'America/Los_Angeles' for 'PST/-8.0/no DST' instead

Between paragraphs, you often want to insert a centered star: *

It would be nice to have a way to center something very easily with Easybook.

Suggestions: automaticaly centering a star if alone on a line and previous and next line are empty.

Or some markdown syntax for that (like >*< )

Or a way to center an image.

.epub format consist of a .zip file with the book contents. The method used by easybook to generate the .zip file requires that zip extension is loaded in PHP (you can see loaded extensions with php -m command). Therefore, if zip extension isn't loaded, easybook outputs the following error when generating a .epub book:

[Symfony\Component\Filesystem\Exception\IOException]
  Failed to copy.../easybook-doc-en-ebook/book.zip to
  .../easybook-doc-en/Output/ebook/book.epub

PHP Warning:  copy(.../easybook-doc-en-ebook/book.zip): failed to open stream:
No such file or directory in ...Symfony/Component/Filesystem/Filesystem.php on line 47

easybook should use an alternative method to generate ZIP files when zip extension is unavailable. PclZip class for example generates ZIP files by using just the zlib extension, available (nearly) in every PHP server.

PrinceXML supports footnotes by default (just wrap its contents with <fn> tags).

Look for footnote implementations in web environment. Show them with Twitter Bootstrap popovers?

Consider the enhancement of easybook adding a new feature that generates HTML5 slides from the Markdown source.

Trying to install via Composer, and EasyBook declares a dependency on the geshi/geshi package, which doesn't exist on Packagist.

http://packagist.org/search/?search_query%5Bquery%5D=geshi%2Fgeshi

I am getting the following error when I run ./book publish "book-name" web

Warning: in_array() expects parameter 2 to be array, null given in /Users/dwarakanathk/easybook/src/Easybook/Plugins/ParserPlugin.php on line 52

Warning: in_array() expects parameter 2 to be array, null given in /Users/dwarakanathk/easybook/src/Easybook/Plugins/ParserPlugin.php on line 52

Warning: in_array() expects parameter 2 to be array, null given in /Users/dwarakanathk/easybook/src/Easybook/Plugins/ParserPlugin.php on line 52

Warning: in_array() expects parameter 2 to be array, null given in /Users/dwarakanathk/easybook/src/Easybook/Plugins/ParserPlugin.php on line 52

[Twig_Error_Runtime]
Item "label" for "Array" does not exist

publish [--dir[="..."]] slug edition

The config file is the default one created using the new command. Using mac os x 10.6.8

Printed books usually display some important information in the back cover, such as content excerpts, reviews, ISBN barcode, etc. Ideally, easybook should be able to automatically generate elements such as the barcode/qrcode.

Following the tutorial, line by line on Fedora 17. Then trying:
./book publish easybook-doc-en print

It fails with the following error:

Publishing print edition of easybook documentation book...

PHP Fatal error: Call-time pass-by-reference has been removed in /home/ploum/hacking/easybook/src/Easybook/Publishers/PdfPublisher.php on line 115

In some scenarios, option values cannot be set via config.yml file due to their dynamic nature. easybook should allow to set any book or edition option via console parameters:

$ ./book publish my-book my-edition --book-options="array('title' => 'My new title for the book')"

$ ./book publish my-book my-edition --edition-options="array('print' => array('highlight_code' => false))"
$ ./book publish my-book my-edition --edition-option="array('web' => array('toc' => array('deep' => 4)))"

Option values can reference any other configuration option, as they are processed as Twig string templates:

$ ./book publish my-book my-edition --book-options="array('title' => '{{ book.author }} diary')"
$ ./book publish my-book my-edition --book-options="array('publication_date' => '{{ '+2days'|date('Ymd') }}')"

Option values set via console options always override any other values.

Hello,

When I run a simple ./book publish 'test' print I keep getting these errors:

wrn: cannot open resource (/home/dorer/Documents/EasyBook/app/Resources/Fonts/Neuton/Neuton-Regular.ttf)
wrn: cannot open resource (/home/dorer/Documents/EasyBook/app/Resources/Fonts/Neuton/Neuton-Bold.ttf)
wrn: cannot open resource (/home/dorer/Documents/EasyBook/app/Rssources/Fonts/Neuton/Neuton-Italic.ttf)

But the operation still works fine, it's just I don't think I am getting all the feature, since the chapter titles didn't look that great (or maybe it's just me). How can I solve this?