1# Latexport - A Latex export plugin
2A latex export renderer plugin to export latex documents from Dokuwiki.
3
4## User documentation
5For user documentation, visit the plugin home page:
6- https://www.dokuwiki.org/plugin:latexport
7
8## Installing a development version
9
10To develop extension to the plugin you need:
11
12- A development environment with PHP5 or higher.
13- A development version of dokuwiki and a configured web site.
14- PhpUnit installed as a PHAR in the path.
15- Checkout the dokuwiki-plugin-latexport in the corresponding plugin folder of dokuwiki.
16
17I'm assuming that you've got a working environment with *Apache* and *PHP* on your development machine. If not, you can check the [wiki](wiki).
18
19### Download development version of dokuwiki
20
21To retrieve the development version of dokuwiki you need to have git installed. Then follow
22instructions in https://www.dokuwiki.org/devel:git
23
24- Go to your development folder, checkout the development version and switch to the stable branch.
25
26```
27git clone https://github.com/splitbrain/dokuwiki.git
28git checkout stable
29```
30
31This should have created a dokuwiki folder with all sources, including a ``_test`` folder with unit tests.
32
33Complete the installation by visiting the ``install.php``:
34* http://localhost:8080/dokuwiki/install.php
35
36### Download development version of this plugin
37
38Go to the plugin folder, and checkout the source code for this plugin:
39
40```
41cd /path/to/dokuwiki/lib/plugins
42git clone https://github.com/jean-michel-gonet/dokuwiki-plugin-latexport.git latexport
43```
44
45Verify that the Latexport plugin is present by visiting
46* http://localhost:8080/dokuwiki/doku.php?do=admin&page=extension
47
48### Unit testing
49As this plugin has a quite complex behaviour, it is extensively tested with a
50PHPUnit test suite included with PHAR.
51
52NB: There are more recent version of those utilities, but they're not compatible
53with the base code of dokuwiki, which is still maintaining compatibility with PHP5.6.
54
55- Install PHPUnit from the PHAR - Visit https://phar.phpunit.de/ to check what
56is the latest version, and use or modify the following commands:
57
58```bash
59wget https://phar.phpunit.de/phpunit-5.7.27.phar
60chmod +x phpunit-5.phar
61mv phpunit-5.phar /usr/local/bin/phpunit
62```
63- Verify the installation:
64
65```bash
66phpunit --version
67PHPUnit 5.7.27 by Sebastian Bergmann and contributors.
68```
69
70- Install PHPAb from the PHAR -  Visit https://github.com/theseer/Autoload/releases to
71check for the latest release version, and use or modify the following commands:
72```bash
73wget https://github.com/theseer/Autoload/releases/download/1.25.9/phpab-1.24.1.phar
74chmod +x phpab-1.24.1.phar
75mv phpab-1.24.1.phar /usr/local/bin/phpab
76```
77- Verify the installation:
78
79```bash
80phpab --version
81phpab 1.25.9 - Copyright (C) 2009 - 2020 by Arne Blankerts and Contributors
82```
83
84Test commands:
85
86```bash
87cd /wherever/is/dokuwiki/_test
88phpunit --group plugin_latexport
89phpunit --group plugin_latexport --testdox
90```
91
92NB: You should be using PHP5.6 for these.
93
94## Adding the timezone configuration
95
96You may be required to add the timezone configuration. For this you need to
97edit the ``php.ini`` file, whose location depends on your distribution, your
98version of PHP, etc. Run the following command to locate it:
99
100```
101php --ini
102Configuration File (php.ini) Path: /usr/local/etc/php/5.6
103Loaded Configuration File:         /usr/local/etc/php/5.6/php.ini
104Scan for additional .ini files in: /usr/local/etc/php/5.6/conf.d
105```
106
107Edit the ``php.ini`` configuration file and add one of the supported time zones (see http://php.net/manual/en/timezones.php)
108by uncommenting the ``date.timezone`` entry:
109
110```
111[Date]
112; Defines the default timezone used by the date functions
113; http://php.net/date.timezone
114date.timezone = Europe/Paris
115```
116
117## The ``.htaccess`` file
118If you want your development version of dokuwiki to behave just as a production
119version, you probably need to add to the root dokuwiki folder the ``.htaccess``
120file that allows redirection (see https://www.dokuwiki.org/rewrite):
121
122```
123## Enable this to restrict editing to logged in users only
124
125## You should disable Indexes and MultiViews either here or in the
126## global config. Symlinks maybe needed for URL rewriting.
127#Options -Indexes -MultiViews +FollowSymLinks
128
129## make sure nobody gets the htaccess, README, COPYING or VERSION files
130<Files ~ "^([\._]ht|README$|VERSION$|COPYING$)">
131    <IfModule mod_authz_host>
132        Require all denied
133    </IfModule>
134    <IfModule !mod_authz_host>
135        Order allow,deny
136        Deny from all
137    </IfModule>
138</Files>
139
140## Don't allow access to git directories
141<IfModule alias_module>
142    RedirectMatch 404 /\.git
143</IfModule>
144
145## Uncomment these rules if you want to have nice URLs using
146## $conf['userewrite'] = 1 - not needed for rewrite mode 2
147RewriteEngine on
148
149RewriteRule ^_media/(.*)              lib/exe/fetch.php?media=$1  [QSA,L]
150RewriteRule ^_detail/(.*)             lib/exe/detail.php?media=$1  [QSA,L]
151RewriteRule ^_export/([^/]+)/(.*)     doku.php?do=export_$1&id=$2  [QSA,L]
152RewriteRule ^$                        doku.php  [L]
153RewriteCond %{REQUEST_FILENAME}       !-f
154RewriteCond %{REQUEST_FILENAME}       !-d
155RewriteRule (.*)                      doku.php?id=$1  [QSA,L]
156RewriteRule ^index.php$               doku.php
157
158## Not all installations will require the following line.  If you do,
159## change "/dokuwiki" to the path to your dokuwiki directory relative
160## to your document root.
161#RewriteBase /dokuwiki
162#
163## If you enable DokuWikis XML-RPC interface, you should consider to
164## restrict access to it over HTTPS only! Uncomment the following two
165## rules if your server setup allows HTTPS.
166#RewriteCond %{HTTPS} !=on
167#RewriteRule ^lib/exe/xmlrpc.php$      https://%{SERVER_NAME}%{REQUEST_URI} [L,R=301]
168```
169
170## Troubleshooting
171
172### The fearsome 0 bytes font file in Mac OS X
173(See www.dmertl.com/blog/?p=11 )
174(See https://en.wikipedia.org/wiki/Resource_fork )
175
176If `otfinfo` complains of the file being too small, check from the command line if the file has zero length:
177
178	MacBook-Pro:Fonts me$ otfinfo -i Playbill
179	otfinfo: Playbill: OTF file corrupted (too small)
180	MacBook-Pro:Fonts me$ ls -la Playbill
181	-rw-rw-r--@ 1 me       staff  0 Jun 15  2010 Playbill
182
183Zero length is visible only from command line. If you check the size from the Finder
184you see a non-zero size. Also you can tell that the file is not corrupt because you can open it in the Font Book.
185
186For some reason, lots of font files have their content hidden in metadata attributes. You can check if it's your
187case with the `xattr`command. There are two versions. The short one:
188
189```
190	MacBook-Pro:Fonts me$ xattr Playbill
191	com.apple.FinderInfo
192	com.apple.ResourceFork
193```
194
195And the long one:
196
197```
198	MacBook-Pro:Fonts me$ xattr -l Playbill
199	com.apple.FinderInfo:
200	00000000  46 46 49 4C 44 4D 4F 56 00 00 04 80 00 01 00 00  |FFILDMOV........|
201	00000010  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  |................|
202	00000020
203	com.apple.ResourceFork:
204	00000000  00 00 01 00 00 00 B8 2F 00 00 B7 2F 00 00 00 78  |......./.../...x|
205	00000010  .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. ..
206	00000050              [This is very long]
207	0000B880  .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. ..
208	0000B890  0B 03 AE CB 60 08 50 6C 61 79 62 69 6C 6C 08 50  |....`.Playbill.P|
209	0000B8A0  6C 61 79 62 69 6C 6C                             |laybill|
210	0000b8a7
211```
212
213You can see that `com.apple.ResourceFork` attribute contains the whole data. To extract the data as binary in a
214separated file, use `xattr` in conjunction with `xxd`, as demostrated below.
215
216	MacBook-Pro:Fonts me$ xattr -px com.apple.ResourceFork Playbill | xxd -r -p > Playbill.ttf
217
218If everything went right, you should have a second file with non-zero length:
219
220	MacBook-Pro:Fonts me$ ls -la Playbill*
221	-rw-rw-r--@ 1 me       staff      0 Jun 15  2010 Playbill
222	-rw-r--r--+ 1 me       staff  47271 Sep 17 09:36 Playbill.ttf
223
224Alas, although you can open this file in Font Book, if you _Validate Font_ it shows a _System Validation_ error. Also,
225`otfinfo` returns yet another error:
226
227	MacBook-Pro:Fonts me$ otfinfo -i Playbill.ttf
228	otfinfo: Playbill.ttf: not an OpenType font (bad magic number)
229
230To overcome this problem, I uploaded the TTF file to a online font converter (for example, https://onlinefontconverter.com/ ),
231and converted it into TTF (yes, same). Then:
2321. Download the result.
2332. Uninstall the original font.
2343. Install your converted font. If you processed a font file with multiple variations - like bold, italic - you will probably
235have one file per variation; in that case install them all.
2364. Check them with `otfinfo`.
237
238To me this worked.
239