mirror of
https://github.com/kovidgoyal/calibre.git
synced 2025-06-23 15:30:45 -04:00
Switch the user manual to use the Sphinx documentation framework
This commit is contained in:
Kovid Goyal
parent
ffeb7fdd6f
commit
f2d43cd6d8
66
src/libprs500/manual/Makefile
Normal file
66
src/libprs500/manual/Makefile
Normal file
@ -0,0 +1,66 @@
|
||||
# Makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line.
|
||||
SPHINXOPTS =
|
||||
SPHINXBUILD = sphinx-build.py
|
||||
PAPER =
|
||||
|
||||
ALLSPHINXOPTS = -d .build/doctrees -D latex_paper_size=$(PAPER) \
|
||||
$(SPHINXOPTS) .
|
||||
|
||||
.PHONY: help clean html web htmlhelp latex changes linkcheck
|
||||
|
||||
help:
|
||||
@echo "Please use \`make <target>' where <target> is one of"
|
||||
@echo " html to make standalone HTML files"
|
||||
@echo " web to make files usable by Sphinx.web"
|
||||
@echo " htmlhelp to make HTML files and a HTML help project"
|
||||
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
|
||||
@echo " changes to make an overview over all changed/added/deprecated items"
|
||||
@echo " linkcheck to check all external links for integrity"
|
||||
|
||||
clean:
|
||||
-rm -rf .build/*
|
||||
|
||||
html:
|
||||
mkdir -p .build/html .build/doctrees
|
||||
$(SPHINXBUILD) -b custom $(ALLSPHINXOPTS) .build/html
|
||||
@echo
|
||||
@echo "Build finished. The HTML pages are in .build/html."
|
||||
|
||||
web:
|
||||
mkdir -p .build/web .build/doctrees
|
||||
$(SPHINXBUILD) -b web $(ALLSPHINXOPTS) .build/web
|
||||
@echo
|
||||
@echo "Build finished; now you can run"
|
||||
@echo " python -m sphinx.web .build/web"
|
||||
@echo "to start the server."
|
||||
|
||||
htmlhelp:
|
||||
mkdir -p .build/htmlhelp .build/doctrees
|
||||
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) .build/htmlhelp
|
||||
@echo
|
||||
@echo "Build finished; now you can run HTML Help Workshop with the" \
|
||||
".hhp project file in .build/htmlhelp."
|
||||
|
||||
latex:
|
||||
mkdir -p .build/latex .build/doctrees
|
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) .build/latex
|
||||
@echo
|
||||
@echo "Build finished; the LaTeX files are in .build/latex."
|
||||
@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
|
||||
"run these through (pdf)latex."
|
||||
|
||||
changes:
|
||||
mkdir -p .build/changes .build/doctrees
|
||||
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) .build/changes
|
||||
@echo
|
||||
@echo "The overview file is in .build/changes."
|
||||
|
||||
linkcheck:
|
||||
mkdir -p .build/linkcheck .build/doctrees
|
||||
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) .build/linkcheck
|
||||
@echo
|
||||
@echo "Link check complete; look for any errors in the above output " \
|
||||
"or in .build/linkcheck/output.txt."
|
||||
137
src/libprs500/manual/conf.py
Normal file
137
src/libprs500/manual/conf.py
Normal file
@ -0,0 +1,137 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
#
|
||||
# calibre documentation build configuration file, created by
|
||||
# sphinx-quickstart.py on Sun Mar 23 01:23:55 2008.
|
||||
#
|
||||
# This file is execfile()d with the current directory set to its containing dir.
|
||||
#
|
||||
# The contents of this file are pickled, so don't put values in the namespace
|
||||
# that aren't pickleable (module imports are okay, they're removed automatically).
|
||||
#
|
||||
# All configuration values have a default value; values that are commented out
|
||||
# serve to show the default value.
|
||||
|
||||
import sys, os
|
||||
|
||||
# If your extensions are in another directory, add it here.
|
||||
sys.path.append(os.path.abspath('../../../'))
|
||||
sys.path.append(os.path.abspath('.'))
|
||||
from libprs500 import __appname__, __version__
|
||||
import custom
|
||||
|
||||
# General configuration
|
||||
# ---------------------
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be extensions
|
||||
# coming with Sphinx (named 'sphinx.addons.*') or your custom ones.
|
||||
extensions = ['custom']
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['.templates']
|
||||
|
||||
# The suffix of source filenames.
|
||||
source_suffix = '.rst'
|
||||
|
||||
# The master toctree document.
|
||||
master_doc = 'index'
|
||||
|
||||
# General substitutions.
|
||||
project = __appname__
|
||||
copyright = '2008, Kovid Goyal'
|
||||
|
||||
# The default replacements for |version| and |release|, also used in various
|
||||
# other places throughout the built documents.
|
||||
#
|
||||
# The short X.Y version.
|
||||
version = __version__
|
||||
# The full version, including alpha/beta/rc tags.
|
||||
release = __version__
|
||||
|
||||
# There are two options for replacing |today|: either, you set today to some
|
||||
# non-false value, then it is used:
|
||||
#today = ''
|
||||
# Else, today_fmt is used as the format for a strftime call.
|
||||
today_fmt = '%B %d, %Y'
|
||||
|
||||
# List of documents that shouldn't be included in the build.
|
||||
unused_docs = ['global']
|
||||
|
||||
master_doc = 'index'
|
||||
|
||||
# If true, '()' will be appended to :func: etc. cross-reference text.
|
||||
#add_function_parentheses = True
|
||||
|
||||
# If true, the current module name will be prepended to all description
|
||||
# unit titles (such as .. function::).
|
||||
#add_module_names = True
|
||||
|
||||
# If true, sectionauthor and moduleauthor directives will be shown in the
|
||||
# output. They are ignored by default.
|
||||
#show_authors = False
|
||||
|
||||
# The name of the Pygments (syntax highlighting) style to use.
|
||||
pygments_style = 'sphinx'
|
||||
|
||||
|
||||
# Options for HTML output
|
||||
# -----------------------
|
||||
|
||||
# The style sheet to use for HTML and HTML Help pages. A file of that name
|
||||
# must exist either in Sphinx' static/ path, or in one of the custom paths
|
||||
# given in html_static_path.
|
||||
html_style = 'default.css'
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
#html_static_path = ['static']
|
||||
|
||||
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
|
||||
# using the given strftime format.
|
||||
html_last_updated_fmt = '%b %d, %Y'
|
||||
|
||||
# If true, SmartyPants will be used to convert quotes and dashes to
|
||||
# typographically correct entities.
|
||||
#html_use_smartypants = True
|
||||
|
||||
# Content template for the index page.
|
||||
#html_index = ''
|
||||
|
||||
# Custom sidebar templates, maps document names to template names.
|
||||
#html_sidebars = {}
|
||||
|
||||
# Additional templates that should be rendered to pages, maps page names to
|
||||
# template names.
|
||||
#html_additional_pages = {}
|
||||
|
||||
# If false, no module index is generated.
|
||||
html_use_modindex = False
|
||||
|
||||
# If true, the reST sources are included in the HTML build as _sources/<name>.
|
||||
html_copy_source = False
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = 'calibredoc'
|
||||
|
||||
|
||||
# Options for LaTeX output
|
||||
# ------------------------
|
||||
|
||||
# The paper size ('letter' or 'a4').
|
||||
latex_paper_size = 'letter'
|
||||
|
||||
# The font size ('10pt', '11pt' or '12pt').
|
||||
latex_font_size = '10pt'
|
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title, author, document class [howto/manual]).
|
||||
#latex_documents = []
|
||||
|
||||
# Additional stuff for the LaTeX preamble.
|
||||
#latex_preamble = ''
|
||||
|
||||
# Documents to append as an appendix to all manuals.
|
||||
#latex_appendices = []
|
||||
|
||||
# If false, no module index is generated.
|
||||
#latex_use_modindex = True
|
||||
6
src/libprs500/manual/conversion.rst
Normal file
6
src/libprs500/manual/conversion.rst
Normal file
@ -0,0 +1,6 @@
|
||||
.. include:: global.rst
|
||||
|
||||
.. _conversion:
|
||||
|
||||
E-book Conversion
|
||||
===================
|
||||
165
src/libprs500/manual/custom.py
Normal file
165
src/libprs500/manual/custom.py
Normal file
@ -0,0 +1,165 @@
|
||||
#!/usr/bin/env python
|
||||
# vim:fileencoding=UTF-8:ts=4:sw=4:sta:et:sts=4:ai
|
||||
|
||||
## Copyright © 2008 <Author> <Email>
|
||||
## This program is free software; you can redistribute it and/or modify
|
||||
## it under the terms of the GNU General Public License as published by
|
||||
## the Free Software Foundation; either version 2 of the License, or
|
||||
## (at your option) any later version.
|
||||
##
|
||||
## This program is distributed in the hope that it will be useful,
|
||||
## but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
## GNU General Public License for more details.
|
||||
##
|
||||
## You should have received a copy of the GNU General Public License along
|
||||
## with this program; if not, write to the Free Software Foundation, Inc.,
|
||||
## 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
|
||||
import shutil, sys, os
|
||||
from sphinx.builder import StandaloneHTMLBuilder, bold
|
||||
from genshi.template import TextTemplate
|
||||
sys.path.append(os.path.abspath('../../../'))
|
||||
from libprs500.linux import entry_points
|
||||
|
||||
class CustomBuilder(StandaloneHTMLBuilder):
|
||||
name = 'custom'
|
||||
|
||||
|
||||
def substitute(app, doctree):
|
||||
pass
|
||||
|
||||
CLI_INDEX = '''\
|
||||
.. include:: ../global.rst
|
||||
||
|
||||
.. _cli:
|
||||
||
|
||||
||
|
||||
Command Line Interface
|
||||
==========================
|
||||
||
|
||||
.. image:: ../images/cli.png
|
||||
||
|
||||
||
|
||||
Documented Commands
|
||||
--------------------
|
||||
||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
||
|
||||
#for cmd, parser in documented_commands
|
||||
$cmd
|
||||
#end
|
||||
||
|
||||
Undocumented Commands
|
||||
-------------------------
|
||||
||
|
||||
#for cmd in undocumented_commands
|
||||
* ${cmd}
|
||||
||
|
||||
#end
|
||||
||
|
||||
You can see usage for undocumented commands by executing them without arguments in a terminal
|
||||
'''
|
||||
|
||||
CLI_CMD=r'''
|
||||
.. include:: ../global.rst
|
||||
||
|
||||
.. _$cmd:
|
||||
||
|
||||
.. role:: mycmdopt(literal)
|
||||
:class: bold
|
||||
||
|
||||
#def option(opt)
|
||||
`${opt.get_opt_string() + ((', '+', '.join(opt._short_opts)) if opt._short_opts else '')}`:mycmdopt:
|
||||
#end
|
||||
$cmd
|
||||
====================================================================
|
||||
||
|
||||
Usage::
|
||||
||
|
||||
$cmdline
|
||||
||
|
||||
#for line in usage
|
||||
#choose
|
||||
#when len(line) > 0
|
||||
$line
|
||||
#end
|
||||
#otherwise
|
||||
||
|
||||
#end
|
||||
#end
|
||||
#end
|
||||
||
|
||||
[options]
|
||||
------------
|
||||
||
|
||||
#for title, desc, options in groups
|
||||
#if title
|
||||
$title
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
||
|
||||
#end
|
||||
#if desc
|
||||
$desc
|
||||
||
|
||||
#end
|
||||
#for opt in options
|
||||
${option(opt)}
|
||||
${opt.help.replace('\n', ' ').replace('%default', str(opt.default)) if opt.help else ''}
|
||||
||
|
||||
#end
|
||||
#end
|
||||
'''
|
||||
|
||||
def cli_docs(info):
|
||||
info(bold('creating CLI documentation...'))
|
||||
documented_cmds = []
|
||||
undocumented_cmds = []
|
||||
|
||||
for script in entry_points['console_scripts']:
|
||||
module = script[script.index('=')+1:script.index(':')].strip()
|
||||
cmd = script[:script.index('=')].strip()
|
||||
module = __import__(module, fromlist=[module.split('.')[-1]])
|
||||
if hasattr(module, 'option_parser'):
|
||||
documented_cmds.append((cmd, getattr(module, 'option_parser')()))
|
||||
else:
|
||||
undocumented_cmds.append(cmd)
|
||||
|
||||
documented_cmds.sort(cmp=lambda x, y: cmp(x[0], y[0]))
|
||||
undocumented_cmds.sort()
|
||||
|
||||
templ = TextTemplate(CLI_INDEX)
|
||||
raw = templ.generate(documented_commands=documented_cmds,
|
||||
undocumented_commands=undocumented_cmds).render()
|
||||
raw = raw.replace('||', '\n')
|
||||
if not os.path.exists('cli'):
|
||||
os.makedirs('cli')
|
||||
open(os.path.join('cli', 'cli-index.rst'), 'wb').write(raw)
|
||||
|
||||
templ = TextTemplate(CLI_CMD)
|
||||
for cmd, parser in documented_cmds:
|
||||
usage = [i for i in parser.usage.replace('%prog', cmd).splitlines()]
|
||||
cmdline = usage[0]
|
||||
usage = usage[1:]
|
||||
usage = [i.replace(cmd, ':command:`%s`'%cmd) for i in usage]
|
||||
groups = [(None, None, parser.option_list)]
|
||||
for grp in parser.option_groups:
|
||||
groups.append((grp.title, grp.description, grp.option_list))
|
||||
|
||||
raw = templ.generate(cmd=cmd, cmdline=cmdline, usage=usage, groups=groups).render()
|
||||
raw = raw.replace('||', '\n').replace('<', '<').replace('>', '>')
|
||||
open(os.path.join('cli', cmd+'.rst'), 'wb').write(raw)
|
||||
|
||||
def generate(app):
|
||||
app.builder.info(bold('copying images to the build tree...'))
|
||||
shutil.rmtree('.build/html/images', True)
|
||||
shutil.copytree('images', '.build/html/images')
|
||||
shutil.rmtree('.build/html/images/.svn', True)
|
||||
shutil.rmtree('.build/html/images/.bzr', True)
|
||||
cli_docs(app.builder.info)
|
||||
|
||||
|
||||
def setup(app):
|
||||
app.add_builder(CustomBuilder)
|
||||
app.connect('doctree-read', substitute)
|
||||
app.connect('builder-inited', generate)
|
||||
121
src/libprs500/manual/faq.rst
Normal file
121
src/libprs500/manual/faq.rst
Normal file
@ -0,0 +1,121 @@
|
||||
.. include:: global.rst
|
||||
|
||||
.. _faq:
|
||||
|
||||
Frequently Asked Questions
|
||||
==========================
|
||||
|
||||
.. contents:: Contents
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
E-book Format Conversion
|
||||
-------------------------
|
||||
.. contents:: Contents
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
What formats does |app| support conversion to/from?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|app| supports the conversion of the following formats to LRF: HTML, LIT, MOBI, PRC, EPUB, RTF, TXT, PDF and LRS. It also supports the conversion of LRF to LRS and HTML. Note that libprs500 does not support the conversion of DRMed ebooks.
|
||||
|
||||
What are the best formats to convert to LRF?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
In order of decreasing preference: LIT, MOBI, HTML, PRC, RTF, TXT, PDF
|
||||
|
||||
Why does the PDF conversion lose some images?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
The PDF conversion tries to extract the text and images from the PDF file and convert them to and HTML based ebook. Some PDF files have images in a format that cannot be extracted (vector images).
|
||||
|
||||
There are no images in the LRF file after conversion from HTML?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
If you use the GUI to convert an HTML file, you have to create a zip file with the HTML file and any images it references and then convert that ZIP file to LRF.
|
||||
|
||||
How do I convert my file containing non-English characters?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
There are two aspects to this problem:
|
||||
1. Knowing the encoding of the source file: |app| tries to guess what character encoding your source files use, but often, this is impossible, so you need to tell it what encoding to use. This can be done in the GUI via the :guilabel:`Source encoding` field in the :guilabel:`Look & Feel` section. The command-line tools all have an :option:`--encoding` option.
|
||||
2. Embedding fonts: If you are generating an LRF file to read on your SONY Reader, you are limited by the fact that the Reader only supports a few non-English characters in the fonts it comes pre-loaded with. You can work around this problem by embedding a unicode-aware font that supports the character set your file uses into the LRF file. You should embed atleast a serif and a sans-serif font. Be aware that embedding fonts significantly slows down page-turn speed on the reader.
|
||||
|
||||
|
||||
How do I use some of the advanced features of the conversion tools?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
You can get help on any individual feature of the converters by mousing over it in the GUI or running ``html2lrf --help`` at a terminal. A good place to start is to look at the following demo files that demonstrate some of the advanced features:
|
||||
* `html-demo.zip <http://libprs500.kovidgoyal.net/downloads/html-demo.zip>`_
|
||||
* `txt-demo.zip <http://libprs500.kovidgoyal.net/downloads/txt-demo.zip>`_
|
||||
|
||||
|
||||
Device Integration
|
||||
-------------------
|
||||
|
||||
.. contents:: Contents
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
What devices does |app| support?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
At the moment |app| has full support for the SONY PRS500 and PRS505. However, using the :guilabel:`Save to disk` function you can use it with any ebook reader that exports itself as a USB disk.
|
||||
|
||||
I used |app| to transfer some books to my reader, and now the SONY software hangs every time I connect the reader?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
You should not use both |app| and Connect to transfer books to the reader. You can fix this problem by:
|
||||
* Removing any storage cards from your reader.
|
||||
* Deleting the file media.xml from the reader's main memory using windows explorer (search for the file to find all locations where it is present). Note that by doing this you will lose all your collections, bookmarks, history etc.
|
||||
* Unplugging the reader and waiting till the list of books shows up again
|
||||
* Re-connecting the reader and starting the SONY software
|
||||
|
||||
Library Management
|
||||
------------------
|
||||
|
||||
.. contents:: Contents
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
What formats does |app| read metadata from?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|app| reads metadata from the following formats: LRF, PDF, LIT, RTF, OPF, MOBI, PRC, EPUB. In addition it can write metadata to: LRF, RTF, OPF
|
||||
|
||||
Where are the book files stored?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
When you import books into the library, they are stored in a database. The database location can be found out by clicking the configuration button (The button with the icon of a hammer next to the search bar).
|
||||
|
||||
Can I save my books to the disk?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
You can save your books to the disk by selecting the books and clicking the "Save to disk" button. Your books will be saved in nicely organized folders.
|
||||
|
||||
Content From The Web
|
||||
---------------------
|
||||
.. contents:: Contents
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
I want |app| to download news from my favorite news website.
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
If you are reasonably proficient with computers, you can teach |app| to download news from any website of your choosing. To learn how to do this see :ref:`news`.
|
||||
|
||||
Otherwise, you can register a request for a particular news site by adding a comment `here <http://libprs500.kovidgoyal.net/ticket/405>`_.
|
||||
|
||||
Can I use web2lrf to download an arbitrary website?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
``web2lrf --url http://mywebsite.com default``
|
||||
|
||||
Miscellaneous
|
||||
--------------
|
||||
|
||||
.. contents:: Contents
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
Why does |app| show only some of my fonts on OS X?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|app| embeds fonts in ebook files it creates. E-book files support embedding only TrueType (.ttf) fonts. Most fonts on OS X systems are in .dfont format, thus they cannot be embedded. |app| shows only TrueType fonts founf on your system. You can obtain many TrueType fonts on the web. Simply download the .ttf files and add them to the Library/Fonts directory in your home directory.
|
||||
|
||||
The graphical user interface of |app| is not starting on Windows?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
If you've never used the graphical user interface before, try deleting the file library1.db (it will be somewhere under :file:`C:\\Documents and Settings` on Windows XP and :file:`C:\\Users` on Windows Vista. If that doesn't fix the problem, locate the file libprs500.log (in the same places as library1.db) and post its contents in a help message on the `Forums <http://libprs500.kovidgoyal.net/discussion>`_.
|
||||
|
||||
I want some feature added to |app|. What can I do?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
You have two choices:
|
||||
1. Create a patch by hacking on |app| and send it to me for review and inclusion. See `Development <http://libprs500.kovidgoyal.net/wiki/Development>`_.
|
||||
2. `Open a ticket <http://libprs500.kovidgoyal.net/newticket>`_ (you have to register and login first) and hopefully I will find the time to implement your feature.
|
||||
1
src/libprs500/manual/global.rst
Normal file
1
src/libprs500/manual/global.rst
Normal file
@ -0,0 +1 @@
|
||||
.. |app| replace:: libprs500
|
||||
255
src/libprs500/manual/gui.rst
Normal file
255
src/libprs500/manual/gui.rst
Normal file
@ -0,0 +1,255 @@
|
||||
.. include:: global.rst
|
||||
|
||||
.. _gui:
|
||||
|
||||
The Grahical User Interface
|
||||
============================
|
||||
|
||||
The Graphical User Interface *(GUI)* provides access to all
|
||||
library management and ebook format conversion features. The basic workflow
|
||||
for using |app| is to first add books to the library from your hard disk.
|
||||
|app| will automatically try to read metadata from the books and add them
|
||||
to its internal database. Once they are in the database, you can performa various
|
||||
:ref:`actions` on them that include conversion from one format to another,
|
||||
transfer to the reading device, viewing on your computer, editing metadata, including covers, etc.
|
||||
|
||||
The interface is divided into various sections:
|
||||
|
||||
.. contents::
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
.. _actions:
|
||||
|
||||
Actions
|
||||
--------
|
||||
|
||||
.. image:: images/actions.png
|
||||
:alt: The Actions Toolbar
|
||||
|
||||
The actions toolbar provides convenient shortcuts to commonly used actions. Most of the action buttons have little arrows next to them. By clicking the arrows, you can perform variations on the default action.
|
||||
|
||||
.. contents::
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
.. _add_books:
|
||||
|
||||
|adbi| Add books
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
.. |adbi| image:: images/add_books.png
|
||||
:align: middle
|
||||
|
||||
The :guilabel:`Add books` action has three variations, accessed by the arrow next to the button.
|
||||
|
||||
|
||||
1. **Add books from a single directory**: Opens a file chooser dialog and allows you to specify which books in a directory should be added. This action is *context sensitive*, i.e. it depends on which :ref:`catalog <catalogs>` you have selected. If you have selected the :guilabel:`Library`, books will be added to the library. If you have selected the ebook reader device, the books will be uploaded to the device, and so on.
|
||||
|
||||
2. **Add books recursively (One book per directory)**: Allows you to choose a directory. The directory and all its sub-directories are scanned recursively and any ebooks found are added to the library.The algorithm assumes that each directory contains a single book. All ebook files in a directory are assumedto be the same book in different formats. This action is the inverse of the :ref:`Save to disk <save_to_disk_multiple>` action, i.e. you can :guilabel:`Save to disk`, delete the books and re-add them with no lost information (except date).
|
||||
|
||||
3. **Add books recursively (Multiple books per directory)**: Allows you to choose a directory. The directory and all its sub-directories are scanned recursively and any ebooks found are added to the library.The algorithm assumes that each directory contains many books. All ebook files with the same name in a directory are assumed to be the same book in different formats. This action is the inverse of the :ref:`Save to disk <save_to_disk_single>` action, i.e. you can :guilabel:`Save to disk`, delete the books and re-add them with no lost information (except date).
|
||||
|
||||
|
||||
The :guilabel:`Add books` action can read metadata from the following ebook formats: ``LRF, EPUB, LIT, MOBI, RTF, PDF, PRC, HTML``. In addition it tries to guess metadata from the filename. See the :ref:`config_filename_metadata` section, to learn how to configure this.
|
||||
|
||||
To add a new format to an existing book, use the :ref:`edit_meta_information` action.
|
||||
|
||||
.. _remove_books:
|
||||
|
||||
|rbi| Remove books
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
.. |rbi| image:: images/remove_books.png
|
||||
:align: middle
|
||||
|
||||
The :guilabel:`Remove books` action deletes books permanently, so use it with care. It is *context sensitive*, i.e. it depends on which :ref:`catalog <catalogs>` you have selected. If you have selected the :guilabel:`Library`, books will be removed from the library. If you have selected the ebook reader device, the books will be removed from the device. To remove only a particular format for a given book use the :ref:`edit_meta_information` action.
|
||||
|
||||
.. _edit_meta_information:
|
||||
|
||||
|emii| Edit meta information
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
.. |emii| image:: images/edit_meta_information.png
|
||||
:align: middle
|
||||
|
||||
|
||||
The :guilabel:`Edit meta information` action has two variations, accessed by the arrow next to the button.
|
||||
|
||||
1. **Edit metadata individually**: This allows you to edit the metadata of books one-by-one, with the option of fetching metadata, including covers from the internet. It also allows you to add/remove particular ebook formats from a book. For more detail see :ref:`metadata`.
|
||||
|
||||
2. **Edit metadata in bulk**: This allows you to edit common metadata fields for large numbers of books simulataneously. It operates on all the books you have selected in the :ref:`Library view <search_sort>`.
|
||||
|
||||
.. _send_to_device:
|
||||
|
||||
|stdi| Send to device
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
.. |stdi| image:: images/send_to_device.png
|
||||
:align: middle
|
||||
|
||||
The :guilabel:`Send to device` action has two variations, accessed by the arrow next to the button.
|
||||
|
||||
1. **Send to main memory**: The selected books are transferred to the main memory of the ebook reader.
|
||||
2. **Send to card**: The selected books are transferred to the storage card on the ebook reader.
|
||||
|
||||
.. _save_to_disk:
|
||||
|
||||
|svdi| Save to disk
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
.. |svdi| image:: images/save_to_disk.png
|
||||
:align: middle
|
||||
|
||||
The :guilabel:`Save to disk` action has two variations, accessed by the arrow next to the button.
|
||||
|
||||
.. _save_to_disk_multiple:
|
||||
|
||||
1. **Save to disk**: This will save the selected books to disk organized in directories. The directory structure looks like::
|
||||
|
||||
Author
|
||||
Title
|
||||
Book Files
|
||||
|
||||
.. _save_to_disk_single:
|
||||
|
||||
2. **Save to disk in a single directory**: The selected books are saved to disk in a single directory.
|
||||
|
||||
All available formats as well as metadata is stored to disk for each selected book. Metadata is stored in an OPF file.
|
||||
|
||||
Saved books can be re-imported to the library without any loss of information by using the :ref:`Add books <add_books>` action.
|
||||
|
||||
.. _fetch_news:
|
||||
|
||||
|fni| Fetch news
|
||||
~~~~~~~~~~~~~~~~~
|
||||
.. |fni| image:: images/fetch_news.png
|
||||
:align: middle
|
||||
|
||||
The :guilabel:`Fetch news` action downloads news from various websites and converts it into an ebook that can be read on your ebook reader. Normally, the newly created ebook is added to your ebook library, but if an ebook reader is connected at the time the download finishes, the news is uploaded to the reader directly.
|
||||
|
||||
The :guilabel:`Fetch news` action uses simple recipes (10-15 lines of code) for each news site. To learn how to create recipes for your own news sources, see :ref:`news`.
|
||||
|
||||
.. _convert_ebooks:
|
||||
|
||||
|cei| Convert e-books
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
.. |cei| image:: images/convert_ebooks.png
|
||||
:align: middle
|
||||
|
||||
Ebooks can be converted from a number of formats into the LRF format (for the SONY Reader). Note that ebooks you purchase will typically have `Digital Rights Management <http://en.wikipedia.org/wiki/Digital_rights_management>` *(DRM)*. |app| will not convert these ebooks. For many DRM formats, it is easy to remove the DRM, but as this is illegal, you have to find tools to liberate your books yourself and then use |app| to convert them.
|
||||
|
||||
For most people, conversion should be a simple 1-click affair. But if you want to learn more about the conversion process, see :ref:`conversion`.
|
||||
|
||||
The :guilabel:`Convert E-books` action has three variations, accessed by the arrow next to the button.
|
||||
|
||||
1. **Convert individually**: This will allow you to specify conversion options to customize the conversion of each selected ebook.
|
||||
|
||||
2. **Bulk convert**: This allows you to specify options only once to convert a number of ebooks in bulk.
|
||||
|
||||
3. **Set conversion defaults**: Allows you to set the default settings for future conversions.
|
||||
|
||||
.. _view:
|
||||
|
||||
|vi| View
|
||||
~~~~~~~~~~~
|
||||
.. |vi| image:: images/view.png
|
||||
:align: middle
|
||||
|
||||
The :guilabel:`View` action displays the book in an ebook viewer program. |app| has a builtin viewer for the LRF format. For other formats it uses the default operating system application. If a book has more than one format, you can view a particular format by clicking the arrow next to the :guilabel:`View` button.
|
||||
|
||||
.. _catalogs:
|
||||
|
||||
Catalogs
|
||||
----------
|
||||
.. image:: images/catalogs.png
|
||||
|
||||
A *catalog* is a collection of books. |app| can manage three different catalogs:
|
||||
|
||||
1. **Library**: This is a collection of books stored in a database file on your computers harddisk.
|
||||
|
||||
2. **Reader**: This is a collection of books stored in the main memory of your ebook reader. It will be available when you connect the reader to your computer.
|
||||
|
||||
3. **Card**: This is a collection of books stored on the storage card in your reader. Note that ${app} supports only a single storage card at a time.
|
||||
|
||||
.. _search_sort:
|
||||
|
||||
Search & Sort
|
||||
---------------
|
||||
.. image:: images/search_sort.png
|
||||
|
||||
The Search & Sort section allows you to perform several powerful actions on your book collections.
|
||||
|
||||
* You can sort them by title, author, date, rating etc. by clicking on the column titles.
|
||||
|
||||
* You can search for a particular book or set of books using the search bar. More on that below.
|
||||
|
||||
* You can quickly and conveniently edit metadata by double-clicking the entry you want changed in the list.
|
||||
|
||||
* You can perform :ref:`actions` on sets to books. To select multiple books you can either:
|
||||
|
||||
- Keep the :kbd:`Ctrl` key pressed and click on the books you want selected.
|
||||
|
||||
- Keep the :kbd:`Shift` key pressed and click on the starting and ending book of arange of books you want selected.
|
||||
|
||||
* You can configure which fields you want displayed by using the :ref:`configuration` dialog.
|
||||
|
||||
.. _search_interface:
|
||||
|
||||
The Search Interface
|
||||
---------------------
|
||||
You can search all the metadata by entering search terms in the search bar. Searches are case insensitive. For example::
|
||||
|
||||
Asimov Foundation format:lrf
|
||||
|
||||
This will match all books in your library that have ``Asimov`` and ``Foundation`` in their metadata and are available in the LRF format. You can build advanced search queries easily using the :guilabel:`Advanced Search Dialog`, accessed by clicking the button |sbi|.
|
||||
|
||||
.. |sbi| image:: images/search_button.png
|
||||
:align: middle
|
||||
|
||||
.. figure:: images/search.png
|
||||
|
||||
:guilabel:`Advanced Search Dialog`
|
||||
|
||||
You can search on individual fields as shown. The "Negate" checkbox implies that only results that do not match the search expression will be returned. You can require all the search criteria to match or any of them.
|
||||
|
||||
.. _configuration:
|
||||
|
||||
Configuration
|
||||
---------------
|
||||
The configuration dialog allows you to set some global defaults used by all of |app|. To access it, click the |cbi|.
|
||||
|
||||
.. |cbi| image:: images/configuration.png
|
||||
|
||||
.. _config_filename_metadata:
|
||||
|
||||
Guessing metadata from file names
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
In the :guilabel:`Advanced` section of the configuration dialog, you can specify a regularexpression that |app| will use to try and guess metadata from the names of ebook files
|
||||
that you add to the library. The default regular expression is::
|
||||
|
||||
title - author
|
||||
|
||||
i.e., it will assumes that all character up to the first ``-`` are the title of the book and subsequent characters are the author of the book. For example, the filename::
|
||||
|
||||
Foundation and Earth - Isaac Asimov.txt
|
||||
|
||||
will be interpreted to have the title: Foundation and Earth and author: Isaac Asimov
|
||||
|
||||
.. tip::
|
||||
If the filename does not contain the hyphen, the regular expression will fail.
|
||||
|
||||
.. _book_details:
|
||||
|
||||
Book Details
|
||||
-------------
|
||||
.. image:: images/book_details.png
|
||||
|
||||
The Book Details display shows you extra information and the cover for the currently selected book.
|
||||
|
||||
.. _jobs:
|
||||
|
||||
Jobs
|
||||
-----
|
||||
.. image:: images/jobs.png
|
||||
|
||||
The Jobs panel shows you the number of currently running jobs. Jobs are tasks that run in a separate process, they include converting ebooks and talking to your reader device. You can click on the jobs panel to access the list of jobs. Once a job has completed, by double-clicking it in the list, you can see a detailed log from that job. This is useful to debug jobs that may not have completed successfully.
|
||||
|
||||
|
||||
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 11 KiB After Width: | Height: | Size: 9.4 KiB |
40
src/libprs500/manual/index.rst
Normal file
40
src/libprs500/manual/index.rst
Normal file
@ -0,0 +1,40 @@
|
||||
.. include:: global.rst
|
||||
===============================================
|
||||
|app| User Manual
|
||||
===============================================
|
||||
|
||||
|app| is an e-book library manager. It can view, convert and catalog e-books in most of the major e-book formats. It can also talk to a few e-book reader devices. It can go out to the internet and fetch metadata for your books. It can download newspapers and convert them into e-books for convenient reading. It is cross platform, running on Linux, Windows and OS X.
|
||||
|
||||
So you've just started |app|. What do you do now? Well, before |app| can do anything with your ebooks, it first has to know about them. So drag and drop a few ebook files into |app|, or click the "Add books" button and browse for the ebooks you want to work with. Once you've added the books, they will show up in the main view looking something like this:
|
||||
|
||||
.. image:: images/added_books.png
|
||||
|
||||
Once you've admired the list of books you just added to your heart's content, you'll probably want to actually read one. In order to do that you'll have to convert the book to a format your reader understands. For the SONY Reader that's the LRF format. Conversion is a breeze, just select the book you want to convert, and click the "Convert E-book" button. Ignore all the options for now and just click "OK". The little hourglass in the bottom right corner will start spinning. Once it's finished spinning, your converted book is ready. Click to "View" button to read the book.
|
||||
|
||||
Now if you want to read the book on your reader, just connect it to the computer, wait till libprs500 detects it (10-20secs) and then click the "Send to device" button. Once the hourglass stops spinning again, disconnect your reader and read away!
|
||||
|
||||
To get started with more advanced usage, you should read about the :ref:`Graphical User Interface <gui>`. For even more power and versatility, learn the :ref:`Command Line Interface <cli>`.
|
||||
|
||||
You will find the list of :ref:`Frequently Asked Questions <faq>` useful as well.
|
||||
|
||||
Sections
|
||||
------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
gui
|
||||
news
|
||||
conversion
|
||||
metadata
|
||||
cli/cli-index
|
||||
faq
|
||||
|
||||
:ref:`search`
|
||||
------------------------
|
||||
|
||||
:ref:`genindex`
|
||||
---------------------
|
||||
|
||||
|
||||
|
||||
@ -1,236 +0,0 @@
|
||||
#!/usr/bin/env python
|
||||
## Copyright (C) 2008 Kovid Goyal kovid@kovidgoyal.net
|
||||
## This program is free software; you can redistribute it and/or modify
|
||||
## it under the terms of the GNU General Public License as published by
|
||||
## the Free Software Foundation; either version 2 of the License, or
|
||||
## (at your option) any later version.
|
||||
##
|
||||
## This program is distributed in the hope that it will be useful,
|
||||
## but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
## GNU General Public License for more details.
|
||||
##
|
||||
## You should have received a copy of the GNU General Public License along
|
||||
## with this program; if not, write to the Free Software Foundation, Inc.,
|
||||
## 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
|
||||
''''''
|
||||
|
||||
import sys, glob, mechanize, time, subprocess, os, shutil, re
|
||||
from tempfile import NamedTemporaryFile
|
||||
from genshi.template import TemplateLoader, MarkupTemplate
|
||||
|
||||
|
||||
# Load libprs500 from source copy
|
||||
sys.path.insert(1, os.path.dirname(os.path.dirname(os.getcwdu())))
|
||||
|
||||
from libprs500.ebooks.BeautifulSoup import BeautifulSoup
|
||||
from libprs500.linux import entry_points
|
||||
from libprs500 import __appname__, __author__, __version__
|
||||
|
||||
class Template(MarkupTemplate):
|
||||
|
||||
def generate(self, *args, **kwargs):
|
||||
kwdargs = dict(app=__appname__, author=__author__.partition('<')[0].strip(),
|
||||
version=__version__, footer=True)
|
||||
kwdargs.update(kwargs)
|
||||
return MarkupTemplate.generate(self, *args, **kwdargs)
|
||||
|
||||
loader = TemplateLoader(os.path.abspath('templates'), auto_reload=True,
|
||||
variable_lookup='strict', default_class=Template)
|
||||
|
||||
def browser():
|
||||
opener = mechanize.Browser()
|
||||
opener.set_handle_refresh(True)
|
||||
opener.set_handle_robots(False)
|
||||
opener.addheaders = [('User-agent', 'Mozilla/5.0 (X11; U; i686 Linux; en_US; rv:1.8.0.4) Gecko/20060508 Firefox/1.5.0.4')]
|
||||
return opener
|
||||
|
||||
def validate(file=None):
|
||||
br = browser()
|
||||
files = [file] if file is not None else glob.glob('build/*.html')
|
||||
for f in files:
|
||||
print 'Validating', f
|
||||
raw = open(f).read()
|
||||
br.open('http://validator.w3.org/#validate_by_input')
|
||||
br.form = tuple(br.forms())[2]
|
||||
br.form.set_value(raw, id='fragment')
|
||||
res = br.submit()
|
||||
soup = BeautifulSoup(res.read())
|
||||
if soup.find('div', id='result').find(id='congrats') is None:
|
||||
print 'Invalid HTML in', f
|
||||
t = NamedTemporaryFile()
|
||||
t.write(unicode(soup).encode('utf-8'))
|
||||
subprocess.call(('xdg-open', t.name))
|
||||
time.sleep(2)
|
||||
return
|
||||
|
||||
def clean():
|
||||
if os.path.exists('build'):
|
||||
shutil.rmtree('build')
|
||||
return 0
|
||||
|
||||
def compile_help():
|
||||
QTDIR = '/usr/local/Trolltech/Qt-4.4.0-beta1'
|
||||
QTBIN = QTDIR + '/bin'
|
||||
QTLIB = QTDIR + '/lib'
|
||||
QCG = os.path.join(QTBIN, 'qcollectiongenerator')
|
||||
QTA = os.path.join(QTBIN, 'assistant')
|
||||
os.environ['LD_LIBRARY_PATH'] = QTLIB
|
||||
for f in ('build/%s.qch'%__appname__, 'build/%s.qhc'%__appname__):
|
||||
if os.path.exists(f):
|
||||
os.unlink(f)
|
||||
cwd = os.getcwd()
|
||||
os.chdir('build')
|
||||
try:
|
||||
subprocess.check_call((QCG, __appname__+'.qhcp', '-o', __appname__+'.qhc'))
|
||||
subprocess.call((QTA, '-collectionFile', __appname__+'.qhc'))
|
||||
finally:
|
||||
os.chdir(cwd)
|
||||
|
||||
|
||||
def get_subsections(section, level=0, max_level=1, prefix='templates'):
|
||||
src = os.path.join(prefix, section)
|
||||
if not os.path.exists(src):
|
||||
return []
|
||||
soup = BeautifulSoup(open(src, 'rb').read().decode('UTF-8'))
|
||||
toc = soup.find(id='toc')
|
||||
if toc is None:
|
||||
return []
|
||||
return [dict(href=section+a['href'] if a['href'].startswith('#') else a['href'],
|
||||
title=a.string.replace('&', '&'),
|
||||
subsections=get_subsections(a['href'], level=1,
|
||||
prefix=prefix, max_level=max_level) if level<max_level else [])\
|
||||
for a in toc.findAll('a', href=True)]
|
||||
|
||||
def qhp():
|
||||
render()
|
||||
cli_docs()
|
||||
|
||||
toc = get_subsections('start.html', prefix='build')
|
||||
toc.insert(0, dict(title='Start', href='start.html', subsections=[]))
|
||||
files = []
|
||||
for loc in ('*.html', 'images'+os.sep+'*', 'styles'+os.sep+'*'):
|
||||
files += glob.glob(os.path.join('build', loc))
|
||||
files = [i.partition(os.sep)[2] for i in files]
|
||||
|
||||
tpl = loader.load('app.qhp')
|
||||
raw = tpl.generate(toc=toc, files=files).render('xml')
|
||||
open(os.path.join('build', __appname__+'.qhp'), 'wb').write(raw)
|
||||
|
||||
tpl = loader.load('app.qhcp')
|
||||
open(os.path.join('build', __appname__+'.qhcp'), 'wb').write(tpl.generate().render('xml'))
|
||||
about = open('templates'+os.sep+'about.txt', 'rb').read()
|
||||
about = re.sub(r'\$\{app\}', __appname__, about)
|
||||
about = re.sub(r'\$\{author\}', __author__.partition('<')[0].strip(), about)
|
||||
open('build'+os.sep+'about.txt', 'wb').write(about)
|
||||
compile_help()
|
||||
|
||||
def cli_docs():
|
||||
documented_cmds = []
|
||||
undocumented_cmds = []
|
||||
|
||||
for script in entry_points['console_scripts']:
|
||||
module = script[script.index('=')+1:script.index(':')].strip()
|
||||
cmd = script[:script.index('=')].strip()
|
||||
module = __import__(module, fromlist=[module.split('.')[-1]])
|
||||
if hasattr(module, 'option_parser'):
|
||||
documented_cmds.append((cmd, getattr(module, 'option_parser')()))
|
||||
else:
|
||||
undocumented_cmds.append(cmd)
|
||||
|
||||
documented_cmds.sort(cmp=lambda x, y: cmp(x[0], y[0]))
|
||||
undocumented_cmds.sort()
|
||||
|
||||
for cmd, parser in documented_cmds:
|
||||
template = loader.load('cli-cmd.html')
|
||||
open('build/cli-%s.html'%cmd, 'wb').write(
|
||||
template.generate(cmd=cmd, parser=parser).render(doctype='xhtml'))
|
||||
|
||||
documented = [i[0] for i in documented_cmds]
|
||||
template = loader.load('cli-index.html')
|
||||
|
||||
open('build/cli-index.html', 'wb').write(
|
||||
template.generate(documented=documented, undocumented=undocumented_cmds).render(doctype='xhtml'))
|
||||
|
||||
|
||||
def html():
|
||||
toc = get_subsections('start.html', prefix='build')
|
||||
toc.insert(0, dict(title='Start', href='start.html', subsections=[]))
|
||||
template = loader.load('navtree.html')
|
||||
dt = ('html', "-//W3C//DTD HTML 4.01 Transitional//EN",
|
||||
"http://www.w3.org/TR/html4/loose.dtd")
|
||||
raw = template.generate(footer=False, toc=toc).render(doctype=dt)
|
||||
raw = re.sub(r'<html[^<>]+>', '<html lang="en">', raw)
|
||||
raw = re.sub(r'<(script|style)([^<>]+)/>', r'<\1 \2></\1>', raw)
|
||||
raw = re.sub(r'<(link|meta)([^<>]+)/>', r'<\1 \2>', raw)
|
||||
open('build'+os.sep+'navtree.html', 'wb').write(raw)
|
||||
|
||||
|
||||
def render():
|
||||
for d in ('images', 'styles'):
|
||||
tgt = os.path.join('build', d)
|
||||
if not os.path.exists(tgt):
|
||||
os.mkdir(tgt)
|
||||
for f in glob.glob(d+os.sep+'*'):
|
||||
if os.path.isfile(f):
|
||||
ftgt = os.path.join(tgt, os.path.basename(f))
|
||||
if os.path.exists(ftgt):
|
||||
os.unlink(ftgt)
|
||||
os.link(f, ftgt)
|
||||
|
||||
sections = [i['href'] for i in get_subsections('start.html')]
|
||||
sections.remove('cli-index.html')
|
||||
|
||||
for f in sections + ['index.html', 'start.html']:
|
||||
kwdargs = {}
|
||||
if not isinstance(f, basestring):
|
||||
f, kwdargs = f
|
||||
dt = f.rpartition('.')[-1]
|
||||
if dt == 'html':
|
||||
dt = 'xhtml'
|
||||
if f == 'index.html':
|
||||
dt=('html', '-//W3C//DTD XHTML 1.0 Frameset//EN', 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd')
|
||||
|
||||
raw = loader.load(f).generate(**kwdargs).render(doctype=dt)
|
||||
open(os.path.join('build', f), 'wb').write(raw)
|
||||
|
||||
|
||||
def all(opts):
|
||||
clean()
|
||||
os.mkdir('build')
|
||||
qhp()
|
||||
html()
|
||||
if opts.validate:
|
||||
validate()
|
||||
|
||||
return 0
|
||||
|
||||
if __name__ == '__main__':
|
||||
if not os.path.exists('build'):
|
||||
os.mkdir('build')
|
||||
|
||||
from libprs500 import OptionParser
|
||||
parser = OptionParser(usage='%prog [options] target [arguments to target]')
|
||||
parser.add_option('--validate', default=False, action='store_true',
|
||||
help='Validate all HTML files against their DTDs.')
|
||||
opts, args = parser.parse_args()
|
||||
|
||||
if len(args) == 0:
|
||||
clean()
|
||||
sys.exit(all(opts))
|
||||
elif len(args) == 1:
|
||||
func = eval(args[0])
|
||||
fargs = []
|
||||
if args[0] == 'all':
|
||||
fargs = [opts]
|
||||
elif len(args) > 1:
|
||||
func = eval(args[0])
|
||||
fargs = args[1:]
|
||||
if func is None:
|
||||
print >>sys.stderr, 'Unknown target', sys.argv(1)
|
||||
sys.exit(1)
|
||||
else:
|
||||
parser.print_help()
|
||||
sys.exit(1)
|
||||
sys.exit(func(*fargs))
|
||||
|
||||
6
src/libprs500/manual/metadata.rst
Normal file
6
src/libprs500/manual/metadata.rst
Normal file
@ -0,0 +1,6 @@
|
||||
.. include:: global.rst
|
||||
|
||||
.. _metadata:
|
||||
|
||||
Editing E-book Metadata
|
||||
========================
|
||||
6
src/libprs500/manual/news.rst
Normal file
6
src/libprs500/manual/news.rst
Normal file
@ -0,0 +1,6 @@
|
||||
.. include:: global.rst
|
||||
|
||||
.. _news:
|
||||
|
||||
Adding your favorite news website
|
||||
==================================
|
||||
@ -1,67 +0,0 @@
|
||||
body {
|
||||
font-family: sans-serif;
|
||||
background-color: white;
|
||||
}
|
||||
|
||||
a {
|
||||
text-decoration: none;
|
||||
color: blue;
|
||||
}
|
||||
|
||||
a:hover {
|
||||
color: red;
|
||||
}
|
||||
|
||||
a:visited {
|
||||
color: blue;
|
||||
}
|
||||
|
||||
.documentHeading {
|
||||
text-align: center;
|
||||
font-family: monospace;
|
||||
}
|
||||
|
||||
.sectionHeading {
|
||||
font-family: monospace;
|
||||
}
|
||||
|
||||
.subsectionHeading {
|
||||
font-family: monospace;
|
||||
}
|
||||
|
||||
.action {
|
||||
font-family: monospace;
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
.footer {
|
||||
font-size: x-small;
|
||||
color: lightgray;
|
||||
text-align: right;
|
||||
}
|
||||
|
||||
.option {
|
||||
font-family: monospace;
|
||||
color: green;
|
||||
}
|
||||
|
||||
|
||||
.option_table td {
|
||||
padding-bottom : 1em;
|
||||
}
|
||||
|
||||
.cmd {
|
||||
font-family: monospace;
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
.runcmd {
|
||||
background: #eeeeee;
|
||||
border: inset 2px;
|
||||
padding: 0.2em;
|
||||
}
|
||||
|
||||
.cmdlist li {
|
||||
font-family: monospace;
|
||||
margin-bottom: 0.2em;
|
||||
}
|
||||
@ -1 +0,0 @@
|
||||
<b>${app}</b> is an ebook management application with support for various ebook readers. Created by <b>${author}</b> © 2007.
|
||||
@ -1,29 +0,0 @@
|
||||
<?xml version="1.0" encoding="utf-8" ?>
|
||||
<QHelpCollectionProject version="1.0" xmlns:py="http://genshi.edgewall.org/">
|
||||
<assistant>
|
||||
<title>${app} User Manual</title>
|
||||
<startPage>qthelp://${app}/manual/start.html</startPage>
|
||||
<applicationIcon>../../gui2/images/library.png</applicationIcon>
|
||||
<enableFilterFunctionality>false</enableFilterFunctionality>
|
||||
<enableDocumentationManager>false</enableDocumentationManager>
|
||||
<enableAddressBar visible="true">true</enableAddressBar>
|
||||
<aboutMenuText>
|
||||
<text>About ${app}</text>
|
||||
</aboutMenuText>
|
||||
<aboutDialog>
|
||||
<file>about.txt</file>
|
||||
<icon>../../gui2/images/dialog_information.svg</icon>
|
||||
</aboutDialog>
|
||||
</assistant>
|
||||
<docFiles>
|
||||
<generate>
|
||||
<file>
|
||||
<input>${app}.qhp</input>
|
||||
<output>${app}.qch</output>
|
||||
</file>
|
||||
</generate>
|
||||
<register>
|
||||
<file>${app}.qch</file>
|
||||
</register>
|
||||
</docFiles>
|
||||
</QHelpCollectionProject>
|
||||
@ -1,30 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<QtHelpProject version="1.0"
|
||||
xmlns:py="http://genshi.edgewall.org/"
|
||||
>
|
||||
<namespace>${app}</namespace>
|
||||
<virtualFolder>manual</virtualFolder>
|
||||
|
||||
<filterSection>
|
||||
|
||||
<toc>
|
||||
<py:for each="section in toc">
|
||||
<section ref="${section['href']}" title="${section['title']}">
|
||||
<py:for each="ss in section['subsections']">
|
||||
<section ref="${ss['title']}" title="${ss['title']}" />
|
||||
|
||||
</py:for>
|
||||
</section>
|
||||
|
||||
</py:for>
|
||||
</toc>
|
||||
|
||||
<files>
|
||||
<py:for each="file in files">
|
||||
<file>${file}</file>
|
||||
|
||||
</py:for>
|
||||
</files>
|
||||
</filterSection>
|
||||
|
||||
</QtHelpProject>
|
||||
@ -1,47 +0,0 @@
|
||||
<?python
|
||||
from genshi import HTML
|
||||
title = cmd
|
||||
usage = [i for i in parser.usage.replace('%prog', cmd).splitlines(True) if i]
|
||||
cmdline = usage[0]
|
||||
usage = usage[1:]
|
||||
usage = [i.replace(cmd, '<span class="cmd">%s</span>'%cmd) for i in usage]
|
||||
groups = [(None, None, parser.option_list)]
|
||||
for grp in parser.option_groups:
|
||||
groups.append((grp.title, grp.description, grp.option_list))
|
||||
?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
||||
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"
|
||||
xml:lang="en"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xmlns:py="http://genshi.edgewall.org/"
|
||||
|
||||
>
|
||||
<xi:include href="layout.html" />
|
||||
|
||||
<head>
|
||||
<title>${cmd}</title>
|
||||
</head>
|
||||
|
||||
<body>
|
||||
<pre class="runcmd">${cmdline}</pre>
|
||||
<p>
|
||||
<py:for each="line in usage">${HTML(line)}<br /></py:for>
|
||||
</p>
|
||||
<h2 class="sectionHeading">[options]</h2>
|
||||
<table class="option_table">
|
||||
<py:for each="title, desc, options in groups">
|
||||
<tr py:if="title is not None"><th colspan="2"><h3 class="subsectionHeading">${title}</h3></th></tr>
|
||||
<tr py:if="desc is not None"><td colspan="2">${desc}<br /> </td></tr>
|
||||
<tr py:for="option in options">
|
||||
<td class="option" py:with="short = ', '.join(option._short_opts)">
|
||||
${option.get_opt_string()}<br />${short}
|
||||
</td>
|
||||
<td py:with="help = option.help if option.help else ''">${help}</td>
|
||||
</tr>
|
||||
</py:for>
|
||||
</table>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
@ -1,38 +0,0 @@
|
||||
<?python
|
||||
title="Command Line Interface"
|
||||
?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
||||
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"
|
||||
xml:lang="en"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xmlns:py="http://genshi.edgewall.org/"
|
||||
|
||||
>
|
||||
<xi:include href="layout.html" />
|
||||
|
||||
<head>
|
||||
<title>${title}</title>
|
||||
</head>
|
||||
|
||||
<body>
|
||||
<div style="text-align:center"><img src="images/cli.png" alt="CLI" /></div>
|
||||
<p>
|
||||
<b class="cmd">${app}</b> has a very comprehensive command line
|
||||
interface to perform most operations that can be performed by the GUI.
|
||||
</p>
|
||||
<h2 class="sectionHeading">Documented commands</h2>
|
||||
<ul class="cmdlist" id="toc">
|
||||
<li py:for="item in documented">
|
||||
<a href="cli-${item}.html">${item}</a>
|
||||
</li>
|
||||
</ul>
|
||||
<h2 class="sectionHeading">Undocumented commands</h2>
|
||||
<ul class="cmdlist">
|
||||
<li py:for="item in undocumented">${item}</li>
|
||||
</ul>
|
||||
<p>You can see usage for undocumented commands by executing them without arguments in a terminal</p>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
@ -1,153 +0,0 @@
|
||||
<?python
|
||||
title = 'Frequently Asked Questions'
|
||||
?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
||||
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"
|
||||
xml:lang="en"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xmlns:py="http://genshi.edgewall.org/"
|
||||
|
||||
>
|
||||
<xi:include href="layout.html" />
|
||||
|
||||
<head>
|
||||
<title>${title}</title>
|
||||
<style type="text/css">
|
||||
h2 {
|
||||
font-family: monospace;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
|
||||
<body>
|
||||
<div class="toc" id="toc">
|
||||
<ul>
|
||||
<li><a href="#Whatdevicesdoes${app}support">What devices does ${app} support?</a></li>
|
||||
<li><a href="#Whatformatsdoes${app}readmetadatafrom">What formats does ${app} read metadata from?</a></li>
|
||||
<li><a href="#Whatformatsdoes${app}supportconversiontofrom">What formats does ${app} support conversion to/from?</a></li>
|
||||
<li><a href="#WhatarethebestformatstoconverttoLRF">What are the best formats to convert to LRF?</a></li>
|
||||
<li><a href="#WhydoesthePDFconversionlosesomeimages">Why does the PDF conversion lose some images?</a></li>
|
||||
<li><a href="#Wherearethebookfilesstored">Where are the book files stored?</a></li>
|
||||
<li><a href="#CanIsavemybookstothedisk">Can I save my books to the disk?</a></li>
|
||||
<li><a href="#Iused${app}totransfersomebookstomyreaderandnowtheSONYsoftwarehangseverytimeIconnectthereader">I used ${app} to transfer some books to my reader, and now the SONY software hangs every time I connect the reader?</a></li>
|
||||
<li><a href="#NoimagesintheLRFfileafterconversionfromHTML">No images in the LRF file after conversion from HTML?</a></li>
|
||||
<li><a href="#osxfonts">Why does ${app} show only some of my fonts on OS X?</a></li>
|
||||
<li><a href="#unicode">How do I convert my file containing non-English characters?</a></li>
|
||||
<li><a href="#windowsbad">The graphical user interface of ${app} is not starting on Windows?</a></li>
|
||||
<li><a href="#CanIuseweb2lrftodownloadanarbitrarywebsite">Can I use web2lrf to download an arbitrary website?</a></li>
|
||||
<li><a href="#Iwantsomefeatureaddedto${app}.WhatcanIdo">I want some feature added to ${app}. What can I do?</a></li>
|
||||
<li><a href="#HowdoIusesomeoftheadvancedfeaturesoftheconversiontools">How do I use some of the advanced features of the conversion tools?</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<h2 id="Whatdevicesdoes${app}support">What devices does ${app} support?</h2>
|
||||
<p>
|
||||
At the moment ${app} has full support for the SONY PRS500 and PRS505. However, using the "save to disk" function you can use it with any ebook reader that exports itself as a USB disk.
|
||||
</p>
|
||||
|
||||
<h2 id="Whatformatsdoes${app}readmetadatafrom">What formats does ${app} read metadata from?</h2>
|
||||
<p>
|
||||
${app} reads metadata from the following formats: LRF, PDF, LIT, RTF, OPF, MOBI, PRC, EPUB.
|
||||
In addition it can write metadata to: LRF, RTF, OPF
|
||||
</p>
|
||||
<h2 id="Whatformatsdoes${app}supportconversiontofrom">What formats does ${app} support conversion to/from?</h2>
|
||||
<p>
|
||||
${app} supports the conversion of the following formats to LRF: HTML, LIT, MOBI, PRC, EPUB, RTF, TXT, PDF and LRS. It also supports the conversion of LRF to LRS and HTML(upcoming). Note that ${app} does not support the conversion of DRMed ebooks.
|
||||
</p>
|
||||
<h2 id="WhatarethebestformatstoconverttoLRF">What are the best formats to convert to LRF?</h2>
|
||||
<p>
|
||||
In order of decreasing preference: LIT, MOBI, HTML, PRC, RTF, TXT, PDF
|
||||
</p>
|
||||
<h2 id="WhydoesthePDFconversionlosesomeimages">Why does the PDF conversion lose some images?</h2>
|
||||
<p>
|
||||
The PDF conversion tries to extract the text and images from the PDF file and convert them to and HTML based ebook. Some PDF files have images in a format that cannot be extracted (vector images).
|
||||
</p>
|
||||
<h2 id="Wherearethebookfilesstored">Where are the book files stored?</h2>
|
||||
<p>
|
||||
When you import books into the library, they are stored in a database. The database location can be found out by clicking the configuration button (The button with the icon of a hammer next to the search bar).
|
||||
</p>
|
||||
<h2 id="CanIsavemybookstothedisk">Can I save my books to the disk?</h2>
|
||||
<p>
|
||||
You can save your books to the disk by selecting the books and clicking the "Save to disk" button. Your books will be saved in nicely organized folders.
|
||||
</p>
|
||||
<h2 id="Iused${app}totransfersomebookstomyreaderandnowtheSONYsoftwarehangseverytimeIconnectthereader">I used ${app} to transfer some books to my reader, and now the SONY software hangs every time I connect the reader?</h2>
|
||||
<p>
|
||||
You should not use both ${app} and Connect to transfer books to the reader. You can fix this problem by:
|
||||
</p>
|
||||
<ul><li>Removing any storage cards from your reader.
|
||||
</li><li>Deleting the file media.xml from the reader's main memory using windows explorer (search for the file to find all locations where it is present). Note that by doing this you will lose all your collections, bookmarks, history etc.
|
||||
</li><li>Unplugging the reader and waiting till the list of books shows up again
|
||||
</li><li>Re-connecting the reader and starting the SONY software
|
||||
</li></ul>
|
||||
|
||||
<h2 id="NoimagesintheLRFfileafterconversionfromHTML">No images in the LRF file after conversion from HTML?</h2>
|
||||
<p>
|
||||
If you use the GUI to convert an HTML file, you have to create a zip file with the HTML file and any images it references and then convert that ZIP file to LRF.
|
||||
</p>
|
||||
<h2 id="osxfonts">Why does ${app} show only some of my fonts on OS X?</h2>
|
||||
<p>
|
||||
${app} embeds fonts in ebook files it creates. E-book files support embedding only
|
||||
TrueType (.ttf) fonts. Most fonts on OS X systems are in .dfont format, thus they
|
||||
cannot be embedded. ${app} shows only TrueType fonts founf on your system. You can
|
||||
obtain many TrueType fonts on the web. Simply download the .ttf files and add them
|
||||
to the <code>Library/Fonts</code> directory in your home directory.
|
||||
</p>
|
||||
|
||||
<h2 id="unicode">How do I convert my file containing non-English characters?</h2>
|
||||
<p>
|
||||
There are two aspects to this problem:
|
||||
</p>
|
||||
<ol>
|
||||
<li>
|
||||
Knowing the encoding of the source file: ${app} tries to guess what
|
||||
character encoding your source files use, but often, this is impossible,
|
||||
so you need to tell it what encoding to use. This can be done in the GUI
|
||||
via the "Source encoding" field in the "Look & Feel" section.
|
||||
The command-line tools all have an <code>--encoding</code> option.
|
||||
</li>
|
||||
<li>
|
||||
Embedding fonts: If you are generating an LRF file to read on your
|
||||
SONY Reader, you are limited by the fact that the Reader only supports
|
||||
a few non-English characters in the fonts it comes pre-loaded with.
|
||||
You can work around this problem by embedding a unicode-aware font
|
||||
that supports the character set your file uses into the LRF file. You
|
||||
should embed atleast a serif and a sans-serif font. Be aware that
|
||||
embedding fonts significantly slows down page-turn speed on the reader.
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
<h2 id="windowsbad">The graphical user interface of ${app} is not starting on Windows?</h2>
|
||||
<p>
|
||||
If you've never used the graphical user interface before,
|
||||
try deleting the file library1.db (it will be somewhere under C:|Documents and Settings on
|
||||
Windows XP and C:|Users on Windows Vista. If that doesn't fix the problem, locate the file
|
||||
libprs500.log (in the same places as library1.db) and post its contents in a help message on
|
||||
the Forums.
|
||||
</p>
|
||||
|
||||
<h2 id="CanIuseweb2lrftodownloadanarbitrarywebsite">Can I use web2lrf to download an arbitrary website?</h2>
|
||||
<pre class="showcmd">web2lrf --url http://mywebsite.com default</pre>
|
||||
|
||||
<h2 id="Iwantsomefeatureaddedto${app}.WhatcanIdo">I want some feature added to ${app}. What can I do?</h2>
|
||||
<p>
|
||||
You have two choices:
|
||||
</p>
|
||||
<ol>
|
||||
<li>Create a patch by hacking on ${app} and send it to me for review and inclusion. See
|
||||
<a class="wiki" href="http://${app}.kovidgoyal.net/wiki/Development">Development</a>.
|
||||
</li>
|
||||
<li><a href="http://${app}.kovidgoyal.net/newticket">Open a ticket</a> (you have to register and login first) and hopefully I will find the time to implement your feature.
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
<h2 id="HowdoIusesomeoftheadvancedfeaturesoftheconversiontools">How do I use some of the advanced features of the conversion tools?</h2>
|
||||
<p>
|
||||
You can get help on any individual feature of the converters by mousing over it in the GUI or running html2lrf --help at a terminal. A good place to start is to look at the following demo files that demonstrate some of the advanced features:
|
||||
</p>
|
||||
<ul><li><a href="http://${app}.kovidgoyal.net/downloads/html-demo.zip">html-demo.zip</a>
|
||||
</li><li><a href="http://${app}.kovidgoyal.net/downloads/txt-demo.zip">txt-demo.zip</a>
|
||||
</li></ul>
|
||||
</body>
|
||||
|
||||
</html>
|
||||
@ -1,338 +0,0 @@
|
||||
<?python
|
||||
title = 'Graphical User Interface'
|
||||
?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
||||
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"
|
||||
xml:lang="en"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xmlns:py="http://genshi.edgewall.org/"
|
||||
|
||||
>
|
||||
<xi:include href="layout.html" />
|
||||
|
||||
|
||||
<head>
|
||||
<title>${title}</title>
|
||||
</head>
|
||||
|
||||
|
||||
<body>
|
||||
<p>
|
||||
The Graphical User Interface <i>(GUI)</i> provides access to all
|
||||
library management and ebook format conversion features. The basic workflow
|
||||
for using ${app} is to first add books to the library from your hard disk.
|
||||
${app} will automatically try to read metadata from the books and add them
|
||||
to its internal database. Once they are in the database, you can performa various
|
||||
<a href="#actions">actions</a> on them that include conversion from one format to another,
|
||||
transfer to the reading device, viewing on your computer, editing metadata, including covers, etc.
|
||||
</p>
|
||||
<p>
|
||||
The interface is divided into various sections:
|
||||
</p>
|
||||
<ul id="toc">
|
||||
<li><a href="#actions">Actions</a></li>
|
||||
<li><a href="#catalogs">Catalogs</a></li>
|
||||
<li><a href="#search_sort">Search & Sort</a></li>
|
||||
<li><a href="#configuration">Configuration</a></li>
|
||||
<li><a href="#book_details">Book Details</a></li>
|
||||
<li><a href="#jobs">Jobs</a></li>
|
||||
</ul>
|
||||
|
||||
<hr />
|
||||
<h2 class="sectionHeading" id="actions">Actions</h2>
|
||||
<div><img src="images/actions.png" alt="The Actions toolbar"/></div>
|
||||
<p>
|
||||
The actions toolbar provides convenient shortcuts to commonly used actions.
|
||||
Most of the action buttons have little arrows next to them. By clicking the arrows,
|
||||
you can perform slight variations on the defult action.
|
||||
</p>
|
||||
<ul>
|
||||
<li><a href="#add_books">Add books</a></li>
|
||||
<li><a href="#remove_books">Remove books</a></li>
|
||||
<li><a href="#edit_meta_information">Edit meta information</a></li>
|
||||
<li><a href="#send_to_device">Send to device</a></li>
|
||||
<li><a href="#save_to_disk">Save to disk</a></li>
|
||||
<li><a href="#fetch_news">Fetch News</a></li>
|
||||
<li><a href="#convert_ebooks">Convert E-books</a></li>
|
||||
<li><a href="#view">View</a></li>
|
||||
</ul>
|
||||
|
||||
<h3 class="subsectionHeading" id="add_books">
|
||||
<img style="vertical-align: middle" src="images/add_books.png" alt="Add books" />
|
||||
Add books
|
||||
</h3>
|
||||
<p>
|
||||
The <span class="action">Add books</span> action has three variations, accessed by the
|
||||
arrow next to the button.
|
||||
</p>
|
||||
<ul>
|
||||
<li>
|
||||
<b>Add books from a single directory</b>: Opens a file chooser dialog and allows you to
|
||||
specify which books in a directory should be added. This action is <i>context sensitive</i>, i.e.
|
||||
it depends on which <a href="#catalogs">catalog</a> you have selected. If you have selected the
|
||||
library, books will be added to the library. If you have selected the ebook reader device, the books
|
||||
will be uploaded to the device.
|
||||
</li>
|
||||
<li>
|
||||
<b>Add books recursively (One book per directory)</b>: Allows you to choose a directory. The directory and
|
||||
all its sub-directories are scanned recursively and any ebooks found are added to the library. The algorithm
|
||||
assumes that each directory contains a single book. All ebook files in a directory are assumed to be the same book
|
||||
in different formats. This action is the inverse of the <a href="#save_to_disk_multiple">Save to disk</a> action,
|
||||
i.e. you can Save to disk, delete the books and re-add them with no lost information (except Date).
|
||||
</li>
|
||||
<li>
|
||||
<b>Add books recursively (Multiple books per directory)</b>: Allows you to choose a directory. The directory and
|
||||
all its sub-directories are scanned recursively and any ebooks found are added to the library. The algorithm
|
||||
assumes that each directory contains many books. All ebook files with the same name in a directory are assumed to be
|
||||
the same book in different formats. This action is the inverse of the
|
||||
<a href="#save_to_disk_single">Save to disk in a single directory</a> action,
|
||||
i.e. you can Save to disk, delete the books and re-add them with no lost information (except Date).
|
||||
</li>
|
||||
</ul>
|
||||
<p>
|
||||
The <span class="action">Add books</span> action can read metadata from the following ebook formats:
|
||||
<code>LRF, EPUB, LIT, MOBI, RTF, PDF, PRC, HTML</code>. In addition it tries to guess metadata from the filename.
|
||||
See <a href="#config_filename_metadata">Configuration</a> section, to learn how to configure this.
|
||||
</p>
|
||||
<p>
|
||||
To add a new format to an existing book, use the <a href="#edit_meta_information">Edit meta information</a> action.
|
||||
</p>
|
||||
|
||||
<h3 class="subsectionHeading" id="remove_books"><img style="vertical-align: middle" src="images/remove_books.png" alt="Remove books" />
|
||||
Remove books </h3>
|
||||
<p>
|
||||
The <span class="action">Remove books</span> action deletes books permanently, so use it with care.
|
||||
It is <i>context sensitive</i>,
|
||||
i.e. it depends on which <a href="#catalogs">catalog</a> you have selected. If you have selected the
|
||||
library, books will be removed from the library. If you have selected the ebook reader device, the books
|
||||
will be removed from the device. To remove only a particular format for a given book use the
|
||||
<a href="#edit_meta_information">Edit meta information</a> action.
|
||||
</p>
|
||||
|
||||
<h3 class="subsectionHeading" id="edit_meta_information">
|
||||
<img style="vertical-align: middle" src="images/edit_meta_information.png" alt="Edit meta information" />
|
||||
Edit meta information
|
||||
</h3>
|
||||
<p>
|
||||
The <span class="action">Edit meta information</span> action has two variations, accessed by the
|
||||
arrow next to the button.
|
||||
</p>
|
||||
<ul>
|
||||
<li>
|
||||
<b>Edit metadata individually</b>: This allows you to edit the metadata of books one-by-one, with the option
|
||||
of fetching metadata, including covers from the internet. It also allows you to add/remove particular
|
||||
ebook formats from a book. For more detail see <a href="metadata.html">Editing metadata</a>.
|
||||
</li>
|
||||
<li>
|
||||
<b>Edit metadata in bulk</b>: This allows you to edit common metadata fields for large numbers of books simulataneously. It
|
||||
operates on all the books you have selected in the <a href="#search_sort">Library view</a>.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<h3 class="subsectionHeading" id="send_to_device">
|
||||
<img style="vertical-align: middle" src="images/send_to_device.png" alt="Send to device" />
|
||||
Send to device
|
||||
</h3>
|
||||
<p>
|
||||
The <span class="action">Send to device</span> action has two variations, accessed by the
|
||||
arrow next to the button.
|
||||
</p>
|
||||
<ul>
|
||||
<li>
|
||||
<b>Send to main memory</b>: The selected books are transferred to the main memory of the ebook reader.
|
||||
</li>
|
||||
<li>
|
||||
<b>Send to card</b>: The selected books are transferred to the storage card on the ebook reader.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<h3 class="subsectionHeading" id="save_to_disk">
|
||||
<img style="vertical-align: middle" src="images/save_to_disk.png" alt="Save to disk" />
|
||||
Save to disk
|
||||
</h3>
|
||||
<p>
|
||||
The <span class="action">Save to disk</span> action has two variations, accessed by the
|
||||
arrow next to the button.
|
||||
</p>
|
||||
<ul>
|
||||
<li id="save_to_disk_multiple">
|
||||
<b>Save to disk</b>: This will save the selected books to disk organized in directories. The directory
|
||||
structure looks like:
|
||||
<pre>
|
||||
Author
|
||||
Title
|
||||
Book Files
|
||||
</pre>
|
||||
</li>
|
||||
<li id="save_to_disk_single">
|
||||
<b>Save to disk in a single directory</b>: The selected books are saved to disk in a single directory.
|
||||
</li>
|
||||
</ul>
|
||||
<p>
|
||||
All available formats as well as metadata is stored to disk for each selected book. Metadata is stored in an OPF file.
|
||||
Saved books can be re-imported to the library without any loss of information by using the <a href="#add_books">Add books</a>
|
||||
action.
|
||||
</p>
|
||||
|
||||
<h3 class="subsectionHeading" id="fetch_news">
|
||||
<img style="vertical-align: middle" src="images/fetch_news.png" alt="Fetch news" />
|
||||
Fetch news
|
||||
</h3>
|
||||
<p>
|
||||
The <span class="action">Fetch news</span> action downloads news from various predefined
|
||||
websites and converts it into an ebook that can be read on your ebook reader. Normally, the newly
|
||||
created ebook is added to your ebook library, but if an ebook reader is connected at the time
|
||||
the download finishes, the news is uploaded to the reader directly.
|
||||
</p>
|
||||
<p>
|
||||
The <span class="action">Fetch news</span> uses simple profiles (10-15 lines of code) for each news
|
||||
site. To learn how to create profiles for your own news sources, see
|
||||
<a href="news.html">creating custom news profiles</a>.
|
||||
</p>
|
||||
|
||||
<h3 class="subsectionHeading" id="convert_ebooks">
|
||||
<img style="vertical-align: middle" src="images/convert_ebooks.png" alt="Convert E-books" />
|
||||
Convert E-books
|
||||
</h3>
|
||||
<p>
|
||||
Ebooks can be converted from a number of formats into the LRF format (for the SONY Reader). Note that ebooks you purchase
|
||||
will typically have <a href="http://en.wikipedia.org/wiki/Digital_rights_management">Digital Rights Management</a>
|
||||
<i>(DRM)</i>. ${app} will not convert these ebooks. For many DRM formats, it is easy to remove the DRM, but as this
|
||||
is illegal, you have to find tools to liberate your books yourself and then use ${app} to convert them.
|
||||
</p>
|
||||
<p>
|
||||
For most people, conversion should be a simple 1-click affair. But if you want to learn more about the
|
||||
conversion process, see <a href="conversion.html">E-book conversion</a>.
|
||||
</p>
|
||||
<p>
|
||||
The <span class="action">Convert E-books</span> action has three variations, accessed by the
|
||||
arrow next to the button.
|
||||
</p>
|
||||
<ul>
|
||||
<li>
|
||||
<b>Convert individually</b>: This will allow you to specify conversion options to customize the
|
||||
conversion of each selected ebook.
|
||||
</li>
|
||||
<li>
|
||||
<b>Bulk convert</b>: This allows you to specify options only once to convert a number of ebooks in bulk.
|
||||
</li>
|
||||
<li>
|
||||
<b>Set conversion defaults</b>: Allows you to set the default settings for future conversions.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
|
||||
<h3 class="subsectionHeading" id="view">
|
||||
<img style="vertical-align: middle" src="images/view.png" alt="View" />
|
||||
View
|
||||
</h3>
|
||||
<p>
|
||||
The <span class="action">View</span> action displays the book in an ebook viewer program. ${app} has a builtin
|
||||
viewer for the LRF format. For other formats it uses the default operating system application. If a book has more than
|
||||
one format, you can view a particular format by clicking the arrow next to the View button.
|
||||
</p>
|
||||
|
||||
<hr />
|
||||
<h2 class="sectionHeading" id="catalogs">Catalogs</h2>
|
||||
<div><img src="images/catalogs.png" alt="Catalogs"/></div>
|
||||
<p>
|
||||
A <i>catalog</i> is a collection of books. ${app} can manage three different catalogs:
|
||||
</p>
|
||||
<ul>
|
||||
<li>
|
||||
<b>Library</b>: This is a collection of books stored in a database file on your computers hard disk.
|
||||
<b>Reader</b>: This is a collection of books stored in the main memory of your ebook reader. It will be available
|
||||
when you connect
|
||||
<b>Card</b>: This is a collection of books stored on the storage card in your reader. Note that ${app} supports
|
||||
only a single storage card at a time.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<hr />
|
||||
<h2 class="sectionHeading" id="search_sort">Search & Sort</h2>
|
||||
<div><img src="images/search_sort.png" alt="Search & Sort"/></div>
|
||||
<p>
|
||||
The Search & Sort section allows you to perform several powerful actions
|
||||
on your book collections.
|
||||
</p>
|
||||
<ul>
|
||||
<li>
|
||||
You can sort them by title, author, date, rating etc.
|
||||
by clicking on the column titles.
|
||||
</li>
|
||||
<li>
|
||||
You can search for a particular book or set of books using the search bar. More on that
|
||||
below.
|
||||
</li>
|
||||
<li>
|
||||
You can quickly and conveniently edit metadata by double-clicking the entry you want changed
|
||||
in the list.
|
||||
</li>
|
||||
<li>
|
||||
You can perform <a href="#actions">actions</a> on sets to books. To select multiple books you can either:
|
||||
<ul>
|
||||
<li>Keep the <code>Ctrl</code> key pressed and click on the books you want selected.</li>
|
||||
<li>Keep the <code>Shift</code> key pressed and click on the starting and ending book of a range
|
||||
of books you want selected.</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>
|
||||
You can configure which fields you want displayed by using the <a href="#configuration">Configuration</a> dialog.
|
||||
</li>
|
||||
</ul>
|
||||
<h3 class="subsectionHeading">The Search Interface</h3>
|
||||
<p>
|
||||
You can search all the metadata by entering search terms in the search bar. Searches are case insensitive.
|
||||
For example:
|
||||
</p>
|
||||
|
||||
<pre style="background: #eeeeee">
|
||||
Asimov Foundation format:lrf
|
||||
</pre>
|
||||
<p>
|
||||
This will match all books in your library that have <code>Asimov</code> and <code>Foundation</code> in their metadata
|
||||
and are available in the LRF format. You can build advanced search queries easily using the "Advanced Search Dialog"
|
||||
by clicking the button <img src="images/search_button.png" alt="Search button" style="vertical-align: middle"/>.<br /><br />
|
||||
</p>
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td><img src="images/search.png" alt="Advanced Search Dialog" /></td>
|
||||
<td>
|
||||
You can search on individual fields as shown. The "Negate" checkbox implies that only results that
|
||||
do not match the search expression will be returned. You can require all the search criteria to match
|
||||
or any of them.
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<hr />
|
||||
<h2 class="sectionHeading" id="configuration">Configuration</h2>
|
||||
<p>
|
||||
The configuration dialog allows you to set some global defaults used by all of ${app}. To access it, click the
|
||||
<img src="images/configuration.png" alt="Configuration" /> button.
|
||||
</p>
|
||||
|
||||
<hr />
|
||||
<h2 class="sectionHeading" id="book_details">Book Details</h2>
|
||||
<div><img src="images/book_details.png" alt="Book Details" /></div>
|
||||
<p>
|
||||
The Book Details display shows you extra information and the cover for the currently selected book.
|
||||
</p>
|
||||
|
||||
<hr />
|
||||
<h2 class="sectionHeading" id="jobs">Jobs</h2>
|
||||
<div><img src="images/jobs.png" alt="Jobs" /></div>
|
||||
<p>
|
||||
The Jobs panel shows you the number of currently running jobs. Jobs are tasks that run in a separate
|
||||
process, they include converting ebooks and talking to your reader device.
|
||||
You can click on the jobs panel to access the list of jobs.
|
||||
Once a job has completed, by double-clicking it in the list, you can see a detailed log from that job. This is useful
|
||||
to debug jobs that may not have completed successfully.
|
||||
</p>
|
||||
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
@ -1,18 +0,0 @@
|
||||
<!DOCTYPE html PUBLIC
|
||||
"-//W3C//DTD XHTML 1.0 Frameset//EN"
|
||||
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
|
||||
|
||||
<head>
|
||||
<meta name="author" content="${author}" />
|
||||
<meta name="copyright" content="© 2008 ${author}" />
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
||||
<title>${app} User Manual</title>
|
||||
</head>
|
||||
|
||||
<frameset cols="25%, 75%">
|
||||
<frame id="nav" src="navtree.html" />
|
||||
<frame id="content" src="start.html" />
|
||||
</frameset>
|
||||
|
||||
</html>
|
||||
@ -1,67 +0,0 @@
|
||||
<?python
|
||||
import re
|
||||
from genshi import HTML
|
||||
from pygments import highlight
|
||||
from pygments.lexers import PythonLexer
|
||||
from pygments.formatters import HtmlFormatter
|
||||
formatter = HtmlFormatter(linenos='inline', cssclass='codeblock',
|
||||
lineanchors='lineno', lineseparator='\n')
|
||||
lexer = PythonLexer()
|
||||
?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
||||
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"
|
||||
xml:lang="en"
|
||||
xmlns:py="http://genshi.edgewall.org/"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
py:strip=""
|
||||
>
|
||||
<py:match path="head">
|
||||
<head py:attrs="select('@*')">
|
||||
<meta name="author" content="${author}" />
|
||||
<meta name="copyright" content="© 2008 ${author}" />
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
||||
<link rel="stylesheet" type="text/css" href="styles/common.css" />
|
||||
<style type="text/css">
|
||||
${formatter.get_style_defs('.codeblock')}
|
||||
.codeblock {
|
||||
background-color: #eeeeee;
|
||||
border: inset 1px black;
|
||||
}
|
||||
.lineno {
|
||||
color: lightgray;
|
||||
font-weight: normal;
|
||||
border-top: solid 1px black;
|
||||
}
|
||||
</style>
|
||||
|
||||
${select('*|text()')}
|
||||
</head>
|
||||
</py:match>
|
||||
|
||||
<py:match path="div[@class='pygmentize']">
|
||||
${HTML(highlight(re.compile(r'^\|\|\|$', re.MULTILINE).sub('', unicode(select('*|text()'))), lexer, formatter))}
|
||||
</py:match>
|
||||
|
||||
<py:match path="body">
|
||||
|
||||
<body py:attrs="select('@*')">
|
||||
<h1 class="documentHeading">
|
||||
${title}
|
||||
</h1>
|
||||
|
||||
${select('*|text()')}
|
||||
<py:if test="footer">
|
||||
<hr />
|
||||
<div class="footer">
|
||||
<p>
|
||||
<a href="http://validator.w3.org/check?uri=referer">
|
||||
<img src="images/valid.png" alt="Valid XHTML 1.0" height="31" width="88" />
|
||||
</a><br />
|
||||
Created by ${author} © 2008
|
||||
</p>
|
||||
</div>
|
||||
</py:if>
|
||||
</body>
|
||||
</py:match>
|
||||
</html>
|
||||
@ -1,59 +0,0 @@
|
||||
<?python
|
||||
title = '%s Manual'%app
|
||||
?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
||||
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"
|
||||
xml:lang="en"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xmlns:py="http://genshi.edgewall.org/"
|
||||
>
|
||||
<xi:include href="layout.html" />
|
||||
|
||||
|
||||
<head>
|
||||
<title>${title}</title>
|
||||
<script src="http://code.jquery.com/jquery-latest.js" type="text/javascript" />
|
||||
<link rel="stylesheet" href="http://dev.jquery.com/view/trunk/plugins/treeview/jquery.treeview.css" type="text/css" />
|
||||
<script type="text/javascript" src="http://dev.jquery.com/view/trunk/plugins/treeview/jquery.treeview.js" />
|
||||
<style type="text/css">
|
||||
#browser {
|
||||
font-family: monospace;
|
||||
}
|
||||
a { color: black; }
|
||||
a:visited { color: black; }
|
||||
.toplevel {
|
||||
font-weight: bold;
|
||||
}
|
||||
.nottoplevel {
|
||||
font-weight: normal;
|
||||
}
|
||||
</style>
|
||||
<script type="text/javascript">
|
||||
$(document).ready(function(){
|
||||
$("#browser").treeview({collapsed:true});
|
||||
});
|
||||
</script>
|
||||
|
||||
</head>
|
||||
<body>
|
||||
<ul id="browser" class="filetree">
|
||||
<py:for each="section in toc">
|
||||
<li py:with="cl='toplevel %s'%('folder' if section['subsections'] else 'file')"
|
||||
class="${cl}">
|
||||
<a target="content" href="${section['href']}">${section['title']}</a>
|
||||
<py:if test="section['subsections']">
|
||||
<ul>
|
||||
<py:for each="ss in section['subsections']">
|
||||
<li class="nottoplevel file">
|
||||
<a target="content" href="${ss['href']}">${ss['title']}</a>
|
||||
</li>
|
||||
</py:for>
|
||||
</ul>
|
||||
</py:if>
|
||||
</li>
|
||||
</py:for>
|
||||
</ul>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@ -1,39 +0,0 @@
|
||||
<?python
|
||||
title = 'Using custom news sources'
|
||||
?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
||||
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"
|
||||
xml:lang="en"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xmlns:py="http://genshi.edgewall.org/"
|
||||
>
|
||||
<xi:include href="layout.html" />
|
||||
|
||||
|
||||
<head>
|
||||
<title>${title}</title>
|
||||
</head>
|
||||
|
||||
<body>
|
||||
<p>
|
||||
<b>This page is awaiting the new news infrastructure in ${app}.</b>
|
||||
${app} contains a very powerful and flexible engine to make fetching
|
||||
news from the Internet and converting it to a nicely formatted ebook,
|
||||
really easy. The easiest way to explain its full power and ease-of-use
|
||||
is through examples, so lets get started...
|
||||
</p>
|
||||
<div class="pygmentize">
|
||||
from libprs500.ebooks.lrf.web.profiles.automatic import AutomaticRSSProfile
|
||||
|||
|
||||
class BBC(DefaultProfile):
|
||||
|||
|
||||
feeds = [
|
||||
'http://newsrss.bbc.co.uk/rss/newsonline_uk_edition/front_page/rss.xml',
|
||||
'http://newsrss.bbc.co.uk/rss/newsonline_uk_edition/sci/tech/rss.xml',
|
||||
]
|
||||
</div>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
@ -1,65 +0,0 @@
|
||||
<?python
|
||||
title = '%s User Manual'%app
|
||||
?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
||||
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"
|
||||
xml:lang="en"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xmlns:py="http://genshi.edgewall.org/"
|
||||
|
||||
>
|
||||
<xi:include href="layout.html" />
|
||||
|
||||
|
||||
<head>
|
||||
<title>${title}</title>
|
||||
</head>
|
||||
|
||||
|
||||
<body>
|
||||
<p>
|
||||
<b>${app}</b> is an e-book library manager. It can view, convert and catalog e-books
|
||||
in most of the major e-book formats. It can also talk to a few e-book reader devices. It can
|
||||
go out to the internet and fetch metadata for your books. It can download newspapers and convert
|
||||
them into e-books for convenient reading. It is cross platform, running on Linux, Windows and OS X.
|
||||
</p>
|
||||
<p>
|
||||
So you've just started ${app}. What do you do now? Well, before ${app} can do anything with your
|
||||
ebooks, it first has to know about them. So drag and drop a few ebook files into ${app}, or click
|
||||
the "Add books" button and browse for the ebooks you want to work with. Once you've added the books,
|
||||
they will show up in the main view looking something like this:<br/>
|
||||
<img src="images/added_books.png" alt="Added books"/><br/>
|
||||
</p>
|
||||
<p>
|
||||
Once you've admired the list of books you just added to your heart's content, you'll probably want to read on.
|
||||
In order to do that you'll have to convert the book to a format your reader understands. For the SONY
|
||||
Reader that's the LRF format. Conversion is a breeze, just select the book you want to convert, and
|
||||
click the "Convert E-book" button. Ignore all the options for now and just click "OK". The little hourglass
|
||||
in the bottom right corner will start spinning. Once it's finished spinning, your converted book is ready.
|
||||
Click to "View" button to read the book.
|
||||
</p>
|
||||
<p>
|
||||
Now if you want to read the book on your reader, just connect it to the computer, wait till
|
||||
${app} detects it (10-20secs) and then click the "Send to device" button. Once the hourglass stops
|
||||
spinning again, disconnect your reader and read away!
|
||||
</p>
|
||||
<p>
|
||||
To get started with more advanced usage, you should read about the
|
||||
<a href="gui.html">Graphical User Interface</a>. For even more power and
|
||||
versatility, learn the <a href="cli-index.html">Command Line Interface</a>.
|
||||
</p>
|
||||
<p>
|
||||
You will find the list of <a href="faq.html">Frequently Asked Questions</a> useful as well.
|
||||
</p>
|
||||
|
||||
<h2>Table of Contents</h2>
|
||||
<ul id="toc">
|
||||
<li><a href="gui.html">Graphical User Interface</a></li>
|
||||
<li><a href="cli-index.html">Command Line Interface</a></li>
|
||||
<li><a href="news.html">Using custom news sources</a></li>
|
||||
<li><a href="faq.html">Frequently Asked Questions</a></li>
|
||||
</ul>
|
||||
</body>
|
||||
|
||||
</html>
|
||||
Loading…
x
Reference in New Issue
Block a user