comparison docs/scripts/man1/TextFilesToHTML.1 @ 0:4816e4a8ae95 draft default tip

Uploaded

0:4816e4a8ae95

.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.22)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "TEXTFILESTOHTML 1"
.TH TEXTFILESTOHTML 1 "2015-03-29" "perl v5.14.2" "MayaChemTools"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
TextFilesToHTML.pl \- Generate HTML table file(s) from TextFile(s)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
TextFilesToHTML.pl ... TextFile(s)...
.PP
TextFilesToHTML.pl [\fB\-a, \-\-align\fR left | center | right,[top | middle | bottom]] [\fB\-b, \-\-border\fR borderwidth] [\fB\-\-cellpadding\fR padding]
[\fB\-\-cellspacing\fR spacing] [\fB\-\-footer\fR string] [\fB\-d, \-\-displaylinks\fR top | bottom | both]
[\fB\-\-displaylinksinfo\fR line | table | both] [\fB\-h, \-\-help\fR]
[\fB\-\-headeralign\fR left | center | right,[top | middle | bottom]] [\fB\-\-headercolor\fR \*(L"#RRGGBB\*(R"]
[\fB\-\-highlight\fR \*(L"fieldlabel,datatype,criterion,value,[fieldlabel,datatype,criterion,value,]...\*(R"]
[\fB\-\-highlightby\fR colnum | collabel] [\fB\-\-highlightcolor\fR \*(L"#RRGGBB,#RRGGBB\*(R"]
[\fB\-\-highlightstyle\fR text | background] [\fB\-\-indelim\fR comma | semicolon] [\fB\-m, \-\-mode\fR plain | shade | highlight | shadedhighlight]
[\fB\-n, \-\-numrows\fR number] [\fB\-o, \-\-overwrite\fR] [\fB\-r, \-\-root\fR rootname]
[\fB\-\-stylesheet\fR old | new | none] [\fB\-\-stylesheetname\fR filename] [\fB \-\-shadecolor\fR \*(L"#RRGGBB,#RRGGBB\*(R"]
[\fB\-t, \-\-title\fR string] [\fB\-\-titledisplay\fR yes | no] [\fB\-w, \-\-workingdir\fR dirname] TextFile(s)...
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Generate \s-1HTML\s0 file(s) from \fITextFile(s)\fR. The \s-1HTML\s0 file(s) contain data tables and appropriate
navigational links to view other tables. These files can be generated for local viewing or
deployment on a web server. A variety of options are provided to control style and
appearence of tables.
.PP
Multiple \fITextFile(s)\fR names are separated by spaces. The valid file extensions are \fI.csv\fR and
\&\fI.tsv\fR for comma/semicolon and tab delimited text files respectively. All other file names
are ignored. All the text files in a current directory can be specified by \fI*.csv\fR,
\&\fI*.tsv\fR, or the current directory name. The \fB\-\-indelim\fR option determines the
format of \fITextFile(s)\fR. Any file which doesn't correspond to the format indicated
by \fB\-\-indelim\fR option is ignored.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-a, \-\-align\fR \fIleft | center | right,[top | middle | bottom]\fR" 4
.IX Item "-a, --align left | center | right,[top | middle | bottom]"
Horizontal and vertical alignment for table rows except for header row which is specified
using \fB\-\-headeralign\fR option. Possible horizontal alignment values: \fIleft, center, or right\fR.
Possible vertical alignment values: \fItop, middle, or bottom\fR.
.Sp
Default values: \fIleft,middle\fR
.IP "\fB\-b, \-\-border\fR \fIborderwidth\fR" 4
.IX Item "-b, --border borderwidth"
Table border width. Default value: 1 for \fIplain\fR and \fIhighlight\fR mode; 0 for \fIshade\fR
and \fIshadedhightlight\fR mode. Zero indicates no border.
.IP "\fB\-\-cellpadding\fR \fIpadding\fR" 4
.IX Item "--cellpadding padding"
Table cell padding. Default value: \fI2\fR.
.IP "\fB\-\-cellspacing\fR \fIspacing\fR" 4
.IX Item "--cellspacing spacing"
Table cell spacing. Default value: \fI1\fR.
.IP "\fB\-\-footer\fR \fIstring\fR" 4
.IX Item "--footer string"
Text string to be included at bottom of each \s-1HTML\s0 file. Default: none.
.IP "\fB\-d, \-\-displaylinks\fR \fItop | bottom | both\fR" 4
.IX Item "-d, --displaylinks top | bottom | both"
Specify where to display navigation links in each \s-1HTML\s0 file for accessing all other \s-1HTML\s0
files. Possible values: \fItop, bottom, or both\fR. Default value: \fIboth\fR. This option is
only valid during multiple \s-1HTML\s0 files generation for an input file.
.IP "\fB\-\-displaylinksinfo\fR \fIline | table | both\fR" 4
.IX Item "--displaylinksinfo line | table | both"
Control display of additional information along with navigational links: Showing line
n of m is displyed for line and showing table n of m for table. Possible values: \fIline
| table | both\fR. Default: \fIboth\fR. This option is only valid  during multiple \s-1HTML\s0 files generation.
.IP "\fB\-h, \-\-help\fR" 4
.IX Item "-h, --help"
Print this help message
.IP "\fB\-\-headeralign\fR \fIleft | center | right,[top | middle | bottom]\fR" 4
.IX Item "--headeralign left | center | right,[top | middle | bottom]"
Horizontal and vertical alignment for table header rows. Possible horizontal alignment
values: \fIleft, center, or right\fR. Possible vertical alignment values: \fItop, middle, or bottom\fR.
.Sp
Default values: \fIcenter,middle\fR
.ie n .IP "\fB\-\-headercolor\fR \fI""#RRGGBB""\fR" 4
.el .IP "\fB\-\-headercolor\fR \fI``#RRGGBB''\fR" 4
.IX Item "--headercolor #RRGGBB"
Color used to fill background of table header row containing column labels
represented as a hexadecimal string. None for \fB\-m, \-\-mode\fR option value
of \fIplain\fR and \fI#ccccff\fR, light blue, for others.
.ie n .IP "\fB\-\-highlight\fR \fI""fieldlabel,datatype,criterion,value,[fieldlabel,datatype,criterion,value,]...""\fR" 4
.el .IP "\fB\-\-highlight\fR \fI``fieldlabel,datatype,criterion,value,[fieldlabel,datatype,criterion,value,]...''\fR" 4
.IX Item "--highlight fieldlabel,datatype,criterion,value,[fieldlabel,datatype,criterion,value,]..."
This value is mode specific. It specifies how to highlight various column values
for each text file. Same set of quartets values are applied to all \fITextFile(s)\fR.
.Sp
For \fIhighlightbycolnum\fR mode, input text format contains these quartets:
\&\fIcolnum,datatype,criterion,value,...\fR. Possible datatype values: \fInumeric or text\fR.
Possible criterion values: \fIle, ge, or eq\fR. Examples: \*(L"1,numeric,le,450>\*(R" or
\&\*(L"2,numeric,ge,150,6,numeric,le,10\*(R".
.Sp
For \fIhighlightbycollabel\fR mode, input text format contains these quartets:
\&\fIcollabel,datatype,criterion,value,...\fR.
.IP "\fB\-\-highlightby\fR \fIcolnum | collabel\fR" 4
.IX Item "--highlightby colnum | collabel"
This value is mode specific. It indicates how columns to be highlighted are specified
using \fB\-\-hightlight\fR option. Possible values: \fIcolnum or collabel\fR. Default value: \fIcolnum\fR.
.ie n .IP "\fB\-\-highlightcolor\fR \fI""#RRGGBB,#RRGGBB""\fR" 4
.el .IP "\fB\-\-highlightcolor\fR \fI``#RRGGBB,#RRGGBB''\fR" 4
.IX Item "--highlightcolor #RRGGBB,#RRGGBB"
Colors used to highlight column values during \fIhighlight\fR and \fIshadedhightlight\fR
mode represented as hexadecimal strings.
.Sp
For \fB\-\-highlighstyle\fR option values of \fItext\fR and \fIbackground\fR, these colors represent
text or background colors respectively. For a specific column, first color string is used for
values which meet criterion indicated by \fB\-\-highlight\fR option; the second color is used
for rest of the values.
.Sp
Default values for \fIbackground\fR \fB\-\-highlightstyle\fR: \fI#0fff0f,#ff0f0f\fR. And default values for
\&\fItext\fR \fB\-\-highlightstyle\fR: \fI#0fbb0f,#ff0f0f\fR. Hexadecimal strings for both \fB\-\-highlightstyle\fR
colors correspond to \fIreddish\fR and \fIgreenish\fR.
.IP "\fB\-\-highlightstyle\fR \fItext | background\fR" 4
.IX Item "--highlightstyle text | background"
This value is mode specific. It indicates highlight style used to differentiate column
values which pass a specified criterion from others. Possible values: \fItext or
background\fR. Default: \fIbackground\fR.
.IP "\fB\-\-indelim\fR \fIcomma | semicolon\fR" 4
.IX Item "--indelim comma | semicolon"
Input delimiter for \s-1CSV\s0 \fITextFile(s)\fR. Possible values: \fIcomma or semicolon\fR.
Default value: \fIcomma\fR. For \s-1TSV\s0 files, this option is ignored and \fItab\fR is used as a
delimiter.
.IP "\fB\-m, \-\-mode\fR \fIplain | shade | highlight | shadedhighlight\fR" 4
.IX Item "-m, --mode plain | shade | highlight | shadedhighlight"
Specify how to generate \s-1HTML\s0 table(s): plain tables with line borders, background of
alternate rows filled with a specified color, column values hightlighted using a specified
criteria, or combination of previous two styles.
.Sp
Possible values: \fIplain, shade, highlight, or shadedhighlight\fR. Default: \fIshade\fR.
.IP "\fB\-n, \-\-numrows\fR \fInumber\fR" 4
.IX Item "-n, --numrows number"
Maximum number of rows per table. Default value: \fI100\fR. Use 0 to put all rows into
one table. For \fITextFile(s)\fR with more than maximum number of specified rows,
multiple \s-1HTML\s0 tables, with appropriate navigation links, are created.
.IP "\fB\-o, \-\-overwrite\fR" 4
.IX Item "-o, --overwrite"
Overwrite existing files.
.IP "\fB\-r, \-\-root\fR \fIrootname\fR" 4
.IX Item "-r, --root rootname"
New file or directory name is generated using the root: <root>.html or <root>\-html.
Default new file name: <InitialTextFileName>.html. Default directory name:
<InitialTextFileName>\-html.
.Sp
For \fITextFile(s)\fR with more than maximum number of rows specified per table,
this directory tree is generated using <Name> where <Name> corresponds to <root>
or <InitialTextFileName>:Top dir \- <Name>\-html; Sub dirs \- html and mols. <Top dir> contains
<Name>.html and <Name>.css files and <sub dir> html conatins various
<Name>Lines<Start>To<End>.html files; <sub dir> mols is created as needed and contains
.Sp
This option is ignored for multiple input files.
.IP "\fB\-\-stylesheet\fR \fIold | new | none\fR" 4
.IX Item "--stylesheet old | new | none"
Controls usage of stylesheet for newly generated \s-1HTML\s0 file(s). Possible values: \fIold,
new, or none\fR. Default value: \fInew\fR.
.Sp
Stylesheet file contains various properties which control apperance of \s-1HTML\s0 pages:
type, size, and color of fonts; background color; and so on.
.Sp
For \fIold\fR value, an existing stylesheet file specified by \fB\-\-stylesheetname\fR option is
used for each \s-1HTML\s0 file; no new stylesheet file is created. This option is quite handy
for deploying \s-1HTML\s0 file(s) on a web server: assuming you specify a valid stylesheet
file location relative to your WWWRoot, a reference to this stylesheet is added to each
\&\s-1HTML\s0 file. For local deployment of \s-1HTML\s0 file(s), a complete path to a local stylesheet
is fine as well.
.Sp
For \fIcreate\fR value, a new stylesheet is created and reference to this local stylesheet
is added to each \s-1HTML\s0 file. Use option \fB\-\-stylesheetname\fR to specify name.
.Sp
For \fInone\fR value, stylesheet usage is completely ignored.
.IP "\fB\-\-stylesheetname\fR \fIfilename\fR" 4
.IX Item "--stylesheetname filename"
Stylesheet file name to be used in conjunction with \fB\-s \-\-stylesheet\fR option. It is only
valid for \fIold\fR value of \fB\-s \-\-stylesheet\fR option. Specify a valid stylesheet file location
relative to your WWWRoot and a reference to this stylesheet is added to each \s-1HTML\s0
file. Example: \*(L"/stylesheets/MyStyleSheet.css\*(R". Or a complete path name to a local
stylesheet file.
.Sp
For \fIcreate\fR value of \fB\-s \-\-stylesheet\fR option, a new stylesheet file is created using
\&\fB\-r \-\-root\fR option. And value of \fB\-\-stylesheetname\fR is simply ignored.
.ie n .IP "\fB \-\-shadecolor\fR \fI""#RRGGBB,#RRGGBB""\fR" 4
.el .IP "\fB \-\-shadecolor\fR \fI``#RRGGBB,#RRGGBB''\fR" 4
.IX Item " --shadecolor #RRGGBB,#RRGGBB"
Colors used to fill background of rows during \fIshade\fR and \fIshadedhightlight\fR mode
represented as a pair of hexadecimal string; the first and second color values
are used for odd and even number rows respectively.
.Sp
Default value: \fI\*(L"#ffffff,#e0e9eb\*(R"\fR \- it's white and very light blue for odd and even number rows.
.IP "\fB\-t, \-\-title\fR \fIstring\fR" 4
.IX Item "-t, --title string"
Title for \s-1HTML\s0 table(s). Default value: <TextFileName>. For multiple input files,
\&\fB\-r \-\-root\fR option is used to generate appropriate titles.
.IP "\fB\-\-titledisplay\fR \fIyes | no\fR" 4
.IX Item "--titledisplay yes | no"
Display title for \s-1HTML\s0 table(s). Possible values: \fIyes or no\fR. Default value: \fIyes\fR.
.IP "\fB\-w, \-\-workingdir\fR \fIdirname\fR" 4
.IX Item "-w, --workingdir dirname"
Location of working directory. Default: current directory.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
To generate \s-1HTML\s0 tables with rows background filled with white and greyish colors and
navigation links on top and botton of each page, type:
.PP
.Vb 1
\&    % TextFilesToHTML.pl \-o Sample1.csv
.Ve
.PP
To generate \s-1HTML\s0 tables with rows background filled with golden and greyish colors,
navigation links on top and botton of each page, 10 rows in each table, greyish header
row color, and cell spacing of 1, type:
.PP
.Vb 3
\&    % TextFilesToHTML.pl \-o \-n 10 \-\-headeralign "center" \-\-headercolor
\&      "#a1a1a1" \-\-shadecolor "#ddd700,#d1d1d1" \-\-cellspacing 1
\&      Sample1.csv
.Ve
.PP
To generate plain \s-1HTML\s0 tables with 10 rows in each table and navigation links only at
the bottom, type:
.PP
.Vb 2
\&    % TextFilesToHTML.pl \-o \-n 10 \-\-displaylinks bottom \-m plain
\&      Sample1.csv
.Ve
.PP
To highlight values in column 3 using specified highlight criteria and fill in default background
colors, type:
.PP
.Vb 3
\&    % TextFilesToHTML.pl \-n 10 \-\-highlight "3,numeric,le,450"
\&      \-\-highlightby colnum \-\-highlightstyle background \-m
\&      shadedhighlight \-o Sample1.csv
.Ve
.PP
To highlight values in column MolWeight using specified highlight criteria, color the text using
default colors, and add a footer message in every page, type:
.PP
.Vb 3
\&    % TextFilesToHTML.pl \-n 4 \-\-highlight "MolWeight,numeric,le,500"
\&      \-\-highlightby collabel \-\-highlightstyle text \-m shadedhighlight \-o
\&      \-\-footer "Copyright (C) MayaChemTools" \-\-cellspacing 1 Sample1.csv
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Manish Sud <[e-mail]>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
JoinTextFiles.pl, MergeTextFilesWithSD.pl, ModifyTextFilesFormat.pl, SplitTextFiles.pl, SortTextFiles.pl
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2015 Manish Sud. All rights reserved.
.PP
This file is part of MayaChemTools.
.PP
MayaChemTools is free software; you can redistribute it and/or modify it under
the terms of the \s-1GNU\s0 Lesser General Public License as published by the Free
Software Foundation; either version 3 of the License, or (at your option)
any later version.