diff --git a/manual/develop.rst b/manual/develop.rst index aca049091d..d51e79b52b 100644 --- a/manual/develop.rst +++ b/manual/develop.rst @@ -166,7 +166,7 @@ calibre is the directory that contains the src and resources sub-directories. The next step is to set the environment variable ``CALIBRE_DEVELOP_FROM`` to the absolute path of the src directory. So, following the example above, it would be ``C:\Users\kovid\work\calibre\src``. `Here is a short -guide `_ to setting environment +guide `_ to setting environment variables on Windows. Once you have set the environment variable, open a new command prompt and check that it was correctly set by using @@ -333,7 +333,7 @@ the debugging session:: calibre-debug -c "from calibre.rpdb import cli; cli()" You can read about how to use the Python debugger in the `Python stdlib docs -for the pdb module `_. +for the pdb module `_. .. note:: By default, the remote debugger will try to connect on port 4444. You can diff --git a/manual/function_mode.rst b/manual/function_mode.rst index bb73110125..87f46c79a6 100644 --- a/manual/function_mode.rst +++ b/manual/function_mode.rst @@ -10,7 +10,7 @@ In the standard *regexp* mode for search and replace, you specify both a regular expression to search for as well as a template that is used to replace all found matches. In function mode, instead of using a fixed template, you specify an arbitrary function, in the -`Python programming language `_. This allows +`Python programming language `_. This allows you to do lots of things that are not possible with simple templates. Techniques for using function mode and the syntax will be described by means of @@ -57,7 +57,7 @@ Python function named replace, that accepts all the arguments shown above. For the moment, we wont worry about all the different arguments to ``replace()`` function. Just focus on the ``match`` argument. It represents a match when running a search and replace. Its full documentation in available -`here `_. +`here `_. ``match.group()`` simply returns all the matched text and all we do is replace hyphens in that text with em-dashes, first replacing double hyphens and then single hyphens. @@ -239,7 +239,7 @@ The ``match`` argument ^^^^^^^^^^^^^^^^^^^^^^ The ``match`` argument represents the currently found match. It is a -`Python Match object `_. +`Python Match object `_. Its most useful method is ``group()`` which can be used to get the matched text corresponding to individual capture groups in the search regular expression. @@ -393,7 +393,7 @@ Suppressing the result dialog when performing searches on marked text ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ You can also suppress the result dialog (which can slow down the repeated -application of a search/replace on many blocks of text) by setting +application of a search/replace on many blocks of text) by setting the ``suppress_result_dialog`` attribute on your function, like this: .. code-block:: python diff --git a/manual/glossary.rst b/manual/glossary.rst index 040b3b3350..dca2ce1392 100644 --- a/manual/glossary.rst +++ b/manual/glossary.rst @@ -5,10 +5,10 @@ Glossary .. glossary:: RSS - **RSS** *(Really Simple Syndication)* is a web feed format that is used to publish frequently updated content, like news articles, blog posts, etc. It is a format that is particularly suited to being read by computers, and is therefore the preferred way of getting content from the web into an e-book. There are many other feed formats in use on the Internet, and calibre understands most of them. In particular, it has good support for the *ATOM* format, which is commonly used for blogs. + **RSS** *(Really Simple Syndication)* is a web feed format that is used to publish frequently updated content, like news articles, blog posts, etc. It is a format that is particularly suited to being read by computers, and is therefore the preferred way of getting content from the web into an e-book. There are many other feed formats in use on the Internet, and calibre understands most of them. In particular, it has good support for the *ATOM* format, which is commonly used for blogs. recipe - A recipe is a set of instructions that teach calibre how to convert an online news source, such as a magazine or a blog, into an e-book. A recipe is essentially `Python `_ code. As such, it is capable of converting arbitrarily complex news sources into e-books. At the simplest level, it is just a set of variables, such as URLs, that give calibre enough information to go out onto the Internet and download the news. + A recipe is a set of instructions that teach calibre how to convert an online news source, such as a magazine or a blog, into an e-book. A recipe is essentially `Python `_ code. As such, it is capable of converting arbitrarily complex news sources into e-books. At the simplest level, it is just a set of variables, such as URLs, that give calibre enough information to go out onto the Internet and download the news. HTML **HTML** *(Hyper Text Mark-Up Language)*, a subset of Standard Generalized Mark-Up Language (SGML) for electronic publishing, is the specific standard used for the World Wide Web. @@ -26,5 +26,4 @@ Glossary **URL** *(Uniform Resource Locator)* for example: ``http://example.com`` regexp - **Regular expressions** provide a concise and flexible means for identifying strings of text of interest, such as particular characters, words, or patterns of characters. See `regexp syntax `_ for the syntax of regular expressions used in Python. - + **Regular expressions** provide a concise and flexible means for identifying strings of text of interest, such as particular characters, words, or patterns of characters. See `regexp syntax `_ for the syntax of regular expressions used in Python. diff --git a/manual/gui.rst b/manual/gui.rst index 01bc880b27..0e6b7e8897 100644 --- a/manual/gui.rst +++ b/manual/gui.rst @@ -345,7 +345,7 @@ Two other kinds of searches are available: equality search and search using `reg Equality searches are indicated by prefixing the search string with an equals sign (=). For example, the query ``tag:"=science"`` will match "science", but not "science fiction" or "hard science". Regular expression searches are -indicated by prefixing the search string with a tilde (~). Any `Python-compatible regular expression `_ can +indicated by prefixing the search string with a tilde (~). Any `Python-compatible regular expression `_ can be used. Note that backslashes used to escape special characters in regular expressions must be doubled because single backslashes will be removed during query parsing. For example, to match a literal parenthesis you must enter ``\\(``. Regular expression searches are 'contains' searches unless the expression contains anchors. Should you need to search for a string with a leading equals or tilde, prefix the string with a backslash. diff --git a/manual/news.rst b/manual/news.rst index 2b5daef6e1..716c0d2874 100644 --- a/manual/news.rst +++ b/manual/news.rst @@ -103,7 +103,7 @@ This is Python, so indentation is important. After you've added the lines, it sh .. image:: images/bbc_altered.png :align: center -In the above, ``def print_version(self, url)`` defines a *method* that is called by calibre for every article. ``url`` is the URL of the original article. What ``print_version`` does is take that url and replace it with the new URL that points to the print version of the article. To learn about `Python `_ see the `tutorial `_. +In the above, ``def print_version(self, url)`` defines a *method* that is called by calibre for every article. ``url`` is the URL of the original article. What ``print_version`` does is take that url and replace it with the new URL that points to the print version of the article. To learn about `Python `_ see the `tutorial `_. Now, click the :guilabel:`Add/update recipe` button and your changes will be saved. Re-download the e-book. You should have a much improved e-book. One of the problems with the new version is that the fonts on the print version webpage are too small. This is automatically fixed when converting to an e-book, but even after the fixing process, the font size of the menus and navigation bar to become too large relative to the article text. To fix this, we will do some more customization, in the next section. diff --git a/manual/regexp.rst b/manual/regexp.rst index 011a8d255c..ec1ff47390 100644 --- a/manual/regexp.rst +++ b/manual/regexp.rst @@ -118,7 +118,7 @@ Bulk editing metadata The last part is regular expression search and replace in metadata fields. You can access this by selecting multiple books in the library and using bulk metadata edit. Be very careful when using this last feature, as it can do **Very Bad Things** to your library! Doublecheck that your expressions do what you want them to using the test fields, and only mark the books you really want to change! In the regular expression search mode, you can search in one field, replace the text with something and even write the result into another field. A practical example: Say your library contained the books of Frank Herbert's Dune series, named after the fashion ``Dune 1 - Dune``, ``Dune 2 - Dune Messiah`` and so on. Now you want to get ``Dune`` into the series field. You can do that by searching for ``(.*?) \d+ - .*`` in the title field and replacing it with ``\1`` in the series field. See what I did there? That's a reference to the first group you're replacing the series field with. Now that you have the series all set, you only need to do another search for ``.*? -`` in the title field and replace it with ``""`` (an empty string), again in the title field, and your metadata is all neat and tidy. Isn't that great? By the way, instead of replacing the entire field, you can also append or prepend to the field, so, if you *wanted* the book title to be prepended with series info, you could do that as well. As you by now have undoubtedly noticed, there's a checkbox labeled :guilabel:`Case sensitive`, so you won't have to use flags to select behaviour here. -Well, that just about concludes the very short introduction to regular expressions. Hopefully I'll have shown you enough to at least get you started and to enable you to continue learning by yourself- a good starting point would be the `Python documentation for regexps `_. +Well, that just about concludes the very short introduction to regular expressions. Hopefully I'll have shown you enough to at least get you started and to enable you to continue learning by yourself- a good starting point would be the `Python documentation for regexps `_. One last word of warning, though: Regexps are powerful, but also really easy to get wrong. calibre provides really great testing possibilities to see if your expressions behave as you expect them to. Use them. Try not to shoot yourself in the foot. (God, I love that expression...) But should you, despite the warning, injure your foot (or any other body parts), try to learn from it. @@ -144,7 +144,7 @@ Thanks for helping with tips, corrections and such: * Starson17 * Orpheu -For more about regexps see `The Python User Manual `_. +For more about regexps see `The Python User Manual `_. The actual regular expression library used by calibre is: `regex `_ which supports several useful enhancements over the python standard library one. diff --git a/manual/template_lang.rst b/manual/template_lang.rst index b885f2f7fe..7398333c0a 100644 --- a/manual/template_lang.rst +++ b/manual/template_lang.rst @@ -84,7 +84,7 @@ If you want only the first two letters of the data, use:: {author_sort:.2} - Only the first two letter of the author sort name -The calibre template language comes from Python and for more details on the syntax of these advanced formatting operations, look at the `Python documentation `_. +The calibre template language comes from Python and for more details on the syntax of these advanced formatting operations, look at the `Python documentation `_. Advanced features ------------------ diff --git a/manual/xpath.rst b/manual/xpath.rst index f76d2cb0a9..d7d1f5d020 100644 --- a/manual/xpath.rst +++ b/manual/xpath.rst @@ -3,22 +3,22 @@ XPath tutorial ============== -In this tutorial, you will be given a gentle introduction to -`XPath `_, a query language that can be +In this tutorial, you will be given a gentle introduction to +`XPath `_, a query language that can be used to select arbitrary parts of `HTML `_ documents in calibre. XPath is a widely -used standard, and googling it will yield a ton of information. This tutorial, -however, focuses on using XPath for e-book related tasks like finding chapter +used standard, and googling it will yield a ton of information. This tutorial, +however, focuses on using XPath for e-book related tasks like finding chapter headings in an unstructured HTML document. .. contents:: Contents :depth: 1 - :local: + :local: Selecting by tag name ---------------------------------------- -The simplest form of selection is to select tags by name. For example, +The simplest form of selection is to select tags by name. For example, suppose you want to select all the ``

`` tags in a document. The XPath query for this is simply:: @@ -36,14 +36,14 @@ the prefix:: /h:body/h:div/h:p (Selects

tags that are children of

tags that are children of the tag) -This will match only ``

A very short e-book to demonstrate the use of XPath.

`` +This will match only ``

A very short e-book to demonstrate the use of XPath.

`` in the :ref:`sample_ebook` but not any of the other ``

`` tags. The ``h:`` prefix in the above examples is needed to match XHTML tags. This is because internally, calibre represents all content as XHTML. In XHTML tags have a *namespace*, and ``h:`` is the namespace prefix for HTML tags. Now suppose you want to select both ``

`` and ``

`` tags. To do that, -we need a XPath construct called *predicate*. A :dfn:`predicate` is simply +we need a XPath construct called *predicate*. A :dfn:`predicate` is simply a test that is used to select tags. Tests can be arbitrarily powerful and as this tutorial progresses, you will see more powerful examples. A predicate is created by enclosing the test expression in square brackets:: @@ -54,7 +54,7 @@ There are several new features in this XPath expression. The first is the use of the wildcard ``*``. It means *match any tag*. Now look at the test expression ``name()='h1' or name()='h2'``. :term:`name()` is an example of a *built-in function*. It simply evaluates to the name of the tag. So by using it, we can select tags -whose names are either `h1` or `h2`. Note that the :term:`name()` function +whose names are either `h1` or `h2`. Note that the :term:`name()` function ignores namespaces so that there is no need for the ``h:`` prefix. XPath has several useful built-in functions. A few more will be introduced in this tutorial. @@ -67,7 +67,7 @@ To select tags based on their attributes, the use of predicates is required:: //*[@class="chapter"] (Select all tags that have class="chapter") //h:h1[@class="bookTitle"] (Select all h1 tags that have class="bookTitle") -Here, the ``@`` operator refers to the attributes of the tag. You can use some +Here, the ``@`` operator refers to the attributes of the tag. You can use some of the `XPath built-in functions`_ to perform more sophisticated matching on attribute values. @@ -78,7 +78,7 @@ Selecting by tag content Using XPath, you can even select tags based on the text they contain. The best way to do this is to use the power of *regular expressions* via the built-in function :term:`re:test()`:: - //h:h2[re:test(., 'chapter|section', 'i')] (Selects

tags that contain the words chapter or + //h:h2[re:test(., 'chapter|section', 'i')] (Selects

tags that contain the words chapter or section) Here the ``.`` operator refers to the contents of the tag, just as the ``@`` operator referred @@ -107,5 +107,4 @@ XPath built-in functions ``re:test(src, pattern, flags)`` returns `true` if the string `src` matches the regular expression `pattern`. A particularly useful flag is ``i``, it makes matching case insensitive. A good primer on the syntax for regular expressions can be found - at `regexp syntax `_ - + at `regexp syntax `_ diff --git a/src/calibre/utils/config.py b/src/calibre/utils/config.py index 0c6ded74de..42f45d75be 100644 --- a/src/calibre/utils/config.py +++ b/src/calibre/utils/config.py @@ -303,7 +303,7 @@ class XMLConfig(dict): Similar to :class:`DynamicConfig`, except that it uses an XML storage backend instead of a pickle file. - See `https://docs.python.org/dev/library/plistlib.html`_ for the supported + See `https://docs.python.org/library/plistlib.html`_ for the supported data types. '''