65.9K
CodeProject 正在变化。 阅读更多。
Home

文章撰写的有用工具链

Sergey Alexandrovich Kryukov
starIconstarIconstarIconstarIconstarIcon

5.00/5 (9投票s)

2017 年 3 月 22 日

CPOL

13分钟阅读

viewsIcon

20794

downloadIcon

119

这个工具链（v.2）帮助我加快了文章写作速度，减少了错误，节省了大量时间；我的一些建议可能会有所帮助。

引言

我想向世界说一个新词。既然未能如愿，我便成了一名作家。

Stanisław Jerzy Lec

目录

写作很烦人

在经历了一段不太顺畅的写作过程后，我开始思考如何让它变得不那么痛苦。事实上，写文章很容易陷入无数令人烦恼的细节中：确保所有锚点唯一且与 HREF 匹配，所有链接正确，样式一致等等。很容易忘记无数细微之处，从而分散对文章本身的主题和目标的注意力。试图推迟所有令人烦恼的工作帮助不大；毕竟，强迫自己去做这部分工作变得越来越难。

实际上，CodeProject 文章编辑器支持一致的编辑过程，但它缺少一个最重要的功能：自动生成的目录（TOC）和自动生成的交叉引用，尤其是 TOC 和标题之间的。我必须要有这个功能，就是这样。此外，对于慢速互联网连接，在线编辑将过于缓慢。

因此，我为减轻痛苦、使写作更稳定和更愉快所做的努力开始获得回报：我的工作速度大大加快，消除了许多干扰，现在感觉非常好。我希望我的研究成果能帮助很多人。这是一种相当枯燥的研究；没有必要每个人都走这条路；最好是利用别人的经验。我的 工具链 远非完美，但我认为它在工具投入和文章写作本身之间取得了不错的平衡。

同时，如果有人能提出一些改进建议、提供一些信息性批评，或许还有一些更好的想法，我将非常感激。

对于那些使用纯文本作为源文件（可能是最佳选择）的人来说，该工具链是跨平台的，但对于那些想从 MS Word 开始的人来说，它是 Windows 特有的。

Pandoc 和 Wiki

经过一些搜索、一些试错工作，花费了我大量的时间，我最终使用了开源的 Pandoc 转换器，并用它将 Wiki 转换为 HTML。

CodeProject 风格，以及任何合理的文章写作风格，都可以通过 Wiki 很好地匹配。在这两种方法中，都鼓励采用严格、适度和一致的风格。所有文章看起来都应该非常相似；颜色和效果不应过于张扬。文章作者应该通过想法和品味脱颖而出，而不是通过廉价的效果。

因此，第一个选择是将 Wiki 文本作为文章源文件。

TWiki

Pandoc 支持的 Wiki 输入格式不多，并且支持远非全面。请参阅我包含在 ZIP 文件中的文档，您可以从本页面下载该文件。

我选择了 TWiki，它不是最流行的 Wiki 标记语言，因为我认为它最接近所需的 CodeProject 特有功能，并且完成了必需的最低限度。一个非常有吸引力的功能是它能够轻松渲染最常用的 CodeProject 元素：行内代码片段。它像这样渲染 像这样的文本，在源代码中显示为 =这样的文本=。这难道不简单吗？

一个真正大的问题是块状代码示例。出于某些原因，Pandoc 在 pre 元素内部生成一个 code 元素，这严重破坏了整个代码片段的格式。我找到的最好的解决方法也得益于 TWiki。我的示例标记 在此处 显示；它还可以解决代码示例的锚点问题，即使是手动 HTML 编码也会有些麻烦。

记住 CodeProject 要求顶层标题为 h2 非常重要。在 TWiki 中，它是这样写的：

---++Top-Level Article Section Heading

通过适当的 Pandoc 选项，目录（TOC）会自动构建，所有标题都带有自动锚点，并与 TOC href 匹配。目前，TWiki 不支持自动编号的 TOC，但这也不是太糟糕，因为 CodeProject 文章风格是为交互式阅读设计的。此外，让某些标题不显示在 TOC 中也很重要；这可以通过 Pandoc 参数来完成，该参数指定 TOC 中标题的最大级别。我将在 脚本代码 中进行解释。

展示 TWiki 格式的示例意义不大。我已经展示了三种情况；应该足够了。为了更好地理解，参照 文档 会更容易。

脚本/批处理

我们花一些时间来节省未来的时间，而不是浪费它，对吧？以上所有内容只有在几乎所有后续步骤都通过单击脚本一次来自动执行时才能节省时间。我现在的脚本是 Windows 特有的，但只需将几行代码翻译成其他平台的脚本语言即可。

这是我为 Windows 建议的，一个批处理文件 wiki2Html.bat

@echo off

:: modify next two lines to point to the directories
:: where Pandoc is installed and where the input files are:
set tool=c:/app/Media/eBookAuthoring/Pandoc/pandoc.exe
set data=./

for %%f in (%data%*. wiki) do call:proc %%~nf
goto:eof

:proc
%tool% -s -S --read=twiki --toc --toc-depth 5 -B title.txt -H style.css -o %1.html %1.wiki
goto:eof

proc 部分是一个真实的子例程，带返回值。我需要它，因为它最方便地将更多行添加到每个项目的处理程序中。

在我使用的 Pandoc 选项中，涉及 4 个文件。显然，“%1.wiki”是输入文件，“%1.html”是输出文件。-s 选项表示 stand-along，它会生成完整格式正确的 HTML，而不是一个片段。使用此选项时，重要的是拥有 HTML 结构的钩子。-H 选项指定用作 head 元素子项的文件。在我的示例中，这实际上不是 CSS，而是一个包含 CSS 的完整 style 元素。此文件不会在 CodeProject 中使用，但最好有一些样式设置，用于在发布前进行渲染预览。另一个钩子 -B (title.txt) 指定 HTML body 最顶部的内容，在 TOC 之上。这是放置文章名称、作者姓名、图片、题词、“目录”或“Table of Contents”等的地方。

看看我的“style.css”文件示例。 “title.txt”文件是我当前文章中的一个示例。这些文件可以在本页面下载的 ZIP 文件中找到。

--toc 和 --toc-depth 参数指定 TOC 中是否存在 TOC 和最大标题深度。

使用 -S (--smart) 选项可以简化重要 Unicode 字符的输入：-- 渲染为 en-dash，--- 渲染为 em-dash，... 渲染为单个省略号；ASCII 引号 U+27 和撇号 U+22（也用于引号）被渲染为 Unicode 对 ‘、’、“ 和 =”=；根据上下文选择对的左侧或右侧成员。另请参阅：注意排版。

我在我的 文档 中详细描述了这种行为，该文档是针对名为 “Extensible Markdown Converter” 的 Visual Studio Code 扩展的。该扩展基于 node.js 模块 “markdown-it”，这是实现此行为的产品之一。

最痛苦的组件：MS Word

这个过程中最让我恼火的是 Word。它很难控制。即使关闭了所有自动更正，也是 Word 决定添加额外的空格或在行之间添加什么字符，而不是我。尽管如此，我仍然在使用它，原因只有一个：它有一个语法检查器，而不仅仅是拼写检查器。也许最好的方法是只使用 Word 进行最终校对，但那样的话，最好有另一个编辑器可以在我们输入时显示错误的拼写。

无论如何，我将展示艰难的方式，即源文本始终是 .DOCX。问题是：最简单的方法是从 Word 复制粘贴到 Wiki 文本，但即使是这个快速操作也会严重干扰写作：我们需要经常重新渲染文本。

为此，我开发了一个基于 ActiveXObject 脚本的脚本（叹气……）。这是一种相当过时的技术，但在 Windows 上，.bat 和 Windows Scripting Host (WSH) 是唯一无需安装任何东西即可工作的技术。此脚本仅执行一步：它从 World 文档中提取纯文本，以便可以将其添加到通用脚本中。此类事物的最佳形式是 .WSF。这是一个用 XML 包装器编写的 JavaScript（或 VBS）；这样的文件只需单击一次即可执行。我的脚本就是这样的：

<job>
<script language="JScript" src="wsh.js"></script>
<script language="JScript">

var options = {
    ext: ".out.txt",
    title: "Convert MS Word to plain text",
    last: undefined
}; //options

(function() {

    String.prototype.replaceAll = function(search, replacement) {
            var target = this;
            return target.split(search).join(replacement);
    };
 
    var files = FileSystem.requireInputFilesGetOneOutputFile(1, options.ext);
    if (!files.files) {
        Shell.errorBox(files, options.title);
        return;
    } //if
    var fname = FileSystem.expandFileName(files.files[0]);

    var doc = new ActiveXObject("Word.Application");
    doc.Visible = false;
    doc.Documents.Open(fname);
    var txt = doc.Documents.Open(fname).Content;
    txt = "" + txt;
    txt = txt.replaceAll(String.fromCharCode(11),  String.fromCharCode(13)+String.fromCharCode(10) );
    doc.quit(0);
    FileSystem.writeAllText(files.outputFile, txt);

})();

</script></job>

这里要注意的部分是 txt.replaceAll 行。这是为了解决一个非常令人烦恼的问题：导出的 Word 文本在某些行之间包含 VTAB 字符（代码点 11）；并且在标准编辑模式下，肉眼看不出区别。

此脚本使用另一个名为“wsh.js”的脚本，该脚本是用 JavaScript 编写的，但这只是文件系统操作和命令行解析。请参考本页面可下载的代码。使用 WSH 脚本后，主脚本（此变体在本页面下载的 ZIP 文件中名为 docx.wiki2Html.bat）如下所示：

@echo off

:: modify next two lines to point to the directories
:: where Pandoc is installed and where the input files are:
set tool=c:/app/Media/eBookAuthoring/Pandoc/pandoc.exe
set data=./

set tmpFile=____tmp.txt

for %%f in (%data%*.docx) do call:proc %%~nf
goto:eof

:proc
.\process\Docx2Text.wsf %1.docx -o:%tmpFile%
%tool% -s -S --read=twiki --toc -B title.txt -H style.css -o %1.html %tmpFile%
del %tmpFile% 
goto:eof

所以，这是那个一键完成所有工作的那个文件。它可以经常执行，而无需关闭 Word。

这里最令人头痛的问题之一是：Word 仅以 UTF-16LE 格式存储 Unicode，而 Pandoc 只处理 UTF-8，但最糟糕的是 "Scripting.FileSystemObject" 只接受 ASCI 或 UTF-16，并在收到 UTF-8 时出错。正如我们过去经常看到的，Microsoft 与 Microsoft 不兼容。我知道 WSH 是一种过时的技术，但这并不能减轻它在地狱中为某些东西保留的温暖位置。这就是要避免在 Word 中使用 Unicode 的原因。对于英文文章来说，这并非严重问题，因为少数字符可以写成 HTML 实体。将所有字符转换为 HTML 的实用程序是无用的，因为我们首先需要获取文本。

Visual Studio

幸运的是，我们大多数人使用的软件开发工具都很准确、方便，但并非为写作文章而设计。好吧，不完全是。我们只需要一个带拼写检查器的好文本编辑器。这些要求没什么特别的。毕竟，我发现我可以将拼写检查器添加到我经常使用的工具之一：Microsoft Visual Studio 2015。所以，我终于摆脱了 Microsoft Word（嗯，更确切地说，摆脱了保留任何 Word 文档；我只使用 Word 进行文章的最终校对，但不在磁盘上创建任何文档）。

我现在选择的拼写检查器叫做“Visual Studio Spell Checker (VS2013/VS2015)”。

感觉如何？嗯，并非一切都如承诺的那样工作；有一些客户的问题报告，但它在不引起过多关注的情况下完成了最基本的工作，首先是“即时检查”。即使没有语法检查，拼写检查也能使整个工作更有效率。这是软件开发，对吧？已安装的预定义规则已经能够很好地处理计算机相关的科目。例如，驼峰式大小写的单词、其他可以识别为计算机语言构造的单词都会被忽略。设置易于理解，并且可以本地与项目一起保存。

我能够更改选项并观察其效果。不幸的是，并非一切都奏效：正则表达式忽略不起作用，但将单词添加到本地词汇表中却很方便。换句话说，该工具是相当可用的。

当然，可以包含 wiki 文件在内的任何与文章相关的项目，并在一个解决方案中完成所有工作。如果开发工具不同，最好将 Visual Studio 的使用降到最低。我发现仅有一个解决方案，没有项目，就足够方便了；所有文章项目都可以作为“解决方案项”添加到解决方案中。

请参阅 ZIP 文件中提供的示例“Article.sln”和“SampleArticle.html”（以及上面解释的另外两个文件）。

CodeProject 特有

CodeProject 编辑器在 Source (HTML) 模式下（工具箱右侧的按钮）能很好地处理上述过程生成的 HTML 代码。只有在 WYSIWYG 模式下进行小的热修复会更好；结果可能不可预测。最好在 HTML 中完成，准确地保留格式正确的 HTML；否则，提交脚本会尝试修复它，结果也可能不可预测。

只有几个微妙的特点

  1. 列表可以是项目符号列表或编号列表。目录（TOC）由 Pandoc 生成，没有自动编号，因此将以项目符号呈现。要避免它们，可以将属性 style="list-style: none;" 添加到 ul 元素。
  2. 嵌套的 TOC 将在内部 ul 元素周围呈现顶部和底部边距不一致。可以通过将属性 style="list-style: none; margin-top:0; margin-bottom:0;" 添加到内部 ul 来修复。
  3. 所有锚点都应使用 id 属性创建。它不适用于 pre 元素，可能是因为 CodeProject 会动态渲染它，带有隐藏/显示/复制操作。解决方法如下，从 TWiki 文本开始：
<literal><i id="someAnchor"></i><pre lang="c#">

SomeCSharpCode(forExample);

</pre></literal>

这是所有必需的后期处理，但如果可用的 CodeProject 样式能够在没有任何后期处理的情况下完成，我将非常高兴。

现在，一些有用的 CodeProject 特定标记惯用法

下载 ZIP 文件

<ul class="download">
    <li><a href="MyFile.zip">Download source code &mdash; 112.1 KB</a></li>
</ul>

CodeProject 编辑器可以自动添加此类标记，基于下载的文件，但有些作者错过了。

另请注意：&mdash; 代替 破折号。

块引用

 

<blockquote class="FQ" id="epigraph">
<div class="FQA">Master said:</div>

<p><i>The wise phrase to convince anyone</i></p>

<dl>
    <dd><a href="https://author/url.org">Some Author</a></dd>
</dl>
</blockquote>

注意排版

只需注意这一点。破折号字符不是‘-’，而是 &mdash; 或 &ndash;；而且“不是最佳或排版标准的引号：它使自动文本搜索更困难，因为左标记与右标记相同。标准的 Unicode &lsquo;、&rsquo;、&ldquo; 和 &rdquo; 是不同的，看起来更具文化性。即使是减号也不是‘-’而是 &minus;，具有更好的可见性；‘-’只是破折号字符。我列出了大多数文章所需的所有字符。这些规则并不难遵守，尤其是如果 使用了合适的软件。

查阅字符映射表（Windows 上的“charmap”，大多数 Linux 发行版上的“gucharmap”）或 HTML 字符实体。请注意：并非所有系统都能渲染所有这些字符，但我上面列出的简短子集完全没问题。

版本

初始版本

2017 年 3 月 22 日

V. 2

2017 年 3 月 28 日

添加了关于 Visual Studio 和 VS 2015 解决方案的建议。

新工具链

2017 年 6 月 29 日

新工具链已在另一篇文章中发布：使用 Visual Studio Code 的一体化文章写作工具链。

由于这个新工具链是一体的，并且基于 Visual Studio Code，它本身就很好，而且加载速度比 Visual Studio 2015 快几个数量级，它可能会使本文提供的工具链几乎过时。

然而，与 Microsoft Office Word 相关的代码仍然可能有些价值，以及关于 TWiki 和 Pandoc 等工具的有用信息。

结束语

本文是使用本文描述的工具链编写的。:-)

写作愉快！

© . All rights reserved.