fix content type for cover
[nikiroo-utils.git] / README.md
CommitLineData
10ccd649 1English [Français](README-fr.md)
eab9e01c 2
08fe2e33 3# Fanfix
de610c82 4
36142555 5Fanfix is a small Java program that can download stories from some supported websites and render them offline.
08fe2e33 6
fccaa18a
NR
7## 🔴 This is the command line and server program
8
9You can also use:
10- the graphical client [Fanfix-swing](https://github.com/nikiroo/fanfix-swing/)
11- the TUI client [Fanfix-jexer](https://github.com/nikiroo/fanfix-jexer/)
de610c82 12
2953f988
NR
13## Synopsis
14
15- ```fanfix``` --import [*URL*]
16- ```fanfix``` --export [*id*] [*output_type*] [*target*]
17- ```fanfix``` --convert [*URL*] [*output_type*] [*target*] (+info)
18- ```fanfix``` --read [*id*] ([*chapter number*])
19- ```fanfix``` --read-url [*URL*] ([*chapter number*])
8b153400
NR
20- ```fanfix``` --search
21- ```fanfix``` --search [*where*] [*keywords*] (page [*page*]) (item [*item*])
8141d7ac
NR
22- ```fanfix``` --search-tag
23- ```fanfix``` --search-tag [*index 1*]... (page [*page*]) (item [*item*])
2953f988 24- ```fanfix``` --list
2953f988
NR
25- ```fanfix``` --server [*key*] [*port*]
26- ```fanfix``` --stop-server [*key*] [*port*]
27- ```fanfix``` --remote [*key*] [*host*] [*port*]
28- ```fanfix``` --help
29
42375f55
NR
30## Description
31
eab9e01c
NR
32(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.)
33
de610c82 34This 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...).
88c61aca 35
6ee59de8 36To help organize your stories, it can also work as a local library so you can:
42375f55 37
373da363
NR
38- Import a story from its URL (or just from a file)
39- Export a story to a file (in any of the supported output types)
333f0e7b 40- Display a story from the local library in text format in the console
de610c82 41- 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)
88c61aca 42
2953f988 43### Supported websites
88c61aca
NR
44
45Currently, the following websites are supported:
42375f55 46
88c61aca
NR
47- http://FimFiction.net/: fan fictions devoted to the My Little Pony show
48- http://Fanfiction.net/: fan fictions of many, many different universes, from TV shows to novels to games
413bcc29 49- http://mangahub.io/: a well filled repository of mangas (English)
88c61aca 50- https://e621.net/: a Furry website supporting comics, including MLP
3968a05a 51- https://sofurry.com/: same thing, but story-oriented
6ee59de8 52- https://e-hentai.org/: done upon request (so, feel free to ask for more websites!)
dad7b76c 53- http://mangas-lecture-en-ligne.fr/: a website offering a lot of mangas (in French)
88c61aca 54
2953f988 55### Support file types
88c61aca
NR
56
57We support a few file types for local story conversion (both as input and as output):
42375f55 58
88c61aca
NR
59- epub: .epub files created by this program (we do not support "all" .epub files, at least for now)
60- text: local stories encoded in plain text format, with a few specific rules:
42375f55
NR
61 - the title must be on the first line
62 - 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)```)
63 - chapters must be declared with ```Chapter x``` or ```Chapter x: NAME OF THE CHAPTER```, where ```x``` is the chapter number
64 - a description of the story must be given as chapter number 0
65 - a cover image may be present with the same filename as the story, but a .png, .jpeg or .jpg extension
88c61aca
NR
66- 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)
67- cbz: .cbz (collection of images) files, preferably created with Fanfix (but any .cbz file is supported, though without most of Fanfix metadata, obviously)
eab9e01c 68- 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
08fe2e33 69
2953f988 70### Supported platforms
08fe2e33 71
301791d3 72Any platform with at lest Java 1.6 on it should be ok.
08fe2e33 73
eab9e01c 74It 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.
b4dc6ab5 75
eab9e01c 76If you have any problems to compile it with a supported Java version (1.6+), please contact us.
08fe2e33 77
2953f988 78## Options
08fe2e33 79
e4672e67 80You can start the program in two ways:
42375f55 81
88c61aca 82- ```java -jar fanfix.jar```
2953f988 83- ```fanfix``` (if you used *make install*)
88c61aca 84
e4672e67 85The following arguments are allowed:
42375f55 86
88c61aca
NR
87- ```--import [URL]```: import the story at URL into the local library
88- ```--export [id] [output_type] [target]```: export the story denoted by ID to the target file
89- ```--convert [URL] [output_type] [target] (+info)```: convert the story at URL into target, and force-add the .info and cover if +info is passed
90- ```--read [id] ([chapter number])```: read the given story denoted by ID from the library
eab9e01c 91- ```--read-url [URL] ([chapter number])```: convert on the fly and read the story at URL, without saving it
8b153400
NR
92- ```--search```: list the supported websites (```where```)
93- ```--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
94- ```--tag [where]```: list all the tags supported by this website
95- ```--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
88c61aca 96- ```--list```: list the stories present in the library and their associated IDs
eab9e01c 97- ```--server [key] [port]```: start a story server on this port
42375f55 98- ```--stop-server [key] [port]```: stop the remote server running on this port (key must be set to the same value)
eab9e01c 99- ```--remote [key] [host] [port]```: contact this server instead of the usual library (key must be set to the same value)
88c61aca 100- ```--help```: display the available options
eab9e01c 101- ```--version```: return the version of the program
08fe2e33 102
2953f988 103### Environment
08fe2e33 104
88c61aca 105Some environment variables are recognized by the program:
42375f55 106
eab9e01c 107- ```LANG=en```: force the language to English
88c61aca
NR
108- ```CONFIG_DIR=$HOME/.fanfix```: use the given directory as a config directory (and copy the default configuration if needed)
109- ```NOUTF=1```: try to fallback to non-unicode values when possible (can have an impact on the resulting files, not only on user messages)
adc71d36 110- ```DEBUG=1```: force the ```DEBUG=true``` option of the configuration file (to show more information on errors)
08fe2e33
NR
111
112## Compilation
113
88c61aca 114```./configure.sh && make```
08fe2e33 115
36142555 116You can also import the java sources into, say, [Eclipse](https://eclipse.org/), and create a runnable JAR file from there.
08fe2e33 117
9f8f013a
NR
118There are some unit tests you can run, too:
119
120```./configure.sh && make build test run-test```
121
966d6260
NR
122If you run the unit tests, note that some flag files can impact them:
123
124- ```test/VERBOSE``` : enable verbose mode
125- ```test/OFFLINE``` : to forbid any downloading
126- ```test/URLS``` : to allow testing URLs
127- ```test/FORCE_REFRESH```: to force a clear of the cache
128
129Note 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).
130
131The test files will be:
132
133- ```test/*.url``` : URL to download in text format, content = URL
134- ```test/*.story```: text mode story, content = story
135
136
08fe2e33
NR
137### Dependant libraries (included)
138
2953f988
NR
139Required:
140
141- ```libs/nikiroo-utils-sources.jar```: some shared utility functions
142- [```libs/unbescape-sources.jar```](https://github.com/unbescape/unbescape): a nice library to escape/unescape a lot of text formats; used here for HTML
143- [```libs/jsoup-sources.jar```](https://jsoup.org/): a library to parse HTML
82f6ca77 144- [```libs/JSON-java-20190722-sources.jar```](https://github.com/stleary/JSON-java): a library to parse JSON
2953f988
NR
145
146Optional:
147
148- [```libs/jexer-sources.jar```](https://github.com/klamonte/jexer): a small library that offers TUI widgets
149- [```pandoc```](http://pandoc.org/): to generate the man pages from the README files
08fe2e33 150
301791d3 151Nothing else but Java 1.6+.
08fe2e33 152
88c61aca 153Note that calling ```make libs``` will export the libraries into the src/ directory.
08fe2e33 154
42375f55
NR
155## Author
156
157Fanfix was written by Niki Roo <niki@nikiroo.be>
158