====== BookCreator Plugin ====== ---- plugin ---- description: Allow to select some pages and create a book (PDF, ODT or text) author : Gerrit Uitslag (original author: Luigi Micco) email : klapinklapin@gmail.com # previous: l.micco@tiscali.it type : action, syntax lastupdate : 2024-02-07 compatible : Elenor Of Tsort, Frusterick Manners, Greebo, Hogfather, Igor, Jack Jackrum, Kaos depends : dw2pdf, text, odt conflicts : projects similar : odt, dw2pdf tags : export, pdf, odt, books securitywarning: downloadurl: https://github.com/Klap-in/dokuwiki-plugin-bookcreator/archive/master.zip bugtracker : https://github.com/Klap-in/dokuwiki-plugin-bookcreator/issues sourcerepo : https://github.com/Klap-in/dokuwiki-plugin-bookcreator donationurl: screenshot_img : https://trello.com/1/cards/644c13bd06a0c6737cae672f/attachments/644c1410e00d0916dfc21f6c/download/bookcreator_bookmanager.png ---- ===== Description ===== The **bookcreator** plugin allows the user to select some pages from a wiki and then export them to create a little PDF book or text (like a similar [[wp>Help:Books|function of Wikipedia]]). First you initialize a book by clicking an interface button. Nextly, a toolbar at the top of the pages appear to add/remove more pages to the book. Also you can jump to the bookmanager (at a preconfigured page) that let you sort and finish the selections for your book, and export it to screen(html) and when the required plugins are installed: to pdf-file, odt-file or text on screen. The bookmanager let you save and load saved selections for later use. You can use drag and drop to change the order and move pages in and out. The bookcreator supports the following export formats, if you install respectively plugin: * To work the PDF export required [[plugin:dw2pdf|dw2pdf]] plugin; * the ODT export required [[plugin:odt|OpenDocument Export]] plugin; * the Text export required the [[plugin:text|text]] plugin. ===== Usage ===== ==== Create book manage tools on wiki:ebook ==== Before using this plugin, you need to create a page with the bookmanager. Therefore you place the syntax ''~~BOOK~~'' in the wiki page ''wiki:ebook'' (in the configuration manager you can change this location). In the bookmanager can show and manage your list of selected pages * Reset current selection * Exclude/include a page from selection * View the excluded pages and "include" them back * Drag and drop to change exporting order of page and remove/add page to the selection. * Set a title for the PDF document * Create the PDF book on selected pages * Create a printable version of selected pages * Extract only text of selected pages * Save and restore selections on a specific namespace (use ACL's rights) == Example == Put at the ''wiki:ebook'' the syntax: ~~BOOK~~ And __after__ you mark at least one page for inclusion in the book, the bookmanager appears. {{https://trello.com/1/cards/644c13bd06a0c6737cae672f/attachments/644c1410e00d0916dfc21f6c/download/bookcreator_bookmanager.png?500&recache|BOOK}} ==== Initiate a book==== {{ https://trello.com/1/cards/644c13bd06a0c6737cae672f/attachments/644c1411072ca080378e5093/download/bookcreator_pagetoolsadd.png?150&recache|pagetools}} Use the //Add/Remove to book// link or button in your template to point a first page you like to add to a pdf book. The image on the left handside is the link as added automatically to the 'dokuwiki' template, see [[#installation]] instruction below for other templates. After selecting the first page, a toolbar appears on every page that let you add or remove additional pages. This toolbar refers also to the book manage tool. {{https://trello.com/1/cards/644c13bd06a0c6737cae672f/attachments/644c158811a19667595f946f/download/bookcreator_toolbar.png?500&recache|toolbar}} The book manage tool that you created above (default on ''wiki:ebook'') with ''~~BOOK~~'' let you reorder and exclude pages to your selection. Everybody who has access to the book manage tool can export selections to pdf, or show a print version. When you have enough (at least the "change") ACL permissions in the namespace where the selections are saved, you can also save and select these selections. ==== Show saved selections ==== Below the bookmanager is a listed displayed with saved selections. You can also display with ''~~ARCHIVEBOOK://number//&sort~~'' such a list of saved selections (books) anywhere into your wiki. * Available action: Load a saved selection into the bookmanager again * Optionally you can specify the number of selections to display and the order: * ''date'' -- Sort by saving date of selection * ''title'' -- Sort by Title of the selection * a //number// limits the number of displayed selections Default is 10 items ordered by date (last updated are sorted first). Each entry links also to the wiki page where their selection is saved. Per page only one list of saved selections is displayed. The user can only see selections when he has at least read access for the namespace ''wiki:ebook:'' (location configurable via config manager) or the pages in this namespace. Permissions for this namespace and the pages can be set as usual via the [[ACL|ACL manager]]. == Example == {{ https://trello.com/1/cards/644c13bd06a0c6737cae672f/attachments/644c140fcbe6cb0c49445a29/download/bookcreator_archivebook.png?170&recache|list}} Lists 5 selections, sorted by date ~~ARCHIVEBOOK:5&date~~ ==== Direct export a saved selection ==== To create a link, which initiates an export to respectively pdf, text, html or odt-file, you can use: (FIXME: ODT format have to receive the update yet, little patience please) ~~EXPORTPDF:Pagename of Saved selection~~ ~~EXPORTTEXT:pagename_of_saved_selection~~ ~~EXPORTHTML:pagename of saved selection~~ ~~EXPORTODT:saved selection~~ To change link title shown in wiki page: ~~EXPORTPDF:saved selection|A Titel that replaces default link title~~ Add url parameters to export url: ~~EXPORTPDF:saved selection&book_skipforbiddenpages=1~~ ~~EXPORTPDF:saved selection&book_skipforbiddenpages=1|Alternative title.pdf~~ ===== Installation ===== Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually. ==== 'dokuwiki' template ==== When you are using the default template of DokuWiki, the "Add/remove to book" link is automatically added via javascript. It will appear when the user has at least read access to the page of the bookmanager (default page is ''wiki:ebook''). ==== other templates ==== Other templates will probably not be supported that good yet. Please request at the issue tracker. ===== Changing the order of wiki pages ===== To change the order of wiki pages in your book, simply move the pages in the list. To do so, hover over the page title to move, click and drag it to the new location. Release the mouse button to finish moving the page to its new location. ===== Saving books ===== Format of stored book pages: when you save a book, it is stored in the format shown below. ====== MyBookName ====== * [[:first_pages]] * [[:second_page]] * [[:namespace:third_page]] * ..... * [[:last_page]] You can also manually create a book from scratch by using the same format. * Take care of prefixing of links by '':'' * To create a book from scratch, start a new page such as //wiki:ebook:mybookname// (default). The namespace can be changed at admin side configuration. ===== Configuration ===== Available configuration options. ^Name ^Description ^ |toolbar |Show toolbar: Never, when selection is not empty or always | |book_page |Wiki page where show your book manager. Put here the ''~~BOOK~~'' syntax. | |help_page |Wiki page with info and instructions | |save_namespace |Namespace where the book manager will save selections. | |skip_ids |Don't show tools if pageid contains one of these ids. | ==== Modifying the generated file ==== If you like to configure/modify the pdf or odt-file that is generated, you have to refer to the respectively the [[plugin:dw2pdf]] or [[plugin:odt]] plugin. The bookcreator plugin provides only the interface for creating a page selection that is submitting to these plugins for the file generation. ===== Version history ===== Recent changes: {{rss>https://github.com/Klap-in/dokuwiki-plugin-bookcreator/commits/master.atom date}} This plugin was the former Pdfbook Plugin. ===== Bug reports and feature requests ===== Please refer to the [[https://github.com/Klap-in/dokuwiki-plugin-bookcreator/issues|issue tracker]] for reporting issues. ===== FAQ ===== * This plugin is almost what I am looking for. Is there a way to add a title page / cover page? (I am using it with dw2pdf to also include a table of contents. I'd be fine with having a wiki page as "title page" before the TOC.)\\ **reaction**: the [[dw2pdf]] plugin, used by the bookcreator plugin for generation of the actual file, has option for adding a cover page. Please refer to [[dw2pdf]]