1##TeXit plugin for Dokuwiki
2
3This is a cloned repository of the [Dokuwiki TeXit plugin], the original website
4was http://danjer.doudouke.org/tech/dokutexit, but the original author has
5disapeared, as well as the whole doudouke.org domain (on which he had his mail
6address).
7
8### Changes
9
10This version comes with a set of updates and changes:
11 * name is now texit instead of dokutexit
12 * code refactoring, simplifying and cleaning
13 * documentation
14 * integration with [nsbpc], simplification of configuration files
15 * update of TeX template, LuaTeX and XeTeX integration
16 * use of latexmk instead of manual compilation (thus working with BibTeX, indexes, etc.)
17 * produced pdf and zip are now in the media namespace
18 * possibility to export a whole namespace
19 * less fancy exports (no ugly background link)
20 * integration with [refnotes] for bibliography (only BibTeX entries)
21 * removing complex administration interface
22 * remove zip functions from outer space, using zlib instead
23
24### Configuration
25
26Configuration is organized this way:
27
28##### Usual plugin config
29
30 * *conf/defaults.php* (or the configuration manager) holds the global configuration, where you can choose several things, such as the default renderer (LaTeX+dvipdf, pdfLaTeX, XeLaTeX or LuaLaTeX)
31 * *conf/header-namespace.tex* is the header which will be included when a whole namespace will be exported
32 * *conf/header-page.tex* is the same for one page export
33 * *conf/commands.tex* is where the TeX macros for dokuwiki styles will be held (this is common for namespace and page)
34 * *conf/footer.tex*, if present, will be inserted before `\end{document}`, useful to insert table of contents or bibliographies.
35
36##### NSBPC plugin config
37
38You can use [nsbpc] to have per-namespace (and thus per-language) configuration. The configuration pages will be:
39 * *nsbpc_texit-namespace* overriding *conf/header-namespace.tex*
40 * *nsbpc_texit-page* overriding *conf/header-page.tex*
41 * *nsbpc_texit-commands* overriding *conf/commands.tex*
42 * *nsbpc_texit-footer* overriding *conf/footer.tex*
43
44##### BibTeX config
45
46If it exists, TeXit will handle the file *texit.bib* in the *conf/* directory of the plugin.
47
48If you use [refnotes], TeXit will merge all BibTeX code from refnotes into a *texit.bib* in the namespace of the refnotes database pages (config option `reference-db-enable`).
49
50If you want to insert the bibliography, please use the `\dokubibliography` (defined in *commands.tex*) macro in your header or footer, it will call the good filename -- just it case this one (*texit.bib*) changes.
51
52### Output files
53
54When clicking on the export button, the plugin will compute an .pdf file containing the produced PDF. The output for page *namespace:subnamespace:id* will be named *namespace:subnamespace:id.pdf* and will automaticall be plae in *media:namespace:subnamespace*.
55
56The intermediate .tex files will be placed in the *texit:namespace:subnamespace* namespace. Suppose you have the following pages:
57
58 * *namespace:subnamespace:page1*
59 * *namespace:subnamespace:page2*
60
61, if you generate all files, the *media:namespace:subnamespace* namespace will contain:
62
63 * *page1.pdf*
64 * *page1-tex.zip*, a zip file containing page1.pdf and the necessary tex files to compile it (see herebelow for the structure)
65 * *page2.pdf*
66 * *page2-tex.zip*
67 * *all.pdf*, pdf containing page1 and page2 (the whole namespace)
68 * *all-tex.zip*
69
70The *texit:namespace:subnamespace* namespace will contain:
71
72 * *commands.tex* : a copy of the corresponding file
73 * *texit.bib* : the bibliography database (not mandatory)
74 * *footer.tex* : the footer (not mandatory)
75 * *page1-content.tex* : the translation content of the *page1* page in TeX (no header, not a complete tex file)
76 * *page2-content.tex* : idem for page2
77 * *page1.tex* : an adptation of *header-page.tex* for *page1.pdf*, `\include`ing the following tex files:
78  * *commands.tex*
79  * *page1-content.tex*
80 * *page2.tex* : idem for page2
81 * *all.tex* : an adaptation of *header-namespace.tex* for *all.pdf*, `\include`ing the following tex files:
82  * *commands.tex*
83  * *page1-content.tex*
84  * *page2-content.tex*
85
86The structure of the *.zip* files in *media:namespace:subnamespace* is the following one (if we take *all-tex.zip*):
87
88 * *all.pdf*
89 * *all.tex*
90 * *commands.tex*
91 * *page1-content.tex*
92 * *page2-content.tex*
93 * *texit.bib* (if relevant)
94 * *footer.tex* (if exists)
95
96All filenames will have characters \_ escaped as \- for good TeX integration. This means that bad things may happen if you have *foo\-bar* and *foo\_bar* in the same namespace.
97
98When the user asks the pdf, intermediate TeX files will be produced only if the page has changed. As the compilation is done with latexmk, no unnecessary recompilation will happen if the page (or all pages in the namespace) haven't changed.
99
100Optionnaly, a prefix may be prepended to PDF filename. It is `$prefix,namespace,subnamespace,` (see configuration manager for options about this). This is useful if you want people to download files with explicit filenames referencing your wiki.
101
102### Warning for server saturation
103
104Robots will follow every link, which means that they will generate all pdfs for all pages and namespaces when they'll reference your website. This can lead to server saturation and crash!
105
106To prevent robots from following the links to PDF export, add a `robots.txt` in the root namespace of your wiki, reading
107
108```
109User-agent: *
110Disallow: /*texit*
111```
112
113(untested yet).
114
115### CMK integration
116
117Note that you can define custom markups with [cmk] (see the README file of cmk).
118
119### Refnotes integration
120
121You can use texit with refnotes, with the following limitations:
122  * only BibTeX configurations in database files will be taken into account
123  * ref namespaces won't work at all, you should put everything in the root namespace
124
125### Documentation
126
127There is a documentation in help/, but it seems Dokuwiki doesn't allow plugins
128to install docs, so you'll have to install it by yourself (you can, for
129instance, follow the link in the administration page). What seems to me as
130the most elegant solution is to create your help pages in the
131manual:pluginsmanual namespace and to add
132
133    ====== Plugins ======
134
135    {{nstoc :fr:wiki:pluginsmanual 2}}
136
137in *manual/start*. Feel free to do otherwise.
138
139### Nice sidebar buttons
140
141Sidebar buttons are really painful to add! The normal way would be to add your images in `lib/tpl/<yourtemplate>/images/pagetools` and to call `lib/tpl/<yourtemplate>/images/pagetools-build.php`. The problem is that this script uses the `imagelayereffect()` php function from php-[gd]. This library has [human issues][gdpb], and Debian doesn't ship a php-gd library with this function (see [here][gdpbdeb]). So if you have a Debian server, the only way to make it work is to either hack your gd library, or do what the `pagetools-build.php` does by hand.
142
143If you do it by hand, basically you have to merge images from the `pagetools` directory (coming from the [retina icon set][retina]) in the `lib/tpl/<yourtemplate>/images/pagetools-sprite.png`. To do so, first duplicate them, with one version in grey and the other in blue, and apply them a gradiant. Then stack them vertically, each 45px, in the `pagetools-sprite.png`.
144
145Once you have a good `pagetools-sprite.png`, then you can change your template this way:
146
147##### actions
148
149All these buttons will be associated with actions, and thus with [action plugins][actionplugins]. If you just want to test the button adding, before developping your action plugin, you can put some dumb values (that you'll have to remove later). To do so, you can follow the instructions on [pdfexport plugin doc][pdfexport], section *Dokuwiki-template: Export Link in Pagetools*.
150
151##### css
152
153Add this at the end of `lib/tpl/<yourtemplate>/css/pagetools.css`:
154
155```css
156#dokuwiki__pagetools ul li a.<myaction> {
157    background-position: right -1090px;
158}
159#dokuwiki__pagetools ul li a.<myaction>:before {
160    margin-top: -1090px;
161}
162#dokuwiki__pagetools ul li a.<myaction>:hover,
163#dokuwiki__pagetools ul li a.<myaction>:active,
164#dokuwiki__pagetools ul li a.<myaction>:focus {
165    background-position: right -1135px;
166}
167```
168
169replacing `<myaction>` by the name of your action. Add it for each button you want in the pagetools bar, adding each time 45px to the values.
170
171### License
172
173The plugin seems to be under GPLv2+ license, which I'll assume.
174
175### Requirements
176
177The plugin supposes you have a recent TeXLive installation (it assumes 2013, but
178it should have almost no problem with 2012 version or with MikTeX), with
179latexmk.
180
181Not that you need to install imagemagick for image conversion.
182
183You need to be able to use zip functions in php (on Debian, install `libphp-pclzip` package).
184
185It has only been tested on a recent dokuwiki (Release 2013-05-10a "Weatherwax").
186
187### Limitations and TODO
188
189  * Cache is not well handled yet: if you change the configuration of a page without changing page content, you'll need to clean the cache, otherwise output will still be the old version (see following point).
190  * When ready, use [nsbpc] function for cache (see TODO section of nsbpc's README and  [Dokuwiki documentation][cache]).
191  * When used with CMK, if a .tex file is already compiled and cmk configuration changes, TeXit has currently no way to know it has te recompile. I believe CMK should put some infos about file dependencies in the medata of the page (it's possible, see link in previous point)
192
193[Dokuwiki TeXit plugin]: https://www.dokuwiki.org/plugin:dokutexit
194[nsbpc]: https://github.com/eroux/dokuwiki-plugin-nsbpc
195[gd]: http://en.wikipedia.org/wiki/GD_Graphics_Library
196[gdpbdeb]: https://bugs.launchpad.net/ubuntu/+source/php5/+bug/74647
197[retina]: http://blog.twg.ca/2010/11/retina-display-icon-set/
198[actionplugins]: https://www.dokuwiki.org/devel:action_plugins
199[pdfexport]: https://www.dokuwiki.org/tips:pdfexport#dokuwiki-templateexport_link_in_pagetools
200[refnotes]: https://www.dokuwiki.org/plugin:refnotes
201[cmk]: https://github.com/eroux/dokuwiki-plugin-cmk
202[cache]:https://www.dokuwiki.org/devel:caching#plugins
203