Permalink
Browse files

updated README, release information, documentation

  • Loading branch information...
1 parent 170d3e1 commit dc009e215d515d9e8e9e9f2df3df5d26a8ba21a5 @ByteProject ByteProject committed Mar 17, 2012
Showing with 133 additions and 6 deletions.
  1. +133 −6 README.md
View
139 README.md
@@ -1,18 +1,145 @@
# AnsiLove/C
-This is a complete rewrite of [AnsiLove/PHP](http://ansilove.sourceforge.net) in the C programming language. It converts ANSi and artscene related file formats into PNG images. Unlike the PHP variant, AnsiLove/C is intended as UNIX command line tool you install preferably to `/usr/bin`. Right now the project is in an early stage of development. It's neither considered as finished nor as stable product, but we are busy working on it.
+This is a complete rewrite of [AnsiLove/PHP](http://ansilove.sourceforge.net) in the C programming language. It converts ANSi and artscene related file formats into PNG images. Unlike the PHP variant, AnsiLove/C is intended as UNIX command line tool you install preferably to `/usr/bin`. The project is considered as completed and stable, current version is `1.0.237`.
# Specs
-AnsiLove/C is strictly using the `C99 standard` to achieve high portability to all major operating systems. It's developed from ground up with the vision to compile just fine on your platform. Be sure to link against `libgd` when compiling which is also needed when running the binary. Supported compilers are `gcc` and `Clang`, others may work but aren't tested. All files include the C standard headers. An exception is compilation on `Mac OS X`, where defines in the sources ensure importing `<Foundation/Foundation.h>`. In other words: the resulting binary on the Mac is a Foundation tool. We use Mac OS X and Linux for AnsiLove/C development. You'll find a Xcode project file in this repository. Additional there's a shell script that builds AnsiLove/C on Ubuntu, it should compile on other distros as well.
+AnsiLove/C is strictly using the `C99 standard` to achieve high portability to all major operating systems. It's developed from ground up with the vision to compile just fine on your platform. Be sure to link against `libgd` when compiling which is also needed when running the binary. Supported compilers are `gcc` and `Clang`, others may work but aren't tested. All files include the C standard headers. An exception is compilation on `Mac OS X`, where defines in the sources ensure importing `<Foundation/Foundation.h>`. In other words: on the Mac, the resulting binary is a Foundation tool. We use Mac OS X and Linux for AnsiLove/C development. You'll find a Xcode project file in this repository. Additional there's a shell script that builds AnsiLove/C on Ubuntu, it should compile on other distros as well. Feel free to fork and add custom build scripts for your own platform, [Homebrew](https://github.com/mxcl/homebrew) formulas, Linux packages, whatever.
-# Why porting to C?
+# Why C?
-There are many reasons for doing this, most notably PHP interpreter independence and performance. A solid C foundation is just perfect for creating libraries and frameworks and it can easily embedded into applications. We already mentioned portability: while there isn't a PHP CLI available for every system, there are very few computer architectures for which a C compiler does not exist. What else? We want evolution. In certain situations, PHP is pretty limited. So AnsiLove/C is not an one to one porting of it's ancestor, it's overall improved and introduces new features.
+There were many reasons, most notably PHP interpreter independence and performance. A solid C foundation is just perfect for creating libraries and frameworks and it can easily embedded into applications. We already mentioned portability. What else? We wanted evolution. AnsiLove/C should not be understood as a port. It takes many different approaches (like processing binary font dumps), it is overall improved and introduces new features. While results tend to be the same, the codebase does not have much in common with it's ancestor.
-# Cocoa / Foundation bridge
+# Cocoa bridge
-If you're looking for something to implement into your Cocoa or Foundation applications, we highly recommend taking a look at [AnsiLove.framework](https://github.com/ByteProject/AnsiLove.framework), which is actively maintained by [@ByteProject](https://github.com/ByteProject) and running smooth and stable. It uses a modfied version of [AnsiLove/PHP](http://ansilove.sourceforge.net) as rendering library and provides a Cocoa layer on top of it. Once AnsiLove/C is finished, it will replace [AnsiLove/PHP](http://ansilove.sourceforge.net) in the [AnsiLove.framework](https://github.com/ByteProject/AnsiLove.framework), to go all the way native.
+If you're looking for something to implement into your Cocoa applications, we highly recommend taking a look at [AnsiLove.framework](https://github.com/ByteProject/AnsiLove.framework), which is actively maintained by [@ByteProject](https://github.com/ByteProject). It uses AnsiLove/C as rendering library and provides a Cocoa layer on top of it.
+
+# Features
+
+Rendering of all known ANSi / ASCII art file types:
+
+- ANSi (.ANS)
+- BiNARY (.BIN)
+- Artworx (.ADF)
+- iCE Draw (.IDF)
+- XBiN (.XB) [details](http://www.acid.org/info/xbin/xbin.htm)
+- PCBOARD (.PCB)
+- TUNDRA (.TND) [details](http://sourceforge.net/projects/tundradraw)
+- ASCII (.ASC)
+- RELEASE info (.NFO)
+- Description in zipfile (.DIZ)
+
+Files with custom suffix default to the ANSi renderer (e.g. ICE or CIA).
+
+AnsiLove/C is capabable of processing:
+
+- SAUCE records
+- DOS and Amiga fonts (embedded binary dump)
+- iCE colors
+
+What else is there:
+
+- Output files are highly optimized 4-bit PNGs
+- You can use custom operands for adjusting output results
+- Built-in support for rendering Amiga ASCII
+
+# Documentation
+
+One major goal for AnsiLove/C was implementing the look and feel of common UNIX command line tools. We strictly follow the `IEEE Std 1003.1` for utility conventions while maintaining compabtiblity with `GNU`. Users comfortable with either one or the other standard should feel home.
+
+## Synopsis
+
+ ansilove file -i [operands]
+ ansilove file -o file.png [operands]
+ ansilove file -s
+ ansilove -vhe
+
+## Options
+
+ -i output identical to input with .png suffix added
+ -o specify custom file name / path for output
+ -s display SAUCE record without generating output
+ -v version information, equivalent to --version
+ -h show help, equivalent to --help
+ -e print a list of examples
+
+## Operands
+
+ font bits icecolors columns
+
+Optional values to adjust output. There are certain cases where you need to set operands for proper rendering. However, this is occassionally. Results turn out well with the built-in defaults. You may launch AnsiLove with the option `-e` to get a list of basic examples, with and without operands. Note that columns is restricted to BIN files, it won't affect other file types. It's also worth mentioning that setting a certain operand requires to set all operands before, so if you need to modifiy the `icecolors` operand, you have to set `font` and `bits` as well. On the other hand, it's fine to set the `font` operand while not setting any of the following. Got that?
+
+## font (operand)
+
+We dumped many fonts as binary data right into AnsiLove/C, so the most popular typefaces for rendering ANSi / ASCII art are available right at your fingertips.
+
+PC fonts can be (all case-sensitive):
+
+- `80x25` (code page 437)
+- `80x50` (code page 437, 80x50 mode)
+- `armenian`
+- `baltic` (code page 775)
+- `cyrillic` (code page 855)
+- `french-canadian` (code page 863)
+- `greek` (code page 737)
+- `greek-869` (code page 869)
+- `hebrew` (code page 862)
+- `icelandic` (Code page 861)
+- `latin1` (code page 850)
+- `latin2` (code page 852)
+- `nordic` (code page 865)
+- `persian` (Iran System encoding standard)
+- `portuguese` (Code page 860)
+- `russian` (code page 866)
+- `terminus` (modern font, code page 437)
+- `turkish` (code page 857)
+
+AMIGA fonts can be (all case-sensitive):
+
+- `amiga` (alias to Topaz)
+- `microknight` (Original MicroKnight version)
+- `microknightplus` (Modified MicroKnight version)
+- `mosoul` (Original mO'sOul font)
+- `pot-noodle` (Original P0T-NOoDLE font)
+- `topaz` (Original Topaz Kickstart 2.x version)
+- `topazplus` (Modified Topaz Kickstart 2.x+ version)
+- `topaz500` (Original Topaz Kickstart 1.x version)
+- `topaz500plus` (Modified Topaz Kickstart 1.x version)
+
+## bits (operand)
+
+`bits can be (all case-sensitive):
+
+- `8` (8-bit)
+- `9` (9-bit)
+- `ced`
+- `transparent`
+- `workbench`
+
+Setting the bits to `9` will render the 9th column of block characters, so the output will look like it is displayed in real textmode.
+
+Setting the bits to `ced` will cause the input file to be rendered in black on gray, and limit the output to 78 columns (only available for `.ans` files). Used together with an `AMIGA` font, the output will look like it is displayed on Amiga.
+
+Setting the bits to `workbench` will cause the input file to be rendered using Amiga Workbench colors (only available for `.ans` files).
+
+Settings the bits to `transparent` will produce output files with transparent background (only available for `.ans` files).
+
+## icecolors (operand)
+
+`icecolors` can be:
+
+- `0`
+- `1`
+
+Setting `icecolors` to `1` will enable iCE color codes. On the opposite `0` means that that `iceColors` are disabled, which is the default value. When an ANSi source was created using iCE colors, it was done with a special mode where the blinking was disabled, and you had 16 background colors available. Basically, you had the same choice for background colors as for foreground colors, that's iCE colors. But now the important part: when the ANSi source does not make specific use of iCE colors, you should NOT set this flag. The file could look pretty weird in normal mode. So in most cases it's fine to turn iCE colors off.
+
+## columns (operand)
+
+`columns` is only relevant for ANSi source files with `.bin` extension and even for those files optional. In most cases conversion will work fine if you don't set this flag, the default value is `160` then. So please pass `columns` only to .bin files and only if you exactly know what you're doing. A KITTEN MAY DIE SOMEWHERE.
+
+## SAUCE records
+
+It's fine to use AnsiLove/C as SAUCE reader without generating any output, just set option `-s` for this purpose.
# Who pulls the strings

0 comments on commit dc009e2

Please sign in to comment.