-Jexer - Java Text User Interface library
-========================================
+English [Français](README-fr.md)
-WARNING: THIS IS ALPHA CODE! PLEASE CONSIDER FILING BUGS AS YOU
-ENCOUNTER THEM.
+# Fanfix
-This library is intended to implement a text-based windowing system
-loosely reminiscient of Borland's [Turbo
-Vision](http://en.wikipedia.org/wiki/Turbo_Vision) library. For those
-wishing to use the actual C++ Turbo Vision library, see [Sergio
-Sigala's updated version](http://tvision.sourceforge.net/) that runs
-on many more platforms.
+Fanfix is a small Java program that can download stories from some supported websites and render them offline.
-Two backends are available:
+## 🔴 This is the command line and server program
-* System.in/out to a command-line ECMA-48 / ANSI X3.64 type terminal
- (tested on Linux + xterm). I/O is handled through terminal escape
- sequences generated by the library itself: ncurses is not required
- or linked to. xterm mouse tracking using UTF8 coordinates is
- supported. For the demo application, this is the default backend on
- non-Windows platforms.
+You can also use:
+- the graphical client [Fanfix-swing](https://github.com/nikiroo/fanfix-swing/)
+- the TUI client [Fanfix-jexer](https://github.com/nikiroo/fanfix-jexer/)
-* Java Swing UI. This backend can be selected by setting
- jexer.Swing=true. The default window size for Swing is 132x40,
- which is set in jexer.session.SwingSession. For the demo
- application, this is the default backend on Windows platforms.
+## Synopsis
-The demo application showing the existing UI controls is available via
-'java -jar jexer.jar' or 'java -Djexer.Swing=true -jar jexer.jar' .
+- ```fanfix``` --import [*URL*]
+- ```fanfix``` --export [*id*] [*output_type*] [*target*]
+- ```fanfix``` --convert [*URL*] [*output_type*] [*target*] (+info)
+- ```fanfix``` --read [*id*] ([*chapter number*])
+- ```fanfix``` --read-url [*URL*] ([*chapter number*])
+- ```fanfix``` --search
+- ```fanfix``` --search [*where*] [*keywords*] (page [*page*]) (item [*item*])
+- ```fanfix``` --search-tag
+- ```fanfix``` --search-tag [*index 1*]... (page [*page*]) (item [*item*])
+- ```fanfix``` --list
+- ```fanfix``` --server [*key*] [*port*]
+- ```fanfix``` --stop-server [*key*] [*port*]
+- ```fanfix``` --remote [*key*] [*host*] [*port*]
+- ```fanfix``` --help
-Additional backends can be created by subclassing
-jexer.backend.Backend and passing it into the TApplication
-constructor.
+## Description
+(If you are interested in the recent changes, please check the [Changelog](changelog.md) -- note that starting from version 1.4.0, the changelog is checked at startup.)
+This program will convert from a (supported) URL to an .epub file for stories or a .cbz file for comics (a few other output types are also available, like Plain Text, LaTeX, HTML...).
-License
--------
+To help organize your stories, it can also work as a local library so you can:
-This project is licensed LGPL ("GNU Lesser General Public License",
-sometimes called the "Library GPL") version 3 or greater. You may
-freely use Jexer in both closed source (proprietary) and open source
-applications, however any changes you make to the Jexer code must be
-made available to your users.
+- Import a story from its URL (or just from a file)
+- Export a story to a file (in any of the supported output types)
+- Display a story from the local library in text format in the console
+- Via [fanfix-swing](https://github.com/nikiroo/fanfix-swing/): Display a story from the local library graphically **by itself** ([fanfix-swing](https://github.com/nikiroo/fanfix-swing/)) or **by calling a native program to handle it** (potentially converted into HTML before hand, so any browser can open it)
-See the file LICENSE for the full license text, which includes both
-the GPL v3 and the LGPL supplemental terms.
+### Supported websites
+Currently, the following websites are supported:
+- http://FimFiction.net/: fan fictions devoted to the My Little Pony show
+- http://Fanfiction.net/: fan fictions of many, many different universes, from TV shows to novels to games
+- http://mangahub.io/: a well filled repository of mangas (English)
+- https://e621.net/: a Furry website supporting comics, including MLP
+- https://sofurry.com/: same thing, but story-oriented
+- https://e-hentai.org/: done upon request (so, feel free to ask for more websites!)
+- http://mangas-lecture-en-ligne.fr/: a website offering a lot of mangas (in French)
-Acknowledgements
-----------------
+### Support file types
-Jexer makes use of the Terminus TrueType font [made available
-here](http://files.ax86.net/terminus-ttf/) .
+We support a few file types for local story conversion (both as input and as output):
+- epub: .epub files created by this program (we do not support "all" .epub files, at least for now)
+- text: local stories encoded in plain text format, with a few specific rules:
+ - the title must be on the first line
+ - the author (preceded by nothing, ```by ``` or ```©```) must be on the second line, possibly with the publication date in parenthesis (i.e., ```By Unknown (3rd October 1998)```)
+ - chapters must be declared with ```Chapter x``` or ```Chapter x: NAME OF THE CHAPTER```, where ```x``` is the chapter number
+ - a description of the story must be given as chapter number 0
+ - a cover image may be present with the same filename as the story, but a .png, .jpeg or .jpg extension
+- info_text: contains the same information as the text format, but with a companion .info file to store some metadata (the .info file is supposed to be created by Fanfix or compatible with it)
+- cbz: .cbz (collection of images) files, preferably created with Fanfix (but any .cbz file is supported, though without most of Fanfix metadata, obviously)
+- html: HTML files that you can open with any browser; note that it will create a directory structure with ```index.html``` as the main file -- we only support importing HTML files created by Fanfix
+### Supported platforms
-Usage
------
+Any platform with at lest Java 1.6 on it should be ok.
-Usage patterns are still being worked on, but in general the goal will
-be to build applications as follows:
+It has been tested on Linux (Debian, Slackware, Ubuntu), MacOS X and Windows for now, but feel free to inform us if you try it on another system.
-```Java
-import jexer.*;
+If you have any problems to compile it with a supported Java version (1.6+), please contact us.
-public class MyApplication extends TApplication {
+## Options
- public MyApplication() {
- super(BackendType.SWING); // Could also use BackendType.XTERM
+You can start the program in two ways:
- // Create standard menus for File and Window
- addFileMenu();
- addWindowMenu();
- }
+- ```java -jar fanfix.jar```
+- ```fanfix``` (if you used *make install*)
- public static void main(String [] args) {
- MyApplication app = new MyApplication();
- (new Thread(app)).start();
- }
-}
-```
+The following arguments are allowed:
-See the file demos/Demo1.java for detailed examples.
+- ```--import [URL]```: import the story at URL into the local library
+- ```--export [id] [output_type] [target]```: export the story denoted by ID to the target file
+- ```--convert [URL] [output_type] [target] (+info)```: convert the story at URL into target, and force-add the .info and cover if +info is passed
+- ```--read [id] ([chapter number])```: read the given story denoted by ID from the library
+- ```--read-url [URL] ([chapter number])```: convert on the fly and read the story at URL, without saving it
+- ```--search```: list the supported websites (```where```)
+- ```--search [where] [keywords] (page [page]) (item [item])```: search on the supported website and display the given results page of stories it found, or the story details if asked
+- ```--tag [where]```: list all the tags supported by this website
+- ```--tag [index 1]... (page [page]) (item [item])```: search for the given stories or subtags, tag by tag, and display information about a specific page of results or about a specific item if requested
+- ```--list```: list the stories present in the library and their associated IDs
+- ```--server [key] [port]```: start a story server on this port
+- ```--stop-server [key] [port]```: stop the remote server running on this port (key must be set to the same value)
+- ```--remote [key] [host] [port]```: contact this server instead of the usual library (key must be set to the same value)
+- ```--help```: display the available options
+- ```--version```: return the version of the program
+### Environment
+Some environment variables are recognized by the program:
-Known Issues / Arbitrary Decisions
-----------------------------------
+- ```LANG=en```: force the language to English
+- ```CONFIG_DIR=$HOME/.fanfix```: use the given directory as a config directory (and copy the default configuration if needed)
+- ```NOUTF=1```: try to fallback to non-unicode values when possible (can have an impact on the resulting files, not only on user messages)
+- ```DEBUG=1```: force the ```DEBUG=true``` option of the configuration file (to show more information on errors)
-Some arbitrary design decisions had to be made when either the
-obviously expected behavior did not happen or when a specification was
-ambiguous. This section describes such issues.
+## Compilation
- TTerminalWindow
- ---------------
+```./configure.sh && make```
- - TTerminalWindow will hang on input from the remote if the
- TApplication is exited before the TTerminalWindow's process has
- closed on its own. This is due to a Java limitation/interaction
- between blocking reads (which is necessary to get UTF8 translation
- correct) and file streams.
+You can also import the java sources into, say, [Eclipse](https://eclipse.org/), and create a runnable JAR file from there.
- - See jexer.tterminal.ECMA48 for more specifics of terminal
- emulation limitations.
+There are some unit tests you can run, too:
- - TTerminalWindow uses cmd.exe on Windows. Output will not be seen
- until enter is pressed, due to cmd.exe's use of line-oriented
- input (see the ENABLE_LINE_INPUT flag for GetConsoleMode() and
- SetConsoleMode()).
+```./configure.sh && make build test run-test```
- ECMA48 Backend
- --------------
-
- - Mouse support for BackendType.ECMA48/XTERM currently requires UTF-8
- coordinates (1005 mode). Terminals that support UTF-8 mouse coordinates
- include xterm, rxvt-unicode, gnome-terminal, and konsole. Due to Java's
- InputStreamReader requirement of a valid UTF-8 stream, one must assume
- the terminal will always generate correct UTF-8 bytes. Mode 1006 (SGR)
- will be supported in a future release.
+If you run the unit tests, note that some flag files can impact them:
+- ```test/VERBOSE``` : enable verbose mode
+- ```test/OFFLINE``` : to forbid any downloading
+- ```test/URLS``` : to allow testing URLs
+- ```test/FORCE_REFRESH```: to force a clear of the cache
+Note that ```test/CACHE``` can be kept, as it will contain all internet related files you need (if you allow URLs, run the test once which will populate the CACHE then go OFFLINE, it will still work).
-Roadmap
--------
+The test files will be:
-Many tasks remain before calling this version 1.0:
+- ```test/*.url``` : URL to download in text format, content = URL
+- ```test/*.story```: text mode story, content = story
-0.0.2: STABILIZE EXISTING
-- TTerminalWindow
- - Expose shell commands as properties
-- Swing:
- - Blinking cursor
- - Block cursor
-- ECMA48Backend running on socket
-- TFileOpen
-- Decide on naming convention: getText, getValue, getLabel: one or all
- of them?
-- Refactor:
- - TKeypress:
- - getCh() --> getChar()
- - getAlt/getCtrl/getShift --> isAltDown / isCtrlDown / isShiftDown
- - Other boolean getters --> isSomething
-- Document any properties used
- - Expose use of 'stty'
+### Dependant libraries (included)
-0.0.3: FINISH PORTING
+Required:
-- TTreeView
- - Also add keyboard navigation
-- TDirectoryList
- - Also add keyboard navigation
+- ```libs/nikiroo-utils-sources.jar```: some shared utility functions
+- [```libs/unbescape-sources.jar```](https://github.com/unbescape/unbescape): a nice library to escape/unescape a lot of text formats; used here for HTML
+- [```libs/jsoup-sources.jar```](https://jsoup.org/): a library to parse HTML
+- [```libs/JSON-java-20190722-sources.jar```](https://github.com/stleary/JSON-java): a library to parse JSON
-0.0.4: NEW STUFF
+Optional:
-- Making TMenu keyboard accelerators active/inactive
-- TStatusBar
-- TEditor
-- TWindow
- - "Smart placement" for new windows
+- [```libs/jexer-sources.jar```](https://github.com/klamonte/jexer): a small library that offers TUI widgets
+- [```pandoc```](http://pandoc.org/): to generate the man pages from the README files
-0.0.5: BUG HUNT
+Nothing else but Java 1.6+.
-- TSubMenu keyboard mnemonic not working
-- ECMA48Terminal
- - Mode 1006 mouse coordinates
+Note that calling ```make libs``` will export the libraries into the src/ directory.
-0.1.0: BETA RELEASE
+## Author
-- TSpinner
-- TComboBox
-- TListBox
-- TCalendar
-- TColorPicker
-
-Wishlist features (2.0):
-
-- TTerminal
- - Handle resize events (pass to child process)
-- Screen
- - Allow complex characters in putCharXY() and detect them in putStrXY().
-- Drag and drop
- - TEditor
- - TField
- - TText
- - TTerminal
- - TComboBox
-
-
-Screenshots
------------
-
-
-
-
+Fanfix was written by Niki Roo <niki@nikiroo.be>
git://git.nikiroo.be / fanfix.git / blobdiff