Name |
Date |
Size |
#Lines |
LOC |
||
---|---|---|---|---|---|---|
.. | Today | - | ||||
conf/ | H | 03-May-2018 | - | 226 | 175 | |
help/ | H | 03-May-2018 | - | 40 | 38 | |
lang/ | H | 03-May-2018 | - | 176 | 59 | |
LICENSE.GPLv2 | H A D | 24-Oct-2013 | 17.7 KiB | 341 | 281 | |
Makefile | H A D | 24-Oct-2013 | 1.4 KiB | 43 | 16 | |
README.md | H A D | 24-Oct-2013 | 9.8 KiB | 203 | 142 | |
action.php | H A D | 24-Oct-2013 | 3.5 KiB | 100 | 45 | |
config.php | H A D | 24-Oct-2013 | 21.4 KiB | 666 | 452 | |
latex.php | H A D | 24-Oct-2013 | 49.5 KiB | 1,805 | 1,393 | |
plugin.info.txt | H A D | 24-Oct-2013 | 259 | 8 | 7 | |
renderer.php | H A D | 24-Oct-2013 | 3.2 KiB | 103 | 59 | |
syntax.php | H A D | 24-Oct-2013 | 3.6 KiB | 140 | 78 | |
texitrender.php | H A D | 24-Oct-2013 | 10.2 KiB | 325 | 207 |
README.md
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