You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
386 lines
16 KiB
386 lines
16 KiB
<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [ |
|
|
|
<!-- |
|
|
|
This document is free software; you can redistribute it and/or |
|
modify it under the terms of the GNU General Public License |
|
as published by the Free Software Foundation; version 2 only |
|
of the License. |
|
|
|
This program is distributed in the hope that it will be useful, |
|
but WITHOUT ANY WARRANTY; without even the implied warranty of |
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
|
GNU General Public License for more details. |
|
|
|
You should have received a copy of the GNU General Public License |
|
along with this document; if not, write to the Free Software |
|
Foundation, Inc., 51 Franklin Street, Fifth Floor, |
|
Boston, MA 02110-1301, USA. |
|
|
|
see the LICENSE file included in the csv2latex package or |
|
http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt |
|
|
|
--> |
|
|
|
<!-- Process this file with docbook-to-man to generate an nroff manual |
|
page: `docbook-to-man manpage.sgml > manpage.1'. You may view |
|
the manual page with: `docbook-to-man manpage.sgml | nroff -man | |
|
less'. A typical entry in a Makefile or Makefile.am is: |
|
|
|
manpage.1: manpage.sgml |
|
docbook-to-man $< > $@ |
|
|
|
|
|
The docbook-to-man binary is found in the docbook-to-man package. |
|
Please remember that if you create the nroff version in one of the |
|
debian/rules file targets (such as build), you will need to include |
|
docbook-to-man in your Build-Depends control field. |
|
|
|
--> |
|
|
|
<!-- Fill in your name for FIRSTNAME and SURNAME. --> |
|
<!ENTITY dhfirstname "<firstname>BENOIT</firstname>"> |
|
<!ENTITY dhsurname "<surname>ROUITS</surname>"> |
|
<!-- Please adjust the date whenever revising the manpage. --> |
|
<!ENTITY dhdate "<date>january 24, 2009</date>"> |
|
<!-- SECTION should be 1-8, maybe w/ subsection other parameters are |
|
allowed: see man(7), man(1). --> |
|
<!ENTITY dhsection "<manvolnum>1</manvolnum>"> |
|
<!ENTITY dhemail "<email>brouits@free.fr</email>"> |
|
<!ENTITY dhusername "Benoit Rouits"> |
|
<!ENTITY dhucpackage "<refentrytitle>CSV2LATEX</refentrytitle>"> |
|
<!ENTITY dhpackage "csv2latex"> |
|
|
|
<!ENTITY ubuntu "<productname>Ubuntu</productname>"> |
|
<!ENTITY debian "<productname>Debian</productname>"> |
|
<!ENTITY gnu "<acronym>GNU</acronym>"> |
|
<!ENTITY gpl "&gnu; <acronym>GPL</acronym>"> |
|
]> |
|
|
|
<refentry> |
|
<refentryinfo> |
|
<address> |
|
&dhemail; |
|
</address> |
|
<author> |
|
&dhfirstname; |
|
&dhsurname; |
|
</author> |
|
<copyright> |
|
<year>2003</year> |
|
<holder>&dhusername;</holder> |
|
</copyright> |
|
&dhdate; |
|
</refentryinfo> |
|
<refmeta> |
|
&dhucpackage; |
|
|
|
&dhsection; |
|
</refmeta> |
|
<refnamediv> |
|
<refname>&dhpackage;</refname> |
|
|
|
<refpurpose>convert a csv file into a LaTeX document</refpurpose> |
|
</refnamediv> |
|
<refsynopsisdiv> |
|
<cmdsynopsis> |
|
<command>&dhpackage;</command> |
|
<arg><option>--nohead</option></arg> |
|
<arg><option>--longtable</option></arg> |
|
<arg><option>--noescape</option></arg> |
|
<arg><option>--guess</option></arg> |
|
<arg><option>--separator <replaceable>c</replaceable>|<replaceable>s</replaceable>|<replaceable>t</replaceable>|<replaceable>p</replaceable>|<replaceable>l</replaceable></option></arg> |
|
<arg><option>--block <replaceable>q</replaceable>|<replaceable>d</replaceable>|<replaceable>n</replaceable></option></arg> |
|
<arg><option>--lines <replaceable>#</replaceable></option></arg> |
|
<arg><option>--position <replaceable>l</replaceable>|<replaceable>c</replaceable>|<replaceable>r</replaceable></option></arg> |
|
<arg><option>--colorrows <replaceable>0-1</replaceable></option></arg> |
|
<arg><option>--reduce <replaceable>1</replaceable>|<replaceable>2</replaceable>|<replaceable>3</replaceable>|<replaceable>4</replaceable></option></arg> |
|
<arg><option>--repeatheader</option></arg> |
|
<arg><option>--nohlines</option></arg> |
|
<arg><option>--novlines</option></arg> |
|
<arg><option>--landscape</option></arg> |
|
<arg><option>--font <replaceable>#</replaceable></option></arg> |
|
<arg>file</arg> |
|
</cmdsynopsis> |
|
</refsynopsisdiv> |
|
<refsect1> |
|
<title>DESCRIPTION</title> |
|
|
|
<para>This manual page documents the <command>&dhpackage;</command> program.</para> |
|
<para><command>&dhpackage;</command> is a program that reads a "comma separated values" (csv) file |
|
and outputs a LaTeX file with one or more tabular environments to display |
|
the printable values of the csv file. The LaTeX code is flushed on the standard output. |
|
</para> |
|
|
|
<para>So-called "comma separated values" files are common formats for exchanging two-dimensinal |
|
tables between programs such as spreadsheets editors, to represent almost any kind of data. |
|
By default, a csv file is made of printable data separated by commas (`,'), each comma |
|
representing a `cell' separator, and each line representing a row. By extension, cell |
|
separators can be represented by tabs if the comma is considered as printable data. |
|
Moreover, some non true csv files can be assumed as two-dimensional tables as well. |
|
In some circumstances, if the printable data includes the cell separator of the |
|
exchange format, the latter can use a second extra character to embrace the printable |
|
data into a block (e.g: quoted text). Thus, it is still possible to parse the file by |
|
using the block delimiter (used twice to embrace the cell) instead of the separator. |
|
</para> |
|
<para><command>&dhpackage</command> aims to parse various csv formats plus formats that fits |
|
into the above definiton, assuming the data is text, and to produce a yet simple LaTeX file |
|
using the "tabular" environment for a table-style layout. |
|
Some options of output will also use macros provided by extra |
|
LaTeX packages that are commonly included in the main LaTeX distributions. |
|
</para> |
|
</refsect1> |
|
<refsect1> |
|
<title>OPTIONS</title> |
|
|
|
<para>This program follows the usual &gnu; command line syntax, |
|
with long options starting with two dashes (`-'). A summary of |
|
options is included below.</para> |
|
|
|
<variablelist> |
|
<varlistentry> |
|
<term><option>-h</option> |
|
<option>--help</option> |
|
</term> |
|
<listitem> |
|
<para>Show summary of options.</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term><option>-v</option> |
|
<option>--version</option> |
|
</term> |
|
<listitem> |
|
<para>Show version of program.</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term><option>-n</option> |
|
<option>--nohead</option> |
|
</term> |
|
<listitem> |
|
<para>Do not output the LaTeX document header. |
|
This is useful when the output is to be included as a separate file into the master document. |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term><option>-t</option> |
|
<option>--longtable</option> |
|
</term> |
|
<listitem> |
|
<para>uses the 'longtable' package instead of the 'tabular' one. |
|
This is useful when the input is long, with <option>--lines 0</option> option. |
|
This option uses the extra `longtable' LaTeX package. |
|
If you also use <option>--nohead</option> option, do not forget to add |
|
the following line into the header of your master document: "\\usepackage{longtable}". |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term><option>-x</option> |
|
<option>--noescape</option> |
|
</term> |
|
<listitem> |
|
<para>Do not escape TeX control characters from the input. |
|
This is useful when the input contains already TeX code. |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term><option>-g</option> |
|
<option>--guess</option> |
|
</term> |
|
<listitem> |
|
<para>Try to guess the csv format. |
|
This is useful when the input is not strictly a comma separated set of printable data. |
|
For example, a line like %Foo, Bar%:%Wizz: Hey% may be parsed as "Foo, Bar" then "Wizz: Hey". |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term><option>-s <replaceable>c</replaceable>|<replaceable>s</replaceable>|<replaceable>t</replaceable>|<replaceable>p</replaceable>|<replaceable>l</replaceable></option> |
|
<option>--separator <replaceable>c</replaceable>|<replaceable>s</replaceable>|<replaceable>t</replaceable>|<replaceable>p</replaceable>|<replaceable>l</replaceable></option> |
|
</term> |
|
<listitem> |
|
<para>Set the given separator as cell separator of the csv format. |
|
`c' means a comma (default). |
|
`s' means a semicolon. |
|
`t' means a tab. |
|
`p' means a space. |
|
`l' means a colon. |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term><option>-b <replaceable>q</replaceable>|<replaceable>d</replaceable>|<replaceable>n</replaceable></option> |
|
<option>--block <replaceable>q</replaceable>|<replaceable>d</replaceable>|<replaceable>n</replaceable></option> |
|
</term> |
|
<listitem> |
|
<para>Set the given block delimiter that embraces the printable data of the csv format. |
|
`q' means a simple quote. |
|
`d' means a double quote. |
|
`n' means no quoting at all (default). |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term><option>-l <replaceable>#</replaceable></option> |
|
<option>--lines <replaceable>#</replaceable></option> |
|
</term> |
|
<listitem> |
|
<para>Force to output multiple tabulars, each having a limited number of lines. |
|
The given argument must be a POSITIVE INTEGER VALUE. This is useful when |
|
the number of input rows is too big to fit into a single papersheet. |
|
A good average for a4 paper is about 40 lines (default). 0 means infinity |
|
(actually about 2 Giga lines). |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term><option>-p <replaceable>l</replaceable>|<replaceable>c</replaceable>|<replaceable>r</replaceable></option> |
|
<option>--position <replaceable>l</replaceable>|<replaceable>c</replaceable>|<replaceable>r</replaceable></option> |
|
</term> |
|
<listitem> |
|
<para>Set the text position in all cells at once. |
|
This simply uses one of the three basic cell formatting options of the LaTeX tabular environment. |
|
`l' means left-aligned (default). |
|
`c' means centered. |
|
`r' means right-aligned. |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term><option>-c <replaceable>0-1</replaceable></option> |
|
<option>--colorrows <replaceable>0-1</replaceable></option> |
|
</term> |
|
<listitem> |
|
<para>Alternate white/gray rows on the LaTeX output, having the given graylevel. |
|
The given argument must be a REAL NUMBER BETWEEN 0 AND 1. |
|
0 means black while 1 means white. |
|
A nice looking value is 0.75 when printed on white paper. |
|
This option uses the extra `colortbl' LaTeX package. |
|
If you also use <option>--nohead</option> option, do not forget to add |
|
the following line into the header of your master document: "\\usepackage{colortbl}". |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term><option>-r <replaceable>1</replaceable>|<replaceable>2</replaceable>|<replaceable>3</replaceable>|<replaceable>4</replaceable></option> |
|
<option>--reduce <replaceable>1</replaceable>|<replaceable>2</replaceable>|<replaceable>3</replaceable>|<replaceable>4</replaceable></option> |
|
</term> |
|
<listitem> |
|
<para>Reduce the size of the tabular and the font in the LaTeX output, given a reduction level. |
|
The given argument must be one of 1, 2, 3 or 4. |
|
The more the level is high, the more the tabular will appear small. |
|
This is useful to shrink the table width when the printable data is made of very long text. |
|
This option uses the extra `relsize' LaTeX package. |
|
If you also use <option>--nohead</option> option, do not forget to add |
|
the following line into the header of your master document: "\\usepackage{relsize}". |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term><option>-z</option> |
|
<option>--nohlines</option> |
|
</term> |
|
<listitem> |
|
<para>Do not output horizontal lines in the table(s). |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term><option>-y</option> |
|
<option>--novlines</option> |
|
</term> |
|
<listitem> |
|
<para>Do not output vertical lines in the table(s). |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term><option>-e</option> |
|
<option>--repeatheader</option> |
|
</term> |
|
<listitem> |
|
<para>Repeat the first row of the first table in every table. |
|
This is useful when the output is very long and separated in |
|
multiple tables. |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term><option>-f <replaceable>#</replaceable></option> |
|
<option>--font <replaceable>#</replaceable></option> |
|
</term> |
|
<listitem> |
|
<para>Set the font size to be inserted on the header and use it to compute lines per table. |
|
The given argument must be an integer in points unit. |
|
If used in conjunction with <option>--lines</option> set to 0, then the lines per tabular |
|
is computed based on LaTeX \\textheight defaulting to 592 pt. |
|
If the <option>--longtable</option> is used, then the computation is not done. |
|
If you also use <option>--nohead</option> option, you should use the same font size |
|
according to your own LaTeX document for best result. |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term><option>-a</option> |
|
<option>--landscape</option> |
|
</term> |
|
<listitem> |
|
<para>Set landscape mode in the LaTeX document header. If used in conjunction with |
|
<option>--lines</option> set to 0 and <option>--font</option> size, then the \\textheight used |
|
to compute lines per tabular defaults to (592 / 1.414) pt. If you also use <option>--nohead</option> |
|
option, you should set your own LaTeX document to landscape mode for best result. |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
</refsect1> |
|
<refsect1> |
|
|
|
<title>EXAMPLES</title> |
|
|
|
<para>Create a PDF document with small text, alternate gray rows, 80 lines per table, |
|
from a guessed csv format of the january stats that my boss created with his |
|
super point-and-click spreadsheet program (which could not generate a PDF output!). |
|
</para> |
|
<para> |
|
<command>&dhpackage; --guess --lines 80 --colorrows 0.75 --reduce 2 january_stats.csv > january_stats.tex && pdflatex january_stats.tex</command> |
|
</para> |
|
|
|
<para>Quickly preview a phonebook from a file formatted as "Surname" "Name" "Phone" "Cellular": |
|
</para> |
|
<para> |
|
<command>&dhpackage; -s p -b d -l 42 phonebook-sorted.txt | latex</command> |
|
</para> |
|
|
|
</refsect1> |
|
<refsect1> |
|
|
|
<title>SEE ALSO</title> |
|
|
|
<para>tex (1), latex (1).</para> |
|
|
|
</refsect1> |
|
</refentry> |
|
|
|
<!-- Keep this comment at the end of the file |
|
Local variables: |
|
mode: sgml |
|
sgml-omittag:t |
|
sgml-shorttag:t |
|
sgml-minimize-attributes:nil |
|
sgml-always-quote-attributes:t |
|
sgml-indent-step:2 |
|
sgml-indent-data:t |
|
sgml-parent-document:nil |
|
sgml-default-dtd-file:nil |
|
sgml-exposed-tags:nil |
|
sgml-local-catalogs:nil |
|
sgml-local-ecat-files:nil |
|
End: |
|
--> |
|
|
|
|
|
|