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:
|
|
-->
|
|
|
|
|
|
|