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

Manual: Use the :option: directive instead of :cmdoption: as it allows for cross-linking

Browse Source
This commit is contained in:
Kovid Goyal 2016-04-15 09:29:40 +05:30
parent 0595d9beaa
commit 8f99ca2bae
3 changed files with 18 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
manual/custom.py
View File

@ -198,13 +198,21 @@ def render_options(cmd, groups, options_header=True, add_program=True, header_le
help = help.replace('\n', ' ').replace('*', '\\*').replace('%default', str(opt.default))
help = mark_options(help)
opt = opt.get_opt_string() + ((', '+', '.join(opt._short_opts)) if opt._short_opts else '')
opt = '.. cmdoption:: '+opt
opt = '.. option:: '+opt
lines.extend([opt, '', ' '+help, ''])
return lines
def mark_options(raw):
raw = re.sub(r'(\s+)--(\s+)', r'\1``--``\2', raw)
raw = re.sub(r'(--[|()a-zA-Z0-9_=,-]+)', r':option:`\1`', raw)
def sub(m):
opt = m.group()
a, b = opt.partition('=')[::2]
if a in ('--option1', '--option2'):
return m.group()
a = ':option:`' + a + '`'
b = (' = ``' + b + '``') if b else ''
return a + b
raw = re.sub(r'(--[|()a-zA-Z0-9_=,-]+)', sub, raw)
return raw
def cli_docs(app):

2
manual/faq.rst
View File

@ -47,7 +47,7 @@ PDF is a terrible format to convert from. For a list of the various issues you w
How do I convert my file containing non-English characters, or smart quotes?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are two aspects to this problem:
1. Knowing the encoding of the source file: calibre 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:`Input character encoding` field in the :guilabel:`Look & Feel->Text` section of the conversion dialog. The command-line tools all have an :option:`--input-encoding` option.
1. Knowing the encoding of the source file: calibre 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:`Input character encoding` field in the :guilabel:`Look & Feel->Text` section of the conversion dialog. The command-line tools have an :option:`ebook-convert-txt-input --input-encoding` option.
2. When adding HTML files to calibre, you may need to tell calibre what encoding the files are in. To do this go to :guilabel:`Preferences->Plugins->File Type plugins` and customize the HTML2Zip plugin, telling it what encoding your HTML files are in. Now when you add HTML files to calibre they will be correctly processed. HTML files from different sources often have different encodings, so you may have to change this setting repeatedly. A common encoding for many files from the web is ``cp1252`` and I would suggest you try that first. Note that when converting HTML files, leave the input encoding setting mentioned above blank. This is because the HTML2ZIP plugin automatically converts the HTML files to a standard encoding (utf-8).
What's the deal with Table of Contents in MOBI files?

8
manual/news.rst
View File

@ -291,7 +291,13 @@ The best way to develop new recipes is to use the command line interface. Create
ebook-convert myrecipe.recipe .epub --test -vv --debug-pipeline debug
The command :command:`ebook-convert` will download all the webpages and save them to the EPUB file :file:`myrecipe.epub`. The :option:`-vv` makes ebook-convert spit out a lot of information about what it is doing. The :option:`--test` makes it download only a couple of articles from at most two feeds. In addition, ebook-convert will put the downloaded HTML into the ``debug/input`` directory, where ``debug`` is the directory you specified in the :option:`--debug-pipeline` option.
The command :command:`ebook-convert` will download all the webpages and save
them to the EPUB file :file:`myrecipe.epub`. The ``-vv`` option makes
ebook-convert spit out a lot of information about what it is doing. The
:option:`ebook-convert-recipe-input --test` option makes it download only a couple of articles from at most two
feeds. In addition, ebook-convert will put the downloaded HTML into the
``debug/input`` directory, where ``debug`` is the directory you specified in
the :option:`ebook-convert --debug-pipeline` option.
Once the download is complete, you can look at the downloaded :term:`HTML` by opening the file :file:`debug/input/index.html` in a browser. Once you're satisfied that the download and preprocessing is happening correctly, you can generate ebooks in different formats as shown below::