Pharmtex Quick Guide Date Issued: 15 JAN 2019 Version: 1.2 Author: Christian Hove Rasmussen Contact: [email protected] Website
Total Page:16
File Type:pdf, Size:1020Kb
PharmTeX Quick Guide Version 1.2 Quick Guide Report Title: PharmTeX Quick Guide Date Issued: 15 JAN 2019 Version: 1.2 Author: Christian Hove Rasmussen Contact: [email protected] Website: http://pharmtex.org PHARMTEX QUICK GUIDE Page 1 of 6 PharmTeX Quick Guide Version 1.2 1. INTRODUCTION PharmTeX is an open-source framework for creating publishing-ready reports directly from figure and table files. The framework is based on LaTeX, the gold standard for typesetting scientific documents. PharmTeX is released under the GNU Affero General Public License Version 3 (AGPLv3). This user guide has the objective of giving you as a PharmTeX user the ability to: • Set up PharmTeX on your computer. • Initialize a report. • Use PharmTeX features to put in various key report components. • Finalize a report to make it ready for publishing. 2. SETTING UP PHARMTEX In this guide, we will assume that you are using the PharmTeX software bundles. They are available on pharmtex.org under Downloads. Currently, versions for Windows and Linux are available. Please download the one suitable for your operating system. Once the ZIP file is downloaded, double-click it to open it and drag-and-drop the "pharmtex" folder within to C:\Users\USERNAME on Windows 10 and /home/USERNAME on Linux (takes about 15 min to extract). When you are done, the location and contents on Windows 10 should be as shown in Figure 1, with USERNAME matching your Windows login name: Figure 1. PharmTeX software bundle location PharmTeX software bundle location. Once the bundle is in place, please download the example document ZIP file from pharmtex.org (located under Downloads). Double-click the ZIP file and drag-and-drop the "example" folder to any location on your computer, e.g. in your "Documents" folder. PHARMTEX QUICK GUIDE Page 2 of 6 PharmTeX Quick Guide Version 1.2 Inside the "example" folder you will see the files in Table 1: Table 1. Typical files in a report folder File Type Description document.tex Main report file This is where you write your report – the filename can be modified if you want to. document.log The log file Show the results of the compilation process. executex Linux start file Double-click this file in Linux to start up PharmTeX. You may delete it if you are running Windows. executex.bat Windows start file Double-click this file in Windows to start up PharmTeX. You may delete it if you are running Linux. glossary.tex Global glossary Contains global glossary definitions provided by the PharmTeX creators. PharmTeX.cls PharmTeX class file Holds all the settings for a PharmTeX document. It is also where the formatting of a document is defined. PharmTeX.ini PharmteX ini file This file is associated with the class file. It is used to improve the compilation performance. PharmTeX.sty PharmTeX package file Holds the Perl features of PharmTeX. It is a series of Perl functions that work together with the class file. pmx.bst Reference list formatting file Reference list formatting file provided by the PharmTeX developers. Defines how citations are printed. references.bib Reference database file Holds the list of references to cite in PharmTeX. Is maintained using JabRef. runlatex.pl Perl start script Either executex (Linux) or executex.bat (Windows) will use this file to run PharmTeX. Item ID omitted, Artifact ID omitted. Typical files in a report folder. All other files in a PharmTeX document folder will be files that you add, e.g. figures, tables, etc. Next, we will test the example report. Inside the "example" folder, double-click the "executex.bat" file if you are running Windows. Viewing of file extensions may be disabled on your computer, in which case you simply try both files named "executex" and see which ones executes (only the BAT file will work correctly). You may get the warning "Windows protected your PC", in which case you have to select "Run anyway" (only the first time you run PharmTeX on the computer). On Linux, double-click the "executex" file (no file extension) or start it in a terminal using "./executex". It will open a terminal windows that will prompt you for the name of the document you want to edit. Write "document" as in the name of the main report file and press enter. You do not need to enter the extension ".tex". This will open up Texstudio and the "document.tex" file. This has to be done every time when opening a PharmTeX document. Do not double-click the TEX file to open it as PharmTeX will not initialize correctly. Once the document is open in Texstudio, press F1 (you may need to enable Fn-Lock/FnLk on your keyboard (Fn+FnLk) to gain access to the F-keys) on your keyboard and you will see it says "Process started" in the bottom left window of Texstudio. Once done, Texstudio will take you to the place in the PDF document (right window in Figure 2) that corresponds to the point in the source code (left window in Figure 2). You can also go from source to PDF by pressing F3. If you press the "Ctrl" button on your keyboard and PHARMTEX QUICK GUIDE Page 3 of 6 PharmTeX Quick Guide Version 1.2 left-click in the PDF window (right), Texstudio will take you to the same place in the source code (left). Any compilation errors will show up in the box below the source window. Make sure to check the "Log" pane in the box below the source for any warnings. PHARMTEX QUICK GUIDE Page 4 of 6 PharmTeX Quick Guide Version 1.2 Figure 2. Screenshot of Texstudio Screenshot of Texstudio. PHARMTEX QUICK GUIDE Page 5 of 6 PharmTeX Quick Guide Version 1.2 3. WORKING ON A DOCUMENT When creating a new PharmTeX report, it is recommended to always start from a template. A standard blank report with some default sections is available in the download file "template.zip" on pharmtex.org under "Downloads". This can be used as your starting point for a new report. Contemplating Figure 2, Texstudio consists of a source window where you write your report text (left/middle) and an output window where you can see the compiled PDF file (right). The window to the very left show the structure of the document, i.e. which sections etc. are present. If you press the little symbols on the far left, the left window will show different menus with shortcuts to various mathematical symbols. These symbols can be used in mathematical environments which are covered in the PharmTeX User Guide (pharmtex.org under "Tutorials"). Use the F-keys for the following functionality: Table 2. Texstudio F-key functionality Key Function Description F1 Full compile Performs a full compilation to ensure that all page numbers, cross references, citations, hyperlinks, etc. are working properly. F2 Fast compile Use this key to compile minor changes, i.e. most just added plain text or check your code for errors. Page numbers etc. may not be accurate until F1 is used. F3 View PDF Placing the cursor somewhere in the source window and pressing F3 will take you the approximate corresponding place in the PDF file. F4 Clear files Deletes all temporary files created by PharmTeX, essentially allowing you to start over. It will not delete your figure, table and other files you have manually added. F5 Start JabReF Starts up an instance of JabRef. It will also open any BibTeX database(s) you have in the report folder. F6 Detach from Perl Compiles all the Perl code used for the report. The resulting folder can be compiled without Perl, but the report should not be modified from this point on. Useful e.g. for external QC when no Perl is available. F7 Recompile Class Recompiles the class file (PharmTeX.cls). Used if you choose to modify the class file (not recommended) and want to see the results. F12 Finalize report Does a full compile and applies the submission-ready components of PharmTeX. Once done, all temporary files will be cleared. Item ID omitted, Artifact ID omitted. Texstudio F-key functionality. Note that F6 and F7 are advanced/developer tools that should not be used unless you have a specific reason for doing so. Until finalization, the watermark "Draft" will appear and all hyperlinks will show. Upon finalization, hyperlinks to the same page and external hyperlinks are disabled to comply with the PharmTeX submission-ready standards. If the document has not been finalized, cross references and page numbers may be inaccurate, so please use the F12 key before issuing the report. Note that compiling using F1 will also produce correct cross refrences and page numbers, but F12 is required for the document to be submission-ready. PHARMTEX QUICK GUIDE Page 6 of 6.