1 |
<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [ |
2 |
|
3 |
<!-- |
4 |
|
5 |
This document is free software; you can redistribute it and/or |
6 |
modify it under the terms of the GNU General Public License |
7 |
as published by the Free Software Foundation; version 2 only |
8 |
of the License. |
9 |
|
10 |
This program is distributed in the hope that it will be useful, |
11 |
but WITHOUT ANY WARRANTY; without even the implied warranty of |
12 |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
13 |
GNU General Public License for more details. |
14 |
|
15 |
You should have received a copy of the GNU General Public License |
16 |
along with this document; if not, write to the Free Software |
17 |
Foundation, Inc., 51 Franklin Street, Fifth Floor, |
18 |
Boston, MA 02110-1301, USA. |
19 |
|
20 |
see the COPYING file included in the csv2latex package or |
21 |
http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt |
22 |
|
23 |
--> |
24 |
|
25 |
<!-- Process this file with docbook-to-man to generate an nroff manual |
26 |
page: `docbook-to-man manpage.sgml > manpage.1'. You may view |
27 |
the manual page with: `docbook-to-man manpage.sgml | nroff -man | |
28 |
less'. A typical entry in a Makefile or Makefile.am is: |
29 |
|
30 |
manpage.1: manpage.sgml |
31 |
docbook-to-man $< > $@ |
32 |
|
33 |
|
34 |
The docbook-to-man binary is found in the docbook-to-man package. |
35 |
Please remember that if you create the nroff version in one of the |
36 |
debian/rules file targets (such as build), you will need to include |
37 |
docbook-to-man in your Build-Depends control field. |
38 |
|
39 |
--> |
40 |
|
41 |
<!-- Fill in your name for FIRSTNAME and SURNAME. --> |
42 |
<!ENTITY dhfirstname "<firstname>BENOIT</firstname>"> |
43 |
<!ENTITY dhsurname "<surname>ROUITS</surname>"> |
44 |
<!-- Please adjust the date whenever revising the manpage. --> |
45 |
<!ENTITY dhdate "<date>january 24, 2009</date>"> |
46 |
<!-- SECTION should be 1-8, maybe w/ subsection other parameters are |
47 |
allowed: see man(7), man(1). --> |
48 |
<!ENTITY dhsection "<manvolnum>1</manvolnum>"> |
49 |
<!ENTITY dhemail "<email>brouits@free.fr</email>"> |
50 |
<!ENTITY dhusername "Benoit Rouits"> |
51 |
<!ENTITY dhucpackage "<refentrytitle>CSV2LATEX</refentrytitle>"> |
52 |
<!ENTITY dhpackage "csv2latex"> |
53 |
|
54 |
<!ENTITY ubuntu "<productname>Ubuntu</productname>"> |
55 |
<!ENTITY debian "<productname>Debian</productname>"> |
56 |
<!ENTITY gnu "<acronym>GNU</acronym>"> |
57 |
<!ENTITY gpl "&gnu; <acronym>GPL</acronym>"> |
58 |
]> |
59 |
|
60 |
<refentry> |
61 |
<refentryinfo> |
62 |
<address> |
63 |
&dhemail; |
64 |
</address> |
65 |
<author> |
66 |
&dhfirstname; |
67 |
&dhsurname; |
68 |
</author> |
69 |
<copyright> |
70 |
<year>2003</year> |
71 |
<holder>&dhusername;</holder> |
72 |
</copyright> |
73 |
&dhdate; |
74 |
</refentryinfo> |
75 |
<refmeta> |
76 |
&dhucpackage; |
77 |
|
78 |
&dhsection; |
79 |
</refmeta> |
80 |
<refnamediv> |
81 |
<refname>&dhpackage;</refname> |
82 |
|
83 |
<refpurpose>convert a csv file into a LaTeX document</refpurpose> |
84 |
</refnamediv> |
85 |
<refsynopsisdiv> |
86 |
<cmdsynopsis> |
87 |
<command>&dhpackage;</command> |
88 |
<arg><option>--nohead</option></arg> |
89 |
<arg><option>--longtable</option></arg> |
90 |
<arg><option>--noescape</option></arg> |
91 |
<arg><option>--guess</option></arg> |
92 |
<arg><option>--separator <replaceable>c</replaceable>|<replaceable>s</replaceable>|<replaceable>t</replaceable>|<replaceable>p</replaceable>|<replaceable>l</replaceable></option></arg> |
93 |
<arg><option>--block <replaceable>q</replaceable>|<replaceable>d</replaceable>|<replaceable>n</replaceable></option></arg> |
94 |
<arg><option>--lines <replaceable>#</replaceable></option></arg> |
95 |
<arg><option>--position <replaceable>l</replaceable>|<replaceable>c</replaceable>|<replaceable>r</replaceable></option></arg> |
96 |
<arg><option>--colorrows <replaceable>0-1</replaceable></option></arg> |
97 |
<arg><option>--reduce <replaceable>1</replaceable>|<replaceable>2</replaceable>|<replaceable>3</replaceable>|<replaceable>4</replaceable></option></arg> |
98 |
<arg><option>--repeatheader</option></arg> |
99 |
<arg><option>--nohlines</option></arg> |
100 |
<arg><option>--novlines</option></arg> |
101 |
<arg>file</arg> |
102 |
</cmdsynopsis> |
103 |
</refsynopsisdiv> |
104 |
<refsect1> |
105 |
<title>DESCRIPTION</title> |
106 |
|
107 |
<para>This manual page documents the <command>&dhpackage;</command> program.</para> |
108 |
<para><command>&dhpackage;</command> is a program that reads a "comma separated values" (csv) file |
109 |
and outputs a LaTeX file with one or more tabular environments to display |
110 |
the printable values of the csv file. The LaTeX code is flushed on the standard output. |
111 |
</para> |
112 |
|
113 |
<para>So-called "comma separated values" files are common formats for exchanging two-dimensinal |
114 |
tables between programs such as spreadsheets editors, to represent almost any kind of data. |
115 |
By default, a csv file is made of printable data separated by commas (`,'), each comma |
116 |
representing a `cell' separator, and each line representing a row. By extension, cell |
117 |
separators can be represented by tabs if the comma is considered as printable data. |
118 |
Moreover, some non true csv files can be assumed as two-dimensional tables as well. |
119 |
In some circumstances, if the printable data includes the cell separator of the |
120 |
exchange format, the latter can use a second extra character to embrace the printable |
121 |
data into a block (e.g: quoted text). Thus, it is still possible to parse the file by |
122 |
using the block delimiter (used twice to embrace the cell) instead of the separator. |
123 |
</para> |
124 |
<para><command>&dhpackage</command> aims to parse various csv formats plus formats that fits |
125 |
into the above definiton, assuming the data is text, and to produce a yet simple LaTeX file |
126 |
using the "tabular" environment for a table-style layout. |
127 |
Some options of output will also use macros provided by extra |
128 |
LaTeX packages that are commonly included in the main LaTeX distributions. |
129 |
</para> |
130 |
</refsect1> |
131 |
<refsect1> |
132 |
<title>OPTIONS</title> |
133 |
|
134 |
<para>This program follows the usual &gnu; command line syntax, |
135 |
with long options starting with two dashes (`-'). A summary of |
136 |
options is included below.</para> |
137 |
|
138 |
<variablelist> |
139 |
<varlistentry> |
140 |
<term><option>-h</option> |
141 |
<option>--help</option> |
142 |
</term> |
143 |
<listitem> |
144 |
<para>Show summary of options.</para> |
145 |
</listitem> |
146 |
</varlistentry> |
147 |
<varlistentry> |
148 |
<term><option>-v</option> |
149 |
<option>--version</option> |
150 |
</term> |
151 |
<listitem> |
152 |
<para>Show version of program.</para> |
153 |
</listitem> |
154 |
</varlistentry> |
155 |
<varlistentry> |
156 |
<term><option>-n</option> |
157 |
<option>--nohead</option> |
158 |
</term> |
159 |
<listitem> |
160 |
<para>Do not output the LaTeX document header. |
161 |
This is useful when the output is to be included as a separate file into the master document. |
162 |
</para> |
163 |
</listitem> |
164 |
</varlistentry> |
165 |
<varlistentry> |
166 |
<term><option>-t</option> |
167 |
<option>--longtable</option> |
168 |
</term> |
169 |
<listitem> |
170 |
<para>uses the 'longtable' package instead of the 'tabular' one. |
171 |
This is useful when the input is long, with <option>--lines 0</option> option. |
172 |
This option uses the extra `longtable' LaTeX package. |
173 |
If you also use <option>--nohead</option> option, do not forget to add |
174 |
the following line into the header of your master document: "\\usepackage{longtable}". |
175 |
</para> |
176 |
</listitem> |
177 |
</varlistentry> |
178 |
<varlistentry> |
179 |
<term><option>-x</option> |
180 |
<option>--noescape</option> |
181 |
</term> |
182 |
<listitem> |
183 |
<para>Do not escape TeX control characters from the input. |
184 |
This is useful when the input contains already TeX code. |
185 |
</para> |
186 |
</listitem> |
187 |
</varlistentry> |
188 |
<varlistentry> |
189 |
<term><option>-g</option> |
190 |
<option>--guess</option> |
191 |
</term> |
192 |
<listitem> |
193 |
<para>Try to guess the csv format. |
194 |
This is useful when the input is not strictly a comma separated set of printable data. |
195 |
For example, a line like %Foo, Bar%:%Wizz: Hey% may be parsed as "Foo, Bar" then "Wizz: Hey". |
196 |
</para> |
197 |
</listitem> |
198 |
</varlistentry> |
199 |
<varlistentry> |
200 |
<term><option>-s <replaceable>c</replaceable>|<replaceable>s</replaceable>|<replaceable>t</replaceable>|<replaceable>p</replaceable>|<replaceable>l</replaceable></option> |
201 |
<option>--separator <replaceable>c</replaceable>|<replaceable>s</replaceable>|<replaceable>t</replaceable>|<replaceable>p</replaceable>|<replaceable>l</replaceable></option> |
202 |
</term> |
203 |
<listitem> |
204 |
<para>Set the given separator as cell separator of the csv format. |
205 |
`c' means a comma (default). |
206 |
`s' means a semicolon. |
207 |
`t' means a tab. |
208 |
`p' means a space. |
209 |
`l' means a colon. |
210 |
</para> |
211 |
</listitem> |
212 |
</varlistentry> |
213 |
<varlistentry> |
214 |
<term><option>-b <replaceable>q</replaceable>|<replaceable>d</replaceable>|<replaceable>n</replaceable></option> |
215 |
<option>--block <replaceable>q</replaceable>|<replaceable>d</replaceable>|<replaceable>n</replaceable></option> |
216 |
</term> |
217 |
<listitem> |
218 |
<para>Set the given block delimiter that embraces the printable data of the csv format. |
219 |
`q' means a simple quote. |
220 |
`d' means a double quote. |
221 |
`n' means no quoting at all (default). |
222 |
</para> |
223 |
</listitem> |
224 |
</varlistentry> |
225 |
<varlistentry> |
226 |
<term><option>-l <replaceable>#</replaceable></option> |
227 |
<option>--lines <replaceable>#</replaceable></option> |
228 |
</term> |
229 |
<listitem> |
230 |
<para>Force to output multiple tabulars, each having a limited number of lines. |
231 |
The given argument must be a POSITIVE INTEGER VALUE. This is useful when |
232 |
the number of input rows is too big to fit into a single papersheet. |
233 |
A good average for a4 paper is about 40 lines (default). 0 means infinity |
234 |
(actualy about 2 Giga lines). |
235 |
</para> |
236 |
</listitem> |
237 |
</varlistentry> |
238 |
<varlistentry> |
239 |
<term><option>-p <replaceable>l</replaceable>|<replaceable>c</replaceable>|<replaceable>r</replaceable></option> |
240 |
<option>--position <replaceable>l</replaceable>|<replaceable>c</replaceable>|<replaceable>r</replaceable></option> |
241 |
</term> |
242 |
<listitem> |
243 |
<para>Set the text position in all cells at once. |
244 |
This simply uses one of the three basic cell formating options of the LaTeX tabular environment. |
245 |
`l' means left-aligned (default). |
246 |
`c' means centered. |
247 |
`r' means right-aligned. |
248 |
</para> |
249 |
</listitem> |
250 |
</varlistentry> |
251 |
<varlistentry> |
252 |
<term><option>-c <replaceable>0-1</replaceable></option> |
253 |
<option>--colorrows <replaceable>0-1</replaceable></option> |
254 |
</term> |
255 |
<listitem> |
256 |
<para>Alternate white/gray rows on the LaTeX output, having the given graylevel. |
257 |
The given argument must be a REAL NUMBER BETWEEN 0 AND 1. |
258 |
0 means black while 1 means white. |
259 |
A nice looking value is 0.75 when printed on white paper. |
260 |
This option uses the extra `colortbl' LaTeX package. |
261 |
If you also use <option>--nohead</option> option, do not forget to add |
262 |
the following line into the header of your master document: "\\usepackage{colortbl}". |
263 |
</para> |
264 |
</listitem> |
265 |
</varlistentry> |
266 |
<varlistentry> |
267 |
<term><option>-r <replaceable>1</replaceable>|<replaceable>2</replaceable>|<replaceable>3</replaceable>|<replaceable>4</replaceable></option> |
268 |
<option>--reduce <replaceable>1</replaceable>|<replaceable>2</replaceable>|<replaceable>3</replaceable>|<replaceable>4</replaceable></option> |
269 |
</term> |
270 |
<listitem> |
271 |
<para>Reduce the size of the tabular and the font in the LaTeX output, given a reduction level. |
272 |
The given argument must be one of 1, 2, 3 or 4. |
273 |
The more the level is high, the more the tabular will appear small. |
274 |
This is useful to shrink the table width when the printable data is made of very long text. |
275 |
This option uses the extra `relsize' LaTeX package. |
276 |
If you also use <option>--nohead</option> option, do not forget to add |
277 |
the following line into the header of your master document: "\\usepackage{relsize}". |
278 |
</para> |
279 |
</listitem> |
280 |
</varlistentry> |
281 |
<varlistentry> |
282 |
<term><option>-z</option> |
283 |
<option>--nohlines</option> |
284 |
</term> |
285 |
<listitem> |
286 |
<para>Do not output horizontal lines in the table(s). |
287 |
</para> |
288 |
</listitem> |
289 |
</varlistentry> |
290 |
<varlistentry> |
291 |
<term><option>-y</option> |
292 |
<option>--novlines</option> |
293 |
</term> |
294 |
<listitem> |
295 |
<para>Do not output vertical lines in the table(s). |
296 |
</para> |
297 |
</listitem> |
298 |
</varlistentry> |
299 |
<varlistentry> |
300 |
<term><option>-e</option> |
301 |
<option>--repeatheader</option> |
302 |
</term> |
303 |
<listitem> |
304 |
<para>Repeat the first row of the first table in every table. |
305 |
This is useful when the output is very long and separated in |
306 |
multiple tables. |
307 |
</para> |
308 |
</listitem> |
309 |
</varlistentry> |
310 |
</variablelist> |
311 |
</refsect1> |
312 |
<refsect1> |
313 |
|
314 |
<title>EXAMPLES</title> |
315 |
|
316 |
<para>Create a PDF document with small text, alternate gray rows, 80 lines per table, |
317 |
from a guessed csv format of the january stats that my boss created with his |
318 |
super point-and-click spreadsheet program (which could not generate a PDF output!). |
319 |
</para> |
320 |
<para> |
321 |
<command>&dhpackage; --guess --lines 80 --colorrows 0.75 --reduce 2 january_stats.csv > january_stats.tex && pdflatex january_stats.tex</command> |
322 |
</para> |
323 |
|
324 |
<para>Quickly preview a phonebook from a file formated as "Surname" "Name" "Phone" "Cellular": |
325 |
</para> |
326 |
<para> |
327 |
<command>&dhpackage; -s p -b d -l 42 phonebook-sorted.txt | latex</command> |
328 |
</para> |
329 |
|
330 |
</refsect1> |
331 |
<refsect1> |
332 |
|
333 |
<title>SEE ALSO</title> |
334 |
|
335 |
<para>tex (1), latex (1).</para> |
336 |
|
337 |
</refsect1> |
338 |
</refentry> |
339 |
|
340 |
<!-- Keep this comment at the end of the file |
341 |
Local variables: |
342 |
mode: sgml |
343 |
sgml-omittag:t |
344 |
sgml-shorttag:t |
345 |
sgml-minimize-attributes:nil |
346 |
sgml-always-quote-attributes:t |
347 |
sgml-indent-step:2 |
348 |
sgml-indent-data:t |
349 |
sgml-parent-document:nil |
350 |
sgml-default-dtd-file:nil |
351 |
sgml-exposed-tags:nil |
352 |
sgml-local-catalogs:nil |
353 |
sgml-local-ecat-files:nil |
354 |
End: |
355 |
--> |
356 |
|
357 |
|