旧书网购_如何使用狮身人面像赋予旧书新的生命

旧书网购

Internet档案库 ， Project Gutenberg项目和Google图书是历史书籍的绝佳来源，但是其数字化工作的最终产品虽然功能全面，但缺乏最后的润色。 例如，我感兴趣的是历史烹饪，特别是乔治亚风格和摄政时期的英国烹饪以及当代的美国烹饪，但是相关食谱的PDF版本通常只是基本的黑白扫描，没有任何有助于可查找性或可搜索性的功能。 纯文本版本虽然更易于搜索，但在美学上并不令人满意，并且通常包含许多光学字符识别错误。

我的宠物项目之一是通过利用开放源代码文档工具来生产18世纪食谱的基于Web的优美版本，将我对历史烹饪的热爱与对开放源代码的热爱相结合。 完成后，这些书将可以完全搜索并且具有目录和索引的超链接表。 为此，我转向了Sphinx文档构建器 ，该构建器为我提供了一种轻松创建，组织和构建功能性HTML书籍的简单方法，此外，使用Sphinx可以创建PDF和EPUB版本，容易。

我正在转换的第一本书，汉娜·格拉斯（Hannah Glasse）的“ 烹饪简单而简单的艺术 ”，还没有为大众消费做好准备，但是在本文中，我分享了我从该书中学到的知识，以便其他人可以从我的工作流程中学习。 可以将其视为高度专业化的Sphinx教程。 我将要描述的大部分内容是开源文档工作人员的常识，但是我希望通过共享我的过程，我将向具有中等计算机技能的非开源人员教他们可以使用的工具与他们的兴趣爱好相关的公共领域文本更加用户友好。 当然，Sphinx确实需要熟悉命令行，但我将解释复杂的部分。

安装Python和Sphinx

Sphinx是Python项目用来生成自己的文档的工具，因此它是使用Python构建的。 为了开始，您将需要在系统上安装Python。 下载适用于您的操作系统的Python 3.x安装程序 ，或使用Linux发行版的程序包管理器安装Python 3（例如，在Fedora上dnf install python3 ）。

在安装Python时，如果要使用安装程序，请确保选中安装pip的选项，或者在安装要分发的python3软件包时安装相关的软件包。 在Fedora上，该软件包称为python3-pip 。 一旦安装了Python和pip，就可以使用pip软件包管理器安装Sphinx。 在Windows上打开命令提示符，在macOS上打开终端，或者在Linux上选择终端仿真器，然后键入： pip3 install -U sphinx 。 如果您看到错误消息，请在Linux和macOS上使用sudo开头命令，或者使用“以管理员身份运行”选项在Windows上启动命令提示符，以特权用户身份重新运行命令。 根据系统的配置方式，可能会提示您输入管理员密码。

一旦安装成功，您将拥有开始使用Sphinx所需的一切。 此外，还可以安装其他软件包以提供更多选项。

设置一个新的Sphinx项目

要创建新的Sphinx项目，请打开命令提示符或终端，使用cd导航到要在其中存储项目的位置（例如/ home / USERNAME / Projects），然后运行sphinx-quickstart命令。 快速入门将提示您提供有关项目的信息，并选择各种配置选项。 请注意，在Windows中，快速入门的提示将被胡扯的字符包围，但这是无害的，并且快速入门也可以正常运行。 第一个提示，“文档的根路径。”，让您设置项目的位置。

如果从要存储文件的目录中运行sphinx-quickstart命令，则可以按键盘上的Enter键以接受默认值。 如果要将项目存储在当前工作目录的子目录中，请在提示符下输入该子目录的名称，Sphinx将创建目录并将所有项目文件存储在该位置。

接下来，将提示您有关使用单独的“源”和“构建”目录的信息。 缺省值为no，它将源文件放置在项目的根目录中，并且构建将以“ _build”子目录结束。 选择默认值是完全可以的，但是如果要使源文件和构建文件更分开，则可以选择“是”。 这会将源文件放在“源”子目录中，而生成的输出将进入“生成”子目录中。

第三个提示允许您更改“ _static”和“ _template”子目录的前缀。 没有令人信服的理由将其更改为默认选项。

接下来的两个提示是项目名称和作者名称。 项目名称可以是您要转换的书的标题，但是使用原始书的作者姓名作为作者字段可能会导致一些奇怪的现象，例如在页脚的版权信息中，当年逝世的作者姓名出现在当年旁边。 由您决定如何最好地处理作者字段，但是我将其设置为我的名字，并将原始作者归功于项目文本中。

然后将提示您为项目分配版本号和发行号，在这种情况下，这没有什么意义，但这是必填字段。 随意将其设置为最适合您的设置。 对于“ beta”版本，可以将其设置为小于1的数字，并在逐步阅读完成的书时将其递增为1.0，也可以将版本和版本设置为原始书的发行年份，而不必担心更新它。

下一个设置，即项目的语言选项，应设置为书籍的原始语言。 通过将语言选项设置为书籍最初使用的语言，Sphinx可以在网站标题中使用正确的语言元数据创建输出，并以正确的语言生成文本，例如“目录”和“快速搜索”。

对于大多数用户，接下来的两个提示应设置为默认值。 两个提示中的第一个提示要求用户选择项目文件的文件扩展名。 默认为.rst（对于Sphinx使用的标记语言reStructedText），因此没有理由对其进行更改。 第二个提示询问用于项目的主文件的名称。 该文件是网站主页和目录内容所在的位置。 默认情况下，此文件称为“ index.rst”，其中“ index”部分来自在此提示符下输入的内容，而“ .rst”扩展名来自上一个提示符。 如果您确实希望将其更改为“ frontmatter”或其他名称，以使其与使用书名的索引名不冲突，则可以，但是没有什么理由。

下一组提示都与Sphinx扩展有关。 对于这样的项目，可以肯定地说不。 唯一的例外是，如果您打算使用GitHub页面托管完成的网站，则应对“创建.nojekyll文件”提示说是。

最后，将询问您是否要创建一个Make文件和一个Windows命令文件，这些文件可用于生成HTML输出，而不必运行sphinx-build并手动指定输入和输出目录。 如果您计划与使用不同操作系统的其他人进行协作，则应该对与您的系统相关的选项（是macOS和Linux的Make文件，或者对于Windows的Windows命令文件）说“是”，或者对两者都说“是”。 Linux和macOS用户将需要确保在其系统上安装了make ，但是Windows命令文件将在不安装任何额外内容的情况下运行。

创建章节并添加内容

设置完成后，您就不用管命令行了，直到需要构建最终产品为止。 所有内容的创建和编辑都可以在文本编辑器中进行。 GitHub的Atom编辑器是一个很好的选择，但是只要保存纯文本文件，任何文本编辑器都可以使用。

首先在Atom或您选择的文本编辑器中打开项目的“ index.rst”文件。 通过列出此书中将包含的所有文件，可以在此文件中构建目录。 在这里，您还可以包括要转换的书中的所有其他主题，例如书名页。

您应该对“ index.rst”进行的第一个编辑是删除“索引和表格”标题下的“ *：ref：`modindex`”行。 这种项目完全没有必要。 然后，您可以修改“ index.rst”的文本以适合您项目的需要。 下方带有等号的行是标题，可以将其文本更改为与转换的书最匹配的内容。 例如，“欢迎使用[您的项目名称]的文档！” 可以用本书的实际书名代替。 可以更改或删除显示为“ Contents：”的行，无论哪种方式最适合您的项目（实际上，您可以根据需要添加任意数量的文本），只需确保保留“ .. toctree ::”和“：”即可。 maxdepth：2英寸的线条完整。

要建立目录并开始构建项目，您将在“：maxdepth：2”行之后留一个空白行，并开始列出要包含在书中的内容。 您需要缩进列表，以便它与“：maxdepth：2”行中的初始冒号对齐，因此在文本开头之前三个空格。 这些部分需要按顺序排列，因此在“ chapter1”之前应有“简介”一章，依此类推。 这些行不应具有“ .rst”文件扩展名，但是当您为不同章节创建文件时，将使用“ index.rst” 和 “ .rst”扩展名中列出的相同名称来保存它们。 例如，您将在“ index.rst”文件中一行读取“ chapter1”，但是包含第1章内容的文件将具有文件名“ chapter1.rst”。 为简单起见，请将所有文件与“ index.rst”文件保存在同一目录中。

创建一章并为其填充内容涉及到在文本编辑器中创建一个新文件，以您希望的任何方式（手动转录，复制和粘贴OCRed文本，或最适合您的方式）从书中添加内容，以及使用适当的文件名保存文件（例如，对于“ index.rst”中列为“ chapter1”的章节，使用“ chapter1.rst”）。 大多数工作来自正确地设置文本格式，并且考虑到reStructedText相当简单的标记，这并不太费力或复杂。

处理较旧的文本时，您最需要了解的是如何制作标题：在一行文本下包含一系列=，子标题：在一行文本下包含一系列-，粗体文本：带有**的文本左侧和右侧以及斜体文本：在左侧和右侧带有*的文本。 有一点要注意的是，表的内容使用标题生成的，所以一定要包括在每个文件的开头至少一个标题（也可以是“ 第十章”与=在下面的横线的迹象，如果这本书你正在处理，其各章均不包含文本标题。）

如果您想使用更高级的格式设置，可以在reStructedText文档中找到更多的reStructedText格式设置选项。 虽然Sphinx可以重现旧书的大多数印刷功能，但是使用现代键盘键入“ Long S ”和各种连字是很耗时的，因此您应该决定是否要包括它们。 您可能想寻求真实性或选择简单性。

您将发现几乎无法重新创建的功能是每页底部的打印机标语 ，因为将书转换为HTML的最简单方法是基于章节，因此显然不会保留分页。 如果您确实坚持保留流行语，则可以进行劳动密集型的工作，即为每个页面创建一个文件并以这种方式组织您的项目，但是最终结果仍然不是完美的。

重新创建书的索引

获取一本书的索引并重新创建它以创建超链接索引，这可能是此过程中最费力的部分。 您将通读本书的索引，查找章节的相关部分，无论是食谱还是其他类型的文本，并在适当位置包括Sphinx的index指令，从而对索引进行反向工程。 要重新创建一个读为“牛肉，如何烤制”的索引条目，您将找到相关的配方，并在其后添加“ .. index :: Beef; How to roast”行。 然后，索引将包含一个“牛肉”主条目和一个“如何烘烤”子条目，这些条目具有指向相关配方的链接。

建立网站

在为要转换的书中的每一章创建文件后，用所有原始内容填充这些文件，并重新创建索引，您需要创建完成HTML。 经过所有的辛苦工作，这是最简单的步骤。 在命令行的项目根目录中，输入make html 。 这将构建您的网站并将最终产品放置在“ build”目录或“ _build”目录中，具体取决于您在运行快速入门时是否选择将源目录和构建目录分开（如果将它们分开，则为“ build”，如果没有，则为“ _build”。）还有更多的构建选项，例如EPUB和PDF。 其中一些选项需要其他软件，因此请查看Sphinx文档以获取详细信息。 在Sphinx的文档中，您还将找到有关大量高级设置和其他选项的信息，如果您想进一步调整已完成的项目，这可能会有所帮助。

通过这些步骤，您为一本旧书赋予了新的生命。

翻译自: https://opensource.com/article/16/11/how-use-sphinx-book-to-web

旧书网购