Read Me

Introduction:
-------------

rendertext is an ascii text to possibly many textualized image files converter. Or... in plain english, a text renderer that can produce the text rendered in JPEG, GIF or PNG format files.

QUICK REFERENCE:
----------------

perl rendertext.pl [options] file...

or...

perl rendertext.pl -h

...or even...

perl rendertext.pl --help

...for a summary of usage.

SUMMARY OF OPTIONS:
-------------------

[-f] [--split=int] [-d=output_folder] [--base=destination_folder]
[--short(=maximum_character_width)?] [--ic=interchar_space] 
[--il=interline_space] [--sw=device_screen_width] [--sh=device_screen_height]
[-0=#background_hexcolor] [-1=#foreground_hexcolor] [-t=format] 
[-z=compression_level] [--pd=palette_dithering] [--pc=palette_max_colors]
[--compact|--full|--linear|--html] 
[--largefont|--mediumfont|--smallfont|--tinyfont] [--wrap] [--nowrap] 
[--mt=margin_top] [--mr=margin_right] [--mb=margin_bottom] [--ml=margin_left]
[--bg=bg_file] [--bg-fixed] [--bg-tiled] [--bg-stretched] [--bg-opac=level]
[--pagenumbers] [--pn-offr=pixels] [--pn-offb=pixels] [--nopagenumbers]
[--rotate90|--rotate180|--rotate270] [--encoding=input_file_encoding]
[--oencoding=output_encoding] [--single=tmp_img_file_path] [--stdout(=(0|1))?]
[--pref=preferences_file]

OPTIONS IN DETAIL:
------------------

-h              : Prints this help.

file            : The file name/path to convert to a textual image. Unless in 
                  help mode, this is the only mandatory argument value.

-d=folder       : Folder where to put all the image files, default is one 
                  based in the file name and just below current folder.

--base=folder   : Specifies a folder (f) where to put inside all the generated
                  folders and files with the images. This option has no effect
                  when the -d switch is used.

--short=maxchar : *************************************************************
                  NOTE: This is a truncation option destinated to solve path
                  name length problems with some operating systems.
                  *************************************************************
                  Use short names for folders and generated image filenames.
                  The specified value refers not to total file/folder length
                  but to the prefix is taken from the file name to use it in
                  the file/folder name generation. This option is only taken
                  into account, if -d option is specified, for file names (so 
                  specified folder name is always respected if -d option is 
                  used). 

--short         : *************************************************************
                  NOTE: This is a truncation option destinated to solve path
                  name length problems with some operating systems.
                  *************************************************************
                  Use short names for folders and generated image filenames,
                  but using program's default value. This option is useful to
                  avoid errors when trying to create files and/or folders in 
                  operating systems that have a critical maximum length 
                  limitation for path names (like WinXP, for example).

--split=int     : Split images in different subfolders with at most this number
                  of files. Useful for ease navigation inside large documents.

-f              : Force folder override, if folder exists, all images in that 
                  folder would be possibly overriden with the new image ones 
                  without notice. So use with caution, or you can loss your 
                  previous image files...

--ic=-?int      : Horizontal space between characters additional to the font 
                  default one, use a positive or integer only, like -1 or 1, 
                  in order to decrease total size or readability, respectively,
                  for example. Default value is 0 pixels, the default kerning 
                  value for the font used.

--il=-?int      : Vertical space between lines. Default value is 0 (pixels).

--sw=int        : Screen width of the output reader device, the default value 
                  is 220.

--sh=int        : Screen height of the output reader device, default is 176.

-0=#hhhhhh      : Color for the background, in web hex format (for example 
                  #eeeeee for a silver gray). Default is #000000 (black). In 
                  general dark background colors will reduce significantly 
                  the power conmsumption of the MP4 device when reading ebooks.

-1=#hhhhhh      : Color for the foreground, the text in human common slang, 
                  in web hex format (for example #003377 for a nice pen alike 
                  dark blue). Default value is #bbbbbb, a light gray.

-t=jpg|gif|png  : The output image format, intended to be readable in the 
                  reader device in question. Default is jpg por a JPEG 
                  compression job.

-z=int          : The compression level, 0-100 for jpg output type, 0-9 for png
                  output type, void option for gif's. Higher the better quality
                  and so bigger image size for jpg's.

--pd=0|1        : The dithering level is an integer, 0 is false, no dithering,
                  1 means a true for dithering, in png and gif outputs only.

--pc=0-256      : The maximum number of colors for the palette in png and gif 
                  outputs only, and integer in the zero to 256 range.

--mt=-?int|auto : Top margin, in pixels, auto for automatic, that is default.

--mr=-?int|auto : Right margin, in pixels, auto for automatic, that is default.

--mb=-?int|auto : Bottom margin, in pixels, auto for automatic, that's default.

--ml=-?int|auto : Left margin, in pixels, auto for automatic, that is default
                  ---> negative values are allowed for margins.

--compact       : Compact textual output, this is ok when you do not need to 
                  preserve visually all newline information, and want to reduce
                  number of image files as much as possible.

--full          : Do this if you want the exact output as in the original text 
                  of the file, maintaining as much as possible the original 
                  formatting like in source code listings... or poetry, for 
                  example.

--linear        : The default formatting, compresses single newlines, but 
                  trying to respect paragraph spacing, and does additional 
                  whitespace trimming in order to compact text in start of 
                  lines and pages.

--html          : A linear mode but with some minimal html interpretation of
                  the source file. A kind of "text plus images" mode for html
                  with images stored in disk with the browser's "Save Page As"
                  command.

--smallfont     : Use a small font for text rendering, this is default font.

--tinyfont      : Use a very small font for text rendering. This can help to
                  reduce rendered size, but probably decreasing readability.

--mediumfont    : Use a medium sized font for text rendering.

--largefont     : Use a large sized font for text rendering. This could be 
                  a size suicide for small device rendering purposes.

--pagenumbers   : Use page numbering, default is not.

--nopagenumbers : Do not use page numbering, this is default.

--pn-offr=int   : A positive integer indicating offset for page numbers display
                  from the right side of the screen.

--pn-offb=int   : A positive integer indicating offset for page numbers display
                  from the bottom side of the screen.

--wrap          : Allow line break happenings inside words.

--nowrap        : Do not wrap chars inside of a word (that is, not allowing 
                  line breaks inside the same "word"), this option improves 
                  readability if for some reason the context is not clear in
                  considering any word's interpretation, at the expense of some
                  more number of files generated. This is the default option.

--bg=file       : Use file as the background texture for paper instead of a 
                  solid background color.

--bg-fixed      : Use background plainly as is (this is default mode). 

--bg-tiled      : Use background image as a mosaic and repeat it until screen's
                  background is filled. 

--bg-stretched  : Stretch background image until it fits exactly covering the
                  whole space of screen's background.

--bg-opac=0-100 : Mix background image with background color letting background
                  image (painted one level upper) have a transparency level for
                  background color to shine through, up to this opacity level.

--rotate90      : Rotate 90 degrees the output image.

--rotate180     : Rotate 180 degrees the output image.

--rotate270     : Rotate 270 degrees the output image.

--encoding=ienc : Declare character coding to be of ienc type, where ienc is a
                  recognized coding type, ISO-8859-1, for example. Does a 
                  character mapping based encoding transformation.

--oencoding=oen : Use oen encoding for the rendered text. GD library fonts use
                  ISO-8859-2 internally. Specifiying --encoding or --oencoding
                  is currently the only way to force encoding transformations 
                  to take place. Otherwise characters will be render careless.

--single=path   : Use path as a filename spec where a single image output for 
                  preview will be produced. This option is intended to be used
                  only for GUI based wrappers. Currently this path is relative
                  to that of this script, or an absolute path specification, 
                  and is not previously examined for correctness.

--stdout=0|1    : Use stdout for error output too (1) or prevail classical way,
                  redirecting error output to stderr (0).

--stdout        : Alias for --stdout=1.

--pref=file     : Read file for preferences, as an inclusive alternative 
                  mimetic and parallel to command line options parsing.

EXAMPLES:
---------

* Ultra-minimal example:

perl rendertext.pl GPL.txt

* Conventional example:

perl rendertext.pl -f -0=#eeeeee -1=#002277 --pagenumbers GPL.txt

* A somewhat more complete and even no less nicer example:

perl rendertext.pl --linear --pagenumbers -f --ml=20 --mt=12 --mb=14 --mr=12 --bg=backgrounds/paper5.jpg -1=#333333 --pn-offr=10 --pn-offb=8 GPL.TXT

PREFERENCE FILE PARAMETERS:
---------------------------
Preference file parameters go one by line, starting by its name, followed by the ASCII '=' char, and the preference value. This way:

  option_name=option_value

Comments can be embedded in, going one per line, starting with the ASCII ';' character. This way:

  ; this is a comment

Parameters summary:
-------------------

* force_folder_override:
  Do you want to enable rewriting folders with generated e-books?: 0 to prevent, 1 to enable.

example: force_folder_override=1

* output_folder:
  Specify an alternate ouput disk/folder for generated e-books.

example: output_folder=C:/

* short_img_names:
  Use this option to specify if you want to limit file name size in characters (as some operating systems have problems with long file names).
  * Put to 1 to use default limit, an integer above 1 to a concrete max length.
  * Left blank this option, or put 0 for not limiting file name sizes.

example: short_img_names=8

* force_text_mode:
  Values: full, linear, compact or html, to force its correspondent text layout interpretation by rendertext.

example: force_text_mode=compact

* default_text_mode:
  Values: full, linear, or compact to default text files to this format. Does not affect html mode though, only plain text files. Be advised that "text file or not to text" is detected by extension, or not having one, files that have an extension recognized as html or as source code (perl, java, etc...), for example, are continuing to be interpreted literally, that's using full text mode. So that's the reason of the force_text_mode option, to fully force whatever another behavior you want.

example: default_text_mode=full

* letter_spacing:
  Space between characters in pixels (can be a negative integer).

example: letter_spacing=-1

* line_height:
  Space between lines in pixels (can be a negative integer).

example: line_height=-1

* bg_color:
  The background color, in web hex format (#ff000 for red and so for...).

example: bg_color=#282828

* fg_color:
  A color for text, in web hex format.

example: fg_color=#eeeeee

* bg_img_path:
  Path for a background image.

example: bg_img_path=/somepath/someimage.jpg

* bg_img_attachment:
  Fill type for background image: fixed, tiled or stretched.

example: bg_img_attachment=stretched

* bg_img_opac
  Alpha value for background image, in the range 0-100.

example: bg_img_opac=50

* img_format:
  GIF, JPG or PNG for output.

example: img_format=PNG

* img_compression:
  Compression ratio for output (png: 0-9, jpeg: 0-100).

example: img_compression=8

* img_dithering:
  Image palette dithering: 0 no dither, 1 use dithering.

example: img_dithering=1

* img_colors:
  Max number of colors, for paletized formats only (gif, maybe png).

example: img_colors=4

* img_width:
  Use this option to adapt image size to your exact device's screen width (valid values are integers representing size in pixels).

example: img_width=300

* img_height:
  Use this option to adapt image size to your exact device's screen height (valid values are integers representing size in pixels).

example: img_height=200

* rotate_img:
  Values: 0 (default), 90, 180 or 270, to rotate image 90, 180 or 270 degrees at the output, respectively, in order to, combined with switching img_width and img_height values, probably ease reading in some weirdly handled devices.

example: rotate_img=90

* margin_top:
  Space from image top to text in pixels, positive values only.

example: margin_top=8

* margin_right:
  Space from right image side to text in pixels, positive values only.

example: margin_right=4

* margin_left:
  Space from left image side to text in pixels, positive values only.

example: margin_left=5

* margin_bottom:
  Space from the bottom side of the image to text in pixels, positive values only.

example: margin_bottom=0

* font_size:
  Possible values are 1, 2, 3 or 4, in increasing size.

example: font_size=2

* print_page_numbers:
  Put to 0 for not to print page numbers, 1 for printing, this is the default.

example: print_page_numbers=1

* page_numbers_roffset:
  Pixel offset from right side of the image where page numbers will be printed.

example: page_numbers_roffset=1

* page_numbers_boffset:
  Pixel offset from image bottom where page numbers will be printed.

example: page_numbers_boffset=1

* wrap_text:
  Do you want to allow broken words at newlines or not?
  Values: 1 to allow, 0 to disallow, let blank for default.

example: wrap_text=0

* text_encoding:
  Source (html, text) encoding format, commonly one of string like: ISO-8859-1 or UTF-8.

example: text_encoding=UTF-8

* output_encoding:
  Encoding format used for rendering, default: ISO-8859-2.

example: output_encoding=ISO-8859-2

* split:
  Organize images at output in series of numbered folders with the images, this value allows to specify the number of images to store, in each folder: maybe useful for organization of e-booooooooks.

example: split=10

History:
--------

My conventional usage of this program is for reading e-books, producing the image files that copied into an MP4 player's photo or image folder you can read using the photo/image viewer. That is why all default options were wrote to fit ok into a sansa's fuze player.

All camed from my interest in reading Gutenberg Project's books without paper (too disturbing passing pages), money (I'm an occasional reader, I don't have money, so I don't need an e-book reader) and weight (my hands are lazy enough to hold a book long time resting at bed, and reading incorporated was not made for me, between other things).

The initial idea was coding a txt file viewer for fuze's rockbox driver, sounds good, but very complicated to my knowledge. 

But some time later I, with some pleasure, get inside a thought of mine that described with naive details how a 100 KB ascii text could be put in ~ 200 jpeg 10 KB images... 2M, not quite bad to release me from a software intervention obbey!

The idea was convert a file with only ascii characters, a common txt plain english file, like a Gutenberg project book, for example, into a series of jpeg images with sequential names with the title of the book as the base that represent the pagination of it, prepared to be copied to a device for my own reading pleasure.

Then fuze seemed to have a 220 * 176 pixel screen matrix, I did not count them, but I assumed this fact as nice, like if the universe were not infinite, let's say... :-) And then, happily, I assumed with a lesser extent satisfacion that the only format that is capable to read from is JPEG, because GIF or PNG produced lesser size image files for text rendering...

And then I thought that could be interesing to produce anywhere in the future a splitted mozilla rendering output, in another child program that will surely be called renderhtml.

So I made a first try (called fuzetxt2jpg), and then this project starts with new name and renewed ambition (kidding...) where fuzetxt2jpg was left.

Statistics and performance, or something...
-------------------------------------------

For GIF/PNG file generation, in a perfect quality, a 50 KB book/article goes to a range between 100 KB and 300 KB of image files, depending on font used, and the --compact option, let's say.

For JPEG file generation, in a decent quality, a 50 KB book/article goes to a range between 700 KB and 3 MB of image files, depending of background/foregroung colors, font used, and the --compact option, more or less.

License:
--------
Currently a GPL <http://www.gnu.org/licenses/gpl.html>.

Note: all references to MP4 commercial device names cited here are merely for informative purposes, and of course they may be a registered trademark of their respective owners and/or are under some kind of copyright protection.

Let me end with this:

~ "Not proud of criticisms, but proud of your usage, be proud of yourself" ~