X-Git-Url: http://git.nikiroo.be/?a=blobdiff_plain;ds=sidebyside;f=README.md;h=1ad3339b89830b9d3ed9634b1af94dd6eea4ef9a;hb=aa08cbd2ee36a83cae1b18251059594e74438265;hp=3aaad98c539a38e108f4eabf224250e38961f616;hpb=0a141b558810dc76fd02562ef9154b0bf2320e6c;p=fanfix.git
diff --git a/README.md b/README.md
index 3aaad98..1ad3339 100644
--- a/README.md
+++ b/README.md
@@ -1,214 +1,158 @@
-Jexer - Java Text User Interface library
-========================================
+English [Français](README-fr.md)
-This library implements a text-based windowing system loosely
-reminiscent of Borland's [Turbo
-Vision](http://en.wikipedia.org/wiki/Turbo_Vision) system. It looks
-like this:
+# Fanfix
-![Terminal, Image, Table](/screenshots/new_demo1.png?raw=true "Terminal, Image, Table")
+Fanfix is a small Java program that can download stories from some supported websites and render them offline.
-Jexer works on both Xterm-like terminals and Swing, and supports
-images in both Xterm and Swing. On Swing, images are true color:
+## ð´ This is the command line and server program
-![Swing Snake Image](/screenshots/snake_swing.png?raw=true "Swing Snake Image")
+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/)
-On Xterm, images are dithered to a common palette:
+## Synopsis
-![Xterm Snake Image](/screenshots/snake_xterm.png?raw=true "Xterm Snake Image")
+- ```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
+## 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.)
-License
--------
+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...).
-Jexer is available to all under the MIT License. See the file LICENSE
-for the full license text.
+To help organize your stories, it can also work as a local library so you can:
+- 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)
+### Supported websites
-Obtaining Jexer
----------------
+Currently, the following websites are supported:
-Jexer is available on Maven Central:
+- 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)
-```xml
-
- com.gitlab.klamonte
- jexer
- 0.3.2
-
-```
+### Support file types
-Binary releases are available on SourceForge:
-https://sourceforge.net/projects/jexer/files/jexer/
+We support a few file types for local story conversion (both as input and as output):
-The Jexer source code is hosted at: https://gitlab.com/klamonte/jexer
+- 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
+Any platform with at lest Java 1.6 on it should be ok.
-1.0.0 Release Coming Soon
---------------------------
+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.
+If you have any problems to compile it with a supported Java version (1.6+), please contact us.
-Jexer's original list of features for its 1.0.0 release are undergoing
-final testing. If you know of a bug or key feature missing, please
-consider opening an issue
-[here.](https://gitlab.com/klamonte/jexer/issues)
+## Options
+You can start the program in two ways:
+- ```java -jar fanfix.jar```
+- ```fanfix``` (if you used *make install*)
-Documentation
--------------
+The following arguments are allowed:
-* [Java API Docs](https://jexer.sourceforge.io/apidocs/api/index.html)
+- ```--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
-* [Wiki](https://gitlab.com/klamonte/jexer/wikis/home)
+### Environment
-* [Jexer web page](https://jexer.sourceforge.io/)
+Some environment variables are recognized by the program:
-* [Development Standards](https://gitlab.com/klamonte/jexer/wikis/dev-standards)
+- ```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)
+## Compilation
+```./configure.sh && make```
-Programming Examples
---------------------
+You can also import the java sources into, say, [Eclipse](https://eclipse.org/), and create a runnable JAR file from there.
-The examples/ folder currently contains:
+There are some unit tests you can run, too:
- * A [prototype tiling window
- manager](/examples/JexerTilingWindowManager.java) in less than 250
- lines of code.
+```./configure.sh && make build test run-test```
- * A much slicker [prototype tiling window
- manager](/examples/JexerTilingWindowManager2.java) in less than 200
- lines of code.
+If you run the unit tests, note that some flag files can impact them:
- * A [prototype image thumbnail
- viewer](/examples/JexerImageViewer.java) in less than 350 lines of
- code.
+- ```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
-jexer.demos contains official demos showing all of the existing UI
-controls. The demos can be run as follows:
+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).
- * 'java -jar jexer.jar' . This will use System.in/out with
- Xterm-like sequences on non-Windows non-Mac platforms. On Windows
- and Mac it will use a Swing JFrame.
+The test files will be:
- * 'java -Djexer.Swing=true -jar jexer.jar' . This will always use
- Swing on any platform.
+- ```test/*.url``` : URL to download in text format, content = URL
+- ```test/*.story```: text mode story, content = story
- * 'java -cp jexer.jar jexer.demos.Demo2 PORT' (where PORT is a
- number to run the TCP daemon on). This will use the Xterm backend
- on a telnet server that will update with screen size changes.
- * 'java -cp jexer.jar jexer.demos.Demo3' . This will use
- System.in/out with Xterm-like sequences. One can see in the code
- how to pass a different InputReader and OutputReader to
- TApplication, permitting a different encoding than UTF-8.
+### Dependant libraries (included)
- * 'java -cp jexer.jar jexer.demos.Demo4' . This demonstrates hidden
- windows and a custom TDesktop.
+Required:
- * 'java -cp jexer.jar jexer.demos.Demo5' . This demonstrates two
- demo applications using different fonts in the same Swing frame.
+- ```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
- * 'java -cp jexer.jar jexer.demos.Demo6' . This demonstrates two
- applications performing I/O across three screens: an Xterm screen
- and Swing screen, monitored from a third Swing screen.
+Optional:
- * 'java -cp jexer.jar jexer.demos.Demo7' . This demonstrates the
- BoxLayoutManager, achieving a similar result as the
- javax.swing.BoxLayout apidocs example.
+- [```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
+Nothing else but Java 1.6+.
+Note that calling ```make libs``` will export the libraries into the src/ directory.
-More Screenshots
-----------------
+## Author
-Jexer can be run inside its own terminal window, with support for all
-of its features including images and mouse, and more terminals:
+Fanfix was written by Niki Roo
-![Yo Dawg...](/screenshots/jexer_sixel_in_sixel.png?raw=true "Yo Dawg, I heard you like text windowing systems, so I ran a text windowing system inside your text windowing system so you can have a terminal in your terminal.")
-
-Sixel output uses a single palette which works OK for a variety of
-real-world images:
-
-![Sixel Pictures Of Cliffs Of Moher And Buoy](/screenshots/sixel_images.png?raw=true "Sixel Pictures Of Cliffs Of Moher And Buoy")
-
-The color wheel with that palette is shown below:
-
-![Sixel Color Wheel](/screenshots/sixel_color_wheel.png?raw=true "Sixel Color Wheel")
-
-
-
-Terminal Support
-----------------
-
-The table below lists terminals tested against Jexer's Xterm backend:
-
-| Terminal | Environment | Mouse Click | Mouse Cursor | Images |
-| -------------- | ------------------ | ----------- | ------------ | ------ |
-| xterm | X11 | yes | yes | yes |
-| jexer | CLI, X11, Windows | yes | yes | yes |
-| mlterm | X11 | yes | yes | yes |
-| RLogin | Windows | yes | yes | yes |
-| alacritty(3) | X11 | yes | yes | no |
-| gnome-terminal | X11 | yes | yes | no |
-| iTerm2 | Mac | yes | yes | no(5) |
-| kitty(3) | X11 | yes | yes | no |
-| lcxterm(3) | CLI, Linux console | yes | yes | no |
-| mintty | Windows | yes | yes | no(5) |
-| rxvt-unicode | X11 | yes | yes | no(2) |
-| xfce4-terminal | X11 | yes | yes | no |
-| aminal(3) | X11 | yes | no | no |
-| konsole | X11 | yes | no | no |
-| yakuake | X11 | yes | no | no |
-| Windows Terminal(6) | Windows | no | no | no(2) |
-| screen | CLI | yes(1) | yes(1) | no(2) |
-| tmux | CLI | yes(1) | yes(1) | no |
-| putty | X11, Windows | yes | no | no(2) |
-| Linux | Linux console | no | no | no(2) |
-| qodem(3) | CLI, Linux console | yes | yes(4) | no |
-| qodem-x11(3) | X11 | yes | no | no |
-| yaft | Linux console (FB) | no | no | yes |
-
-1 - Requires mouse support from host terminal.
-
-2 - Also fails to filter out sixel data, leaving garbage on screen.
-
-3 - Latest in repository.
-
-4 - Requires TERM=xterm-1003 before starting.
-
-5 - Sixel images can crash terminal.
-
-6 - Version 0.7.3291.0, on Windows 10.0.18362.30. Tested against
- WSL-1 Debian instance.
-
-
-
-See Also
---------
-
-* [Tranquil Java IDE](https://tjide.sourceforge.io) is a TUI-based
- integrated development environment for the Java language that was
- built using a very lightly modified GPL version of Jexer. TJ
- provided a real-world use case to shake out numerous bugs and
- limitations of Jexer.
-
-* [LCXterm](https://lcxterm.sourceforge.io) is a curses-based terminal
- emulator that allows one to use Jexer with full support on the raw
- Linux console.
-
-* [ptypipe](https://gitlab.com/klamonte/ptypipe) is a small C utility
- that permits a Jexer TTerminalWindow to resize the running shell
- when its window is resized.
-
-
-
-Acknowledgements
-----------------
-
-Jexer makes use of the Terminus TrueType font [made available
-here](http://files.ax86.net/terminus-ttf/) .