下午好
作为开源
Embox项目的开发人员之一，我经常（最近经常）听说该项目很有趣，但是由于没有文档，因此无法使用。 我们答复说，有某种文档，我们总是可以回答问题，在极端情况下，您可以尝试自己解决这个问题，因为该项目是开放的，但所有这些都不适合。 对于开发人员，我不得不处理这个非常不愉快的话题。 但是自然地，本文不是关于文档“令人不愉快”的事实！ 关于我们如何使文档开发过程更加舒适。 确实，在任何或多或少的大型项目中，必然会出现与文档相关的问题。
对于那些懒得看书的人，我会马上说，最后我们开始以markdown格式开发文档。 好吧，对于那些对细节感兴趣，减价的原因以及这种方法的利弊的人，我要求猫。
我将从证明该主题的相关性开始。 Embox不仅存在文档问题。 例如，Google宣布了面向技术作家
Season of Docs的Google Summer Of Code（GSOC）计划的类似产品。 卡巴斯基实验室公司
为技术作家举行
会议 。 并且Parallels公司
在该集线器上发表
有关如何写文档的文章 。 所有这些都表明该主题很重要，也许不应该引起人们的关注。
上面提到的系列文章理解了文档的正确内容，但是，如果您愿意的话，我想重点介绍文档，技术的开发过程。 的确，对于一个开源项目而言，其特点是开放性是开发过程的一种属性。 我们想创建一个满足项目要求的流程。
简要介绍我们的文档开发过程的历史。
一旦项目位于
googlecode上 。 我们有一个相当不错的Wiki，许多人甚至还记得它，询问在哪里找到它，并要求将其转移到项目现在所在的github（或在另一个可访问的位置）。 googlecode Wiki非常方便。 它是多语言的，在我看来，它具有比github上的Wiki更多的功能。 但是碰巧它与googlecode本身一起被遗忘了。 github上当前的wiki在交付有关项目的运营信息方面表现良好，但是在此平台上创建完整的文档非常困难。
当然，对于任何开源项目，您都需要在线（可快速访问）在线文档（由Wiki扮演角色）和完整的离线文档（因为可以更轻松地理解项目的本质和意识形态）。 此外，对单个文档（而不是不同的Wiki页面）进行脱机搜索也更加容易。
我知道的最好的选择可能是
ARM文档 。 也就是说，在线文档中所有部分都进行了搜索，但是可以以pdf格式下载特定文档。 不幸的是，就功能而言，Embox尚未达到ARM的水平。 因此，我们必须单独制作脱机版本。 为此，我们使用了
Google Docs服务。 之所以方便，是因为：它使您可以下载各种格式的数据，进行协作并具有内置的版本控制系统。 我们从Wiki转移了一些信息，设置了结构，因为开发离线版本的目的是创建整体文档，并开始开发多个文档。 但是足够快，我们遇到了问题。 信息已过时，Wiki中的数据与脱机文档中的数据不匹配，最重要的是，我们无法创建完整的文档。 虽然有一个结构，但由于无法从用户那里得到体面的反馈，因此事实证明只有其创建者才能理解文档。 这当然不是服务问题，但正如他们所说，事实是显而易见的。 我们必须寻找解决此问题的另一种方法。
然后，我们试图将数据从旧的Wiki传输到Wiki github，但是即使如此，我们仍然迅速遇到了问题。 我们发现部分信息已过时，部分信息尚未添加，部分信息不清楚如何以用户友好的形式呈现。 在某种程度上，继续寻找问题的解决方案时，我们甚至考虑使用git存储库在TeX中开发文档，但是很快意识到这已经太多了。 虽然这个想法产生了影响。
我们决定从文档中制定我们想要的东西，这意味着在文档开发过程中，我们将内容放在方括号之外：
- 该文档应以文本格式保存，因为它应该使用git作为版本控制系统
- 该文档应具有在线（wiki）和离线（单独的文档，例如pdf）版本
- 联机和脱机文档应能够轻松同步。
- 文档应包含可单独开发或研究的部分（章节），但您可以从中组成完整的文档
没有一点与markdown的使用相抵触，这很有趣，因为它已在Wiki上使用。 当然，您可以使用其他格式并将其转换为markdown。 但是，在编制了另一组需求列表之后，这次是添加各种内容（图像，文本，格式）的功能，我们得出的结论是，降价足以满足我们当前的所有需求。 最早在Google上搜索“将markdown转换为pdf”的主题的Google表示，存在将markdown转换为其他格式的选项，并且非常受欢迎。
有多种方法可以将markdown转换为pdf ，但是
pandoc迄今为止最受欢迎。 该实用程序可以将任何文本格式转换为任何文本格式。 另外，它是悬臂的。 因此，它不仅是我们熟悉的，而且还可以内置到脚本中以创建各种格式的文档。
我们决定使用该实用程序，并开始考虑下一个必须解决的小问题，即如何制作单个文档，而不是从单独的markdown文件中获得的许多带有不同章节的pdf文件。 最初的需求只是简单地按照所需的顺序“保存”文件（合并来自不同文件的文本），但是事实证明它要简单得多，pandoc本身完全能够处理文件列表。 这也使我们能够部分解决需要内容可能相交的各种文档的问题。 例如，我们生成了三个文档，所有三个文档都包含一个简短的描述部分。 我们只需在所有文档的pandoc列表中列出此文件即可。
我们对包含文档标题的封面应用类似的原则，依此类推。 我们只是为每个文档创建了带有标题的文件，并将它们作为pandoc的源列表中的第一个文件。
您可能已经猜到了，这（不同文件的列表）解决了多语言问题，我们只用所需的语言指定文件。
让我们再谈一点俄语。 生成pdf时，pandoc使用乳胶作为后端进行渲染，拼写检查等。 默认情况下，不显示西里尔字母，并且显示有关未知字符的错误。 这很简单地解决，只需指定“ Babel Russian”即可。
--- ... header-includes: - \usepackage[russian]{babel} ---
应该指出的是，指出
--- ... header-includes: - \usepackage[russian, english]{babel} ---
并在文本中使用乳胶命令
\selectlanguage{russian} \foreignlanguage{english}{ English text }
或
\begin{otherlanguage}{english} Text in english \end{otherlanguage}
但是，由于我们希望保持“干净”的减价以便可能转移到Wiki，并且事实证明babel指令足以满足我们的目的，因此我们决定不对其进行复杂化，并保留原样。
当然，我们希望没有任何格式的文档，但至少看起来要统一。 乳胶再次帮助了我们。 事实是，由于pandoc使用乳胶，因此您可以为其指定乳胶模板。 只需使用--template选项即可完成
pandoc --template=embox_pandoc.latex ...
编译完模板并在生成所有文档时指定了模板之后，您将以大致相同的样式获得文档。 “或多或少”-因为我们无法解决一些问题。 例如，形成单个代码块。 在markdown中，可以指定单个代码块，以便不进行格式化，并且可以打开语法突出显示。 但是我们设法只制作了一行代码。 在查看生成的乳胶代码后发现。
也就是说，在某些情况下，相同的块放在不同的文档上会有一些不同。
另一点与西里尔字母有关，即使用俄语。 如上所述，要使用俄语，事实证明足以在标头中指定俄语通天塔。 但是我们遇到了一些奇怪的问题，例如，没有大胆的突出显示和其他格式上的奇怪问题。 最初，我们犯了一个事实，即俄语是用大写字母而不是模板指定的。 他们开始研究这个问题。 事实证明，以一种很好的方式，您不仅需要使用
\usepackage[russian, english]{babel}
还要
设置字体 \usepackage[T1,T2A]{fontenc} \usepackage[utf8]{inputenc}
但是即使这样做，也无法纠正这种情况。 事实证明，并非所有字体集都包含所有渲染选项，特别是我们的字体集不包含粗体，斜体等其他格式。 由于没有简单的解决方案，因此我们考虑并将问题推迟到更好的时候。 好吧，由于我们想使用一个干净的markdown（即不指定乳胶命令），因此我们为这两种语言制作了一个通用模板，并且在标题中添加了有关俄语的指示。
关于应用程序本身的界面，我只想说几句话。 因为，正如我所说，控制台应用程序对我们个人来说是非常熟悉的，并且很容易打包到脚本中。 实际上，该界面很简单，您当然可以设置许多选项，但是就我们的目的而言，指定一个模板，一个输入文件列表和一个输出文件就足够了。
pandoc --template=embox_pandoc.latex <title file> <list of input markdown files> -o <output file>
在Internet上，您可以发现要生成pdf（或其他输出格式），您需要使用--pdf-engine = xelatex选项的处理器类型，但是默认情况下，如果输出文件具有pdf扩展名，则使用该处理器类型。 因此，我们也不需要这个。
我们将用于汇编文档的脚本打包在一个Makefile中，以使它变得非常熟悉。 现在，要获取文档，您可以设置必要的环境，只需调用
make [en][ru]
总结一下，有关版本控制系统的几句话。 原则不是使我们努力坚持的一切变得复杂（保持简单）。 由于最简单的解决方案是在github上使用单独的存储库，因此
我们做到了 。 我们希望使用github可以改善用户反馈。 毕竟，正如您在github上所知道的那样，您可以在其中讨论缺点并提供您的想法和方向。
这个过程是在许多工人的要求下最近启动的！ 我们设法制作了
英文和
俄文版的“快速入门”，以及
俄文版用户手册的第一版 。 在我们看来，此过程本身更为方便，因此我们与公众分享了这一过程。