综合技术文献工具

Question

背景

寻求统一的技术文档，连接计算机和用户生成的内容，使用开源工具.目标是以与输出无关的文件格式编写(或生成)内容，然后将其转换为最终文档。下图帮助说明了整体的连接方式。

解决方案应该是独立于操作系统的。

输出特征

最后文件必须包括：

• 表格
• 数字
• 代码段
• 自动编号的标题(用于表、数字和代码段)
• 交叉引用(超链接到表、图和书目引用)
• 标题(最多7个级别；1.、1.1.、.、1.1.1.1.1.1.1.)
• 附录(最多七级；A、A.1、.、A.1.1.1.1.1.1.)
• 自动编号标题和附录
• 目录(超级链接)
• 表列表(超链接)
• 数字清单(超链接)
• 书目(书籍、文章、期刊、白皮书、网站超链)
  • 各种格式(APA、芝加哥、IEEE等)

最重要的是，样式化(通过模板或编码)应该是可能的，这样所有的文档都可以用新的外观和感觉重新生成。例如，ConTeXt在这方面很擅长。

Markdown和Pandoc提供了很多这种功能，但我不确定它是否处理交叉引用、自动标题、书目和代码片段。

输入特征

• 跨文档变量 (例如，服务器名称只记录一次，但由应用程序体系结构和软件需求规范引用)。
• 基于浏览器的WYSIWYG编辑器(可能合并)
  • 表编辑器
  • 移除 (嵌入式摘录以帮助单一来源的内容)
  • 协作(理想情况下，实时)
  • 修订版
  • 标记(查看源代码的能力，但主要用于现代文字处理器)

• 计算机生成的内容被转换为Markdown格式：
  • 源代码文档(包描述，不需要超链接内容)；Javadocs，DO2等。
  • SNMP (网络设备的名称和IP地址)
  • 图(实体-关系，UML，GraphViz等)
    • 理想情况下，可以导入JPG、PNG和SVG映像。

- List of database surrogate keys and descriptions (dumped from database)

问题

它甚至有可能生成一个高质量的技术文档，其中包括各种各样的工件，只使用Markdown作为源内容？

以下是我希望得到的建议或建议：

• 包括源代码(例如，Javadoc/ code -> Markdown)
• 可能将各种*nix命令输出重新格式化为Markdown (nmap、traceroute、ls、tree、df、SNMP输出等)；例如，可以使用awk和sed对转换进行转换。
• 所见即所得编辑器(自由和开放源码软件替代方案到汇合点)
• 它可以处理从Markdown源到所需的输出格式(PDF绝对和MS可选)的输出特性。
  • 如果Pandoc/ConTeXt不能完成这一壮举，什么可以完成呢？

• 用于集成书目和交叉引用的软件和/或数据格式(例如，Markdown、YAML)，以便文档生成器(例如ConTeXt)可以使用它们(例如，RStudio)？

如果有一个将所有这些特性结合在一起的软件包，我也很想知道这一点。

相关

相关问题包括：

• Wiki取代微软字

软件

• http://rapporter.github.io/pander/
• http://pandoc.org/
• https://www.r-project.org/

Specifications

• https://daringfireball.net/projects/markdown/syntax
• http://blog.martinfenner.org/2013/06/19/citations-in-scholarly-markdown/
• http://www.oracle.com/technetwork/articles/java/index-jsp-135444.html

Answer 1

我相当肯定，这将是一个小小的工作，您可以使用狮身人面像文档提供非常类似于您所描述的内容。您可能遇到问题的一个领域是实时协作编辑。

• 基本格式是重新构造的文本(而不是标记)，但是输入可以在减价中。
• 多输出格式
• 多个输入源，包括源代码、wiki、在线等.
• 可以在构建过程中调用和发布多个工具。
• 交叉平台
• 开放源码
• 生成非常好看的文档
• 所有您所要求的输出功能都可用
• 模板-是的
• 生成多个输出格式的文档-是的
• 由于Pygments，代码片段在多种语言中的语法突出显示。
• 广泛的交叉引用:函数、类、引文、术语表术语和类似信息的语义标记和自动链接。
• 良好的国际化支持使用gettext。
• 可扩展和积极开发。