Cutlery/calibre
1
0
Fork 0
mirror of https://github.com/kovidgoyal/calibre.git synced 2025-07-08 18:54:09 -04:00
Code Issues Packages Projects Releases Wiki Activity

0.8.67+, added catalog help functionality

Browse Source
This commit is contained in:
GRiker 2012-09-02 05:02:15 -06:00
parent 2b85633a87
commit 0ff236f71f
6 changed files with 256 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

193
resources/catalog/help_epub_mobi.html Normal file
View File

@ -0,0 +1,193 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Untitled Document</title>
<style type="text/css">
h1 {
font-size: 1.5em;
text-align: center;
}
h2 {
font-size: 1.0em;
font-weight: normal;
margin-bottom: 0.25em;
margin-top: 0px;
font-family: Arial, Helvetica, sans-serif;
}
h3 {
text-align: center;
font-family: Arial, Helvetica, sans-serif;
font-weight: normal;
}
.ui_element {
font-family: Arial, Helvetica, sans-serif;
font-weight: normal;
font-size: 90%;
}
.user-input {
font-family: "Courier New", Courier, monospace;
font-size: 90%;
}
</style>
</head>
<body>
<h1><a name="toc" id="toc"></a>AZW3 • EPUB • MOBI Catalogs </h1>
<h2><a href="#selecting_books_to_catalog">Selecting books to catalog</a></h2>
<h2><a href="#included_sections">Included sections: Selecting which sections to include in the catalog</a></h2>
<h2><a href="#prefixes">Prefixes: Adding a prefix indicating book status</a></h2>
<h2><a href="#excluded_books">Excluded books: Ignoring certain books when generating the catalog</a></h2>
<h2><a href="#excluded_genres">Excluded genres: Ignoring certain tags as genres when generating the catalog</a></h2>
<h2><a href="#other_options">Other options: Specifying thumb size, adding extra information to Descriptions</a></h2>
<h2><a href="#customizing_catalog_appearance">Customizing the appearance of the generated catalog</a></h2>
<hr />
<h3><a name="selecting_books_to_catalog" id="selecting_books_to_catalog"></a><a href="#toc">Selecting books to catalog</a></h3>
<p>If you want all of your library cataloged, remove any search or filtering criteria by clearing the <span class="ui_element">Search:</span> field in the main window. With a single book selected, all books in your library will be candidates for inclusion in the generated catalog. Individual books may be excluded by various criteria; see the <a href="#excluded_genres">Excluded genres</a> section below for more information.</p>
<p>If you want only some of your library cataloged, you have two options:</p>
<ol>
<li>Create a multiple selection of the books you want cataloged. With more than one book selected in calibre's main window, only the selected books will be cataloged.</li>
<li>Use the <span class="ui_element">Search:</span> field or calibre's Tag Browser to filter the displayed books. With a single book selected, only the displayed books will be cataloged.</li>
</ol>
<hr />
<h3><a name="included_sections" id="included_sections"></a><a href="#toc">Included sections</a></h3>
<p>&lt;img&gt;</p>
<p>Sections enabled by a checkmark will be included in the generated catalog:</p>
<ul>
<li> <span class="ui_element">Authors</span> - all books, sorted by author, presented in a list format.</li>
<li><strong class="ui_element">Titles</strong> - all books, sorted by title, presented in a list format.</li>
<li><strong class="ui_element">Series</strong> - all books in series, sorted by series, presented in a list format</li>
<li><strong class="ui_element">Genres</strong> - individual genres presented in a list, sorted by Author and Series</li>
<li><strong class="ui_element">Recently Added</strong> - all books, sorted in reverse chronological order. List includes books added in the last 30 days, then a month-by-month listing of added books.</li>
<li><strong class="ui_element">Descriptions</strong> - detailed description page for each book, including a cover thumbnail and comments. Sorted by author, with non-series books listed before series books.</li>
</ul>
<hr />
<h3><a name="prefixes" id="prefixes"></a><a href="#toc">Prefixes</a></h3>
<p>&lt;img&gt;</p>
<p>Prefix rules specify matching criteria and a prefix to use when the criteria is matched.</p>
<p>The checkbox in the first column enables the rule. <span class="ui_element">Name</span> is a rule name that you provide. <span class="ui_element">Field</span> is either <span class="ui_element">Tags</span> or a custom column in your library. <span class="ui_element">Value</span> is the content of <span class="ui_element">Field</span> to match. When a prefix rule is satisfied, the book will be marked with the selected symbol in the <span class="ui_element">Prefix</span> column.</p>
<p>Three prefix rules have been specified in the example above:</p>
<ol>
<li><span class="user-input">Read book</span> specifies that a book with any date in a custom column named <span class="user-input">Last read</span> will be prefixed with a checkmark symbol.</li>
<li><span class="user-input">Wishlist item</span> specifies that any book with a <span class="user-input">Wishlist</span> tag will be prefixed with an X symbol.</li>
<li> <span class="user-input">Library books</span> specifies that any book with a value of True (or Yes) in a custom column <span class="user-input">Available in Library</span> will be prefixed with a double arrow symbol.</li>
</ol>
<p>The first matching rule supplies the prefix. Disabled or incomplete rules are ignored.</p>
<hr />
<h3><a name="excluded_books" id="excluded_books"></a><a href="#toc">Excluded books</a></h3>
<p>&lt;img&gt;</p>
<p>Exclusion rules specify matching criteria for books that will not be cataloged.</p>
<p>The checkbox in the first column enables the rule. <span class="ui_element">Name</span> is a rule name that you provide. <span class="ui_element">Field</span> is either <span class="ui_element">Tags</span> or a custom column in your library. <span class="ui_element">Value</span> is the content of <span class="ui_element">Field</span> to match. When an exclusion rule is satisfied, the book will be excluded from the generated catalog.</p>
<p>Two exclusion rules have been specified in the example above:</p>
<ol>
<li>The <span class="user-input">Catalogs</span> rule specifies that any book with a <span class="user-input">Catalog</span> tag will be excluded from the generated catalog.</li>
<li>The <span class="user-input">Archived Books</span> rule specifies that any book with a value of <span class="user-input">Archived</span> in the custom column <span class="user-input">Status</span> will be excluded from the generated catalog.</li>
</ol>
<p>All rules are evaluated for every book. Disabled or incomplete rules are ignored.</p>
<hr />
<h3><a name="excluded_genres" id="excluded_genres"></a><a href="#toc">Excluded genres</a></h3>
<p>&lt;img&gt;</p>
<p>When the catalog is generated, tags in your database are used as genres. For example, you may have the tags <span class="user-input">Fiction</span> and <span class="user-input">Nonfiction</span> applied to books in your library. These tags become genres in the generated catalog, with all tagged books showing up in their respective genre lists.</p>
<p>You may be using certain tags for other purposes, perhaps a <span class="user-input">+</span> to indicate a read book, or a bracketed tag like <span class="user-input">[Amazon Freebie]</span> to indicate a book's source. The <span class="ui_element">Excluded genres</span> regex allows you to specify tags that you don't want used as genres in the generated catalog. The default exclusion regex pattern <span class="user-input">\[.+\]\+</span> excludes any tags of the form <span class="user-input">[tag]</span>, as well as excluding +, the default tag for read books, from being used as genres in the generated catalog.</p>
<p>You can also use the exact tag name in a regex. For example, <span class="user-input">[Amazon Freebie]</span> will exclude that tag from the generated catalog. If you want to list multiple exact tags for exclusion, put a pipe character between them: <span class="user-input">[Amazon Freebie]|[Project Gutenberg]</span>.</p>
<p>The Results field shows you which tags will be excluded when the catalog is built, based on the tags in your database and the regex you enter.</p>
<hr />
<h3><a name="other_options" id="other_options"></a><a href="#toc">Other options</a></h3>
<p><span class="ui_element">Thumb width</span> specifies a width preference for cover thumbnails included in the Descriptions section. Thumbnails are cached to improve performance. If you want to experiment with different widths, try generating a catalog with just a few books until you've found your optimal width, then generate your full catalog. The first time a catalog is generated with a new thumbnail width, performance will be slower, but subsequent runs will take advantage of the cache.</p>
<p><span class="ui_element">Extra note</span> specifies a custom column's contents to be inserted into the Description, opposite the cover. For example, you might want to display the date you last read a book using a <span class="user-input">Last Read</span> custom column. For advanced use of the Description note feature, see <a href="http://www.mobileread.com/forums/showpost.php?p=1335767&postcount=395" target="new">this post in the calibre forum</a>.</p>
<p><span class="ui_element">Merge with Comments</span> specifies a custom column whose content will be non-destructively merged with the Comments metadata during catalog generation. For example, you might have a custom column <span class="user-input">Author Bio</span> that you'd like to append to the Comments metadata. You can choose to insert the custom column contents before or after the Comments section, and optionally separate the appended content with a horizontal rule. Eligible custom column types include <span class="user-input">text</span>, <span class="user-input">comments</span>, and <span class="user-input">composite</span>.</p>
<hr />
<h3><a name="customizing_catalog_appearance" id="customizing_catalog_appearance"></a><a href="#toc">Customizing catalog appearance</a></h3>
<p>If you wish to change the default appearance of the Description pages or Section lists, you can do so by modifying a local copy of the catalog's template and CSS files, overriding the default layout. This requires familiarity with HTML and CSS.<br />
</p>
<ul>
<li>Open your calibre configuration directory - <span class="ui_element">Preferences|Advanced|Miscellaneous|Open calibre configuration directory</span>.<br />
</li>
<li>Within this directory, create a subdirectory <span class="user-input">resources</span> (if it doesn't already exist).<br />
</li>
<li>Within the <span class="user-input">resources</span> directory, create a subdirectory <span class="user-input">catalog</span>.<br />
</li>
<li>Open a new file system window, navigate to the default catalog resources folder:<br />
<ul>
<li>OSX: <span class="user-input">Applications/calibre/Contents/Resources/resources/catalog</span><br />
</li>
<li>Windows: <span class="user-input">Program Files\Calibre2\resources\catalog</span><br />
</li>
</ul>
</li>
<li>Copy all of the files from the default catalog resources folder to the newly created <span class="user-input">resources/catalog</span> directory within your calibre configuration directory.<br />
</li>
<li>Edit <span class="user-input">template.xhtml</span> and <span class="user-input">stylesheet.css</span> to your preferences. If you want to start over, copy from the default template and CSS files again. If you want to discard your customizations, delete the <span class="user-input">catalog</span> subfolder from your calibre configuration resources directory.<br />
</li>
</ul>
<p>Customizing the Description page. Available fields in <span class="user-input">template.xhtml</span>:<br />
</p>
<ul>
<li>{author} - Book author(s)<br />
</li>
<li>{author_prefix} - Checkmark if read, 'X' if wishlist, else blank<br />
</li>
<li>{comments} - Contents of the book's Comments field<br />
</li>
<li>{formats} - List of installed formats<br />
</li>
<li>{genres} - List of genres<br />
</li>
<li>{note_content} - Note content as specified in options<br />
</li>
<li>{note_source} - Note source field as specified in options<br />
</li>
<li>{pubdate} - Month/Year published<br />
</li>
<li>{publisher} - Publisher<br />
</li>
<li>{pubmonth} - Month published<br />
</li>
<li>{pubyear} - Year published<br />
</li>
<li>{rating} - Graphical rating<br />
</li>
<li>{series} - Series name<br />
</li>
<li>{series_index} - Series index<br />
</li>
<li>{thumb} - Cover thumb url<br />
</li>
<li>{title} - Book title<br />
</li>
</ul>
<p>Example: Changing year of publication in Description header<br />
Default: &lt;td class=&quot;date&quot;&gt;{pubyear}&lt;/td&gt;<br />
Removed: &lt;td class=&quot;date&quot;&gt;&lt;/td&gt;<br />
Augmented: &lt;td class=&quot;date&quot;&gt;Year of publication: {pubyear}&lt;/td&gt;<br />
Modified: &lt;td class=&quot;date&quot;&gt;{pubmonth} {pubyear}&lt;/td&gt;</p>
<p>Customizing the Section lists. Templates controlling the display of book titles in the various Section lists (Books by Author, Books by Title, etc) may be edited to taste. <br />
Available fields in section_list_templates.py:<br />
{title} - Title of the book<br />
{series} - Series name<br />
{series_index} - Number of the book in the series<br />
{rating} - 0-5 stars<br />
{rating_parens} - (0-5 stars)<br />
{pubyear} - Year the book was published<br />
{pubyear_parens} - (Year the book was published)<br />
Example: Changing Books by Author to remove year of publication:<br />
Default:</p>
<p>Code:<br />
by_authors_normal_title_template = '{title} {pubyear_parens}'<br />
by_authors_series_title_template = '[{series_index}] {title} {pubyear_parens}'<br />
Year of publication removed:</p>
<p>Code:<br />
by_authors_normal_title_template = '{title}'<br />
by_authors_series_title_template = '[{series_index}] {title}'<br />
Rating added:</p>
<p>Code:<br />
by_authors_normal_title_template = '{title} {rating}'<br />
by_authors_series_title_template = '[{series_index}] {title} {rating}'</p>
<p>Tips for experimenting with customization:<br />
Work with a small subset of your catalog, 5-10 books<br />
If you are experimenting with Section list templates, disable Descriptions in E-book options - catalog generation will be much faster.<br />
If you are experimenting with CSS, build an EPUB version of your catalog, explode it with the Tweak EPUB feature to find the class of the element you want to change.</p>
<p>&nbsp;</p>
<p>&nbsp;</p>
</body>
</html>

24
src/calibre/devices/apple/driver.py
View File

@ -13,7 +13,8 @@ from calibre.constants import isosx, iswindows
from calibre.devices.errors import OpenFeedback, UserFeedback
from calibre.devices.usbms.deviceconfig import DeviceConfig
from calibre.devices.interface import DevicePlugin
from calibre.ebooks.metadata import authors_to_string, MetaInformation, title_sort
from calibre.ebooks.metadata import (author_to_author_sort, authors_to_string,
MetaInformation, title_sort)
from calibre.ebooks.metadata.book.base import Metadata
from calibre.utils.config import config_dir, dynamic, prefs
from calibre.utils.date import now, parse_date
@ -405,9 +406,9 @@ class ITUNES(DriverBase):
@return: A BookList.
Implementation notes:
iTunes does not sync purchased books, they are only on the device. They are visible, but
they are not backed up to iTunes. Since calibre can't manage them, don't show them in the
list of device books.
iTunes does not sync purchased books, they are only on the device. They are
visible, but they are not backed up to iTunes. Since calibre can't manage them,
don't show them in the list of device books.
"""
if not oncard:
@ -1637,9 +1638,19 @@ class ITUNES(DriverBase):
logger().info('%s%s' % (' '*indent,'-' * len(msg)))
for book in booklist:
tl = [i.title for i in booklist]
lt = max(tl, key=len)
al = [i.author for i in booklist]
la = max(al, key=len)
asl = [i.author_sort for i in booklist]
las = max(asl, key=len)
if isosx:
logger().info("%s%-40.40s %-30.30s %-10.10s %s" %
(' '*indent,book.title, book.author, str(book.library_id)[-9:], book.uuid))
fs = '{!s}{:<%d} {:<%d} {:<%d} {:<10} {!s}' % (' ' * indent, len(lt),
len(la), len(las))
logger.info(fs.format(book.title, book.author, book.author_sort,
str(book.library_id)[-9:], book.uuid))
#logger().info("%s%-40.40s %-30.30s %-10.10s %s" %
# (' '*indent,book.title, book.author, str(book.library_id)[-9:], book.uuid))
elif iswindows:
logger().info("%s%-40.40s %-30.30s" %
(' '*indent,book.title, book.author))
@ -3478,6 +3489,7 @@ class Book(Metadata):
'''
def __init__(self,title,author):
Metadata.__init__(self, title, authors=author.split(' & '))
self.author_sort = author_to_author_sort(author)
@property
def title_sorter(self):

12
src/calibre/gui2/catalog/catalog_epub_mobi.py
View File

@ -11,13 +11,14 @@ import re, sys
from functools import partial
from calibre.ebooks.conversion.config import load_defaults
from calibre.gui2 import gprefs, info_dialog, question_dialog
from calibre.gui2 import gprefs, info_dialog, open_url, question_dialog
from calibre.utils.icu import sort_key
from catalog_epub_mobi_ui import Ui_Form
from PyQt4.Qt import (Qt, QAbstractItemView, QCheckBox, QComboBox,
QDoubleSpinBox, QIcon, QLineEdit, QObject, QRadioButton, QSize, QSizePolicy,
QTableWidget, QTableWidgetItem, QTextEdit, QToolButton, QVBoxLayout, QWidget,
QTableWidget, QTableWidgetItem, QTextEdit, QToolButton, QUrl,
QVBoxLayout, QWidget,
SIGNAL)
class PluginWidget(QWidget,Ui_Form):
@ -440,6 +441,13 @@ class PluginWidget(QWidget,Ui_Form):
self.merge_after.setEnabled(False)
self.include_hr.setEnabled(False)
def show_help(self):
'''
Display help file
'''
url = 'file:///' + P('catalog/help_epub_mobi.html')
open_url(QUrl(url))
class CheckableTableWidgetItem(QTableWidgetItem):
'''
Borrowed from kiwidude

4
src/calibre/gui2/catalog/catalog_epub_mobi.ui
View File

@ -268,7 +268,7 @@ The default pattern \[.+\]|\+ excludes tags of the form [tag], e.g., [Test book]
</size>
</property>
<property name="toolTip">
<string>List of tags that will be excluded as genres</string>
<string>Tags that will be excluded as genres</string>
</property>
<property name="frameShape">
<enum>QFrame::StyledPanel</enum>
@ -379,7 +379,7 @@ The default pattern \[.+\]|\+ excludes tags of the form [tag], e.g., [Test book]
<item>
<widget class="QLabel" name="label_3">
<property name="text">
<string>&amp;Extra note</string>
<string>E&amp;xtra note</string>
</property>
<property name="buddy">
<cstring>header_note_source_field</cstring>

31
src/calibre/gui2/dialogs/catalog.py
View File

@ -10,7 +10,7 @@ import os, sys, importlib
from calibre.customize.ui import config
from calibre.gui2.dialogs.catalog_ui import Ui_Dialog
from calibre.gui2 import dynamic, ResizableDialog
from calibre.gui2 import dynamic, ResizableDialog, info_dialog
from calibre.customize.ui import catalog_plugins
class Catalog(ResizableDialog, Ui_Dialog):
@ -22,7 +22,6 @@ class Catalog(ResizableDialog, Ui_Dialog):
from PyQt4.uic import compileUi
ResizableDialog.__init__(self, parent)
self.dbspec, self.ids = dbspec, ids
# Display the number of books we've been passed
@ -115,6 +114,7 @@ class Catalog(ResizableDialog, Ui_Dialog):
self.format.currentIndexChanged.connect(self.show_plugin_tab)
self.buttonBox.button(self.buttonBox.Apply).clicked.connect(self.apply)
self.buttonBox.button(self.buttonBox.Help).clicked.connect(self.help)
self.show_plugin_tab(None)
geom = dynamic.get('catalog_window_geom', None)
@ -129,6 +129,10 @@ class Catalog(ResizableDialog, Ui_Dialog):
if cf in pw.formats:
self.tabs.addTab(pw, pw.TITLE)
break
if hasattr(self.tabs.widget(1),'show_help'):
self.buttonBox.button(self.buttonBox.Help).setVisible(True)
else:
self.buttonBox.button(self.buttonBox.Help).setVisible(False)
def format_changed(self, idx):
cf = unicode(self.format.currentText())
@ -165,6 +169,29 @@ class Catalog(ResizableDialog, Ui_Dialog):
self.save_catalog_settings()
return ResizableDialog.accept(self)
def help(self):
'''
To add help functionality for a specific format:
In gui2.catalog.catalog_<format>.py, add the following:
from calibre.gui2 import open_url
from PyQt4.Qt import QUrl
In the PluginWidget() class, add this method:
def show_help(self):
url = 'file:///' + P('catalog/help_<format>.html')
open_url(QUrl(url))
Create the help file at resources/catalog/help_<format>.html
'''
if self.tabs.count() > 1 and hasattr(self.tabs.widget(1),'show_help'):
try:
self.tabs.widget(1).show_help()
except:
info_dialog(self, _('No help available'),
_('No help available for this output format.'),
show_copy_button=False,
show=True)
def reject(self):
dynamic.set('catalog_window_geom', bytearray(self.saveGeometry()))
ResizableDialog.reject(self)

8
src/calibre/gui2/dialogs/catalog.ui
View File

@ -14,7 +14,7 @@
<string>Generate catalog</string>
</property>
<property name="windowIcon">
<iconset resource="../../../../resources/images.qrc">
<iconset>
<normaloff>:/images/lt.png</normaloff>:/images/lt.png</iconset>
</property>
<layout class="QGridLayout" name="gridLayout">
@ -37,7 +37,7 @@
<enum>Qt::Horizontal</enum>
</property>
<property name="standardButtons">
<set>QDialogButtonBox::Apply|QDialogButtonBox::Cancel|QDialogButtonBox::Ok</set>
<set>QDialogButtonBox::Apply|QDialogButtonBox::Cancel|QDialogButtonBox::Help|QDialogButtonBox::Ok</set>
</property>
</widget>
</item>
@ -54,8 +54,8 @@
<rect>
<x>0</x>
<y>0</y>
<width>666</width>
<height>599</height>
<width>650</width>
<height>575</height>
</rect>
</property>
<layout class="QVBoxLayout" name="verticalLayout">