example-aless80 1.5.4

DocOnce是一种标记语言，具有Markdown类似的标签，针对涉及大量文本中的数学和代码的科学报告、软件文档、书籍、博客文章和幻灯片。从DocOnce源可以生成LaTeX、Sphinx、HTML、IPython笔记本、Markdown、MediaWiki和其他格式。这意味着您可以从单一源获取针对纸张、平板电脑和手机的最新发布技术。

文档

• 教程： Sphinx，HTML，PDF
• 手册： Sphinx，HTML，PDF
• 快速参考： Sphinx，HTML，PDF
• 故障排除和常见问题解答： Sphinx，HTML，PDF

本教程介绍了科学文档的基本语法和最基本元素，而手册则累积了所有不同的功能。开始的最有效方法是查看报告演示并学习源代码（它包含所有基本元素，如标题、作者、摘要、目录、标题、注释、行内数学公式、单/多个方程、带编号和无编号、标签、章节和方程的交叉引用、项目符号列表、编号列表、从文件复制计算机代码、行内计算机代码、索引条目、图表、表格和注意事项）。

安装

DocOnce是一个Python 3包，可以使用pip或conda安装。请参阅手册以进行全面的安装。

初步步骤

• python -V和pip -V命令应指向Python 3.x。如果不是这种情况，您可能需要使用以下说明中的pip3和python3命令。

使用pip安装

安装DocOnce及其依赖项

pip install DocOnce --user

使用conda安装

使用pip创建conda环境

conda create --name doconce python=3
conda activate doconce
conda install pip

安装DocOnce及其依赖项

pip install DocOnce

在Python虚拟环境中安装

Python虚拟环境是一个用于Python项目的隔离环境，这使得此选项是安装的最安全选择。

创建虚拟环境

python -m venv venv
. venv/bin/activate

安装DocOnce及其依赖项

pip install DocOnce

亮点

• DocOnce是一种适度标记的标记语言（请参阅语法示例），非常类似于Markdown，但具有更多功能，旨在用于文本中包含大量数学和代码的文档（请参阅演示）。
• 对图书项目有广泛的支持。除了经典的基于LaTeX的纸质图书外，还可以免费获得全响应式、外观现代的基于HTML的电子书，适用于平板电脑和手机。例如，图书的部分可以出现在博客文章中以供讨论，也可以作为IPython笔记本进行实验和注释。
• 对于包含数学和代码的文档，可以生成清洁的纯LaTeX（PDF）、HTML（带有MathJax和Pygments - 嵌入您自己的模板）、Sphinx（用于吸引人的网页设计）、Markdown、IPython笔记本、Google或Wordpress博客文章的HTML以及MediaWiki。LaTeX输出有许多用于计算机代码排版的精美布局。
• DocOnce还可以输出其他格式（尽管没有支持精美排版的数学和代码）：纯无标签文本、Google wiki、Creole wiki和reStructuredText。从Markdown或reStructuredText可以转换到XML、DocBook、epub、OpenOffice/LibreOffice、MS Word和其他格式。
• 文档源首先由Preprocess和Mako预处理，这为您在文档文本中提供了完整的编程能力。例如，使用Mako可以轻松编写包含所有计算机代码示例的书籍，这些示例使用两种不同的语言（例如Matlab和Python），并且可以在编译文档时确定语言。还可以通过Mako实现DocOnce的新用户特定功能。
• DocOnce扩展了Sphinx、Markdown和MediaWiki输出，使得带有标签的LaTeX对齐环境适用于方程组。DocOnce还调整了Sphinx和HTML代码，使得可以引用当前网页之外的方程。
• DocOnce通过简化报告或书籍中的运行文本，使编写包含数学和代码的幻灯片变得非常容易。支持的幻灯片元素包括LaTeX Beamer幻灯片、HTML5幻灯片（reveal.js、deck.js、dzslides）和Remark（Markdown）幻灯片。幻灯片元素可以排列在一个单元格网格中，以便轻松控制布局。

DocOnce与Markdown、Pandoc-extended Markdown以及特别地MultiMarkdown相似。DocOnce的主要优势是更丰富的对编写大型文档（书籍）的支持，其中包括大量的数学和代码，以及HTML和LaTeX格式的定制输出。DocOnce还特别支持练习、测验和注意事项，这三个特性在开发教育材料时非常受欢迎。书籍可以由许多较小的文档组成，这些文档可能独立于书籍存在，从而降低了编写书籍的门槛（参见示例）。

新闻

以下是DocOnce最近的一些新特性和改进

• 2020年10月：DocOnce现在可以生成Jupyter Book的内容文件。
• 2020年7月：挪威奥斯陆大学科学教育计算中心的Alessandro Marin担任开发者兼主要维护者。
• 2016年10月10日，DocOnce的创造者Hans Petter Langtangen去世。在挪威奥斯陆大学科学教育计算中心的支持下，Kristian Gregorius Hustad将担任主要维护者。

以下是近期使用DocOnce编写的书籍

安装

DocOnce是一个纯Python包，可以使用pip安装。

Terminal> pip install --upgrade git+https://github.com/doconce/preprocess
Terminal> pip install --upgrade .

注意。如果您在2017年2月之前首次安装了DocOnce，则在升级之前必须删除旧版本。请参阅问题#110中的说明。

然而，DocOnce有许多依赖项，具体取决于您想要处理哪种格式以及文本中使用的构造的复杂性。

使用Anaconda，通过以下方式可以轻松安装DocOnce及其所有依赖项：

Terminal> conda config --add channels conda-forge
Terminal> conda install doconce

警告。截至2017年3月，一些依赖项尚未添加到conda-forge通道，但大多数格式应该可以正常工作。

在Debian/Ubuntu上，获取所需软件包相当简单。您可以运行一个Python脚本或等效的Bash脚本。此类脚本安装了一个非常全面的软件包。您可以阅读安装指南以获取关于为各种目的所需软件的更详细描述。例如，对于HTML输出，通常只需安装纯DocOnce源（如果使用，可能还需要预处理程序）。

演示

一份简短的科学报告展示了DocOnce可以生成的许多格式以及数学和计算机代码的外观。（注意：在页面底部有一个链接到另一个演示版本，其中包含生成不同版本的完整DocOnce命令。）

另一个演示展示了DocOnce如何用于以不同格式创建幻灯片（HTML5 reveal.js、deck.js等，以及LaTeX Beamer）。

DocOnce支持基于Bootstrap样式的响应式HTML文档，其设计和功能基于Bootstrap样式。一个Bootstrap演示展示了颜色和布局的多种可能性。

DocOnce 还支持 测验格式 的练习。纯测验文件可以 自动上传 到通过智能手机（借助 quiztools 将 DocOnce 转换为 Kahoot!）运行的 Kahoot! 在线测验游戏。

已经编写了多本完全使用 DocOnce 编写的书籍（多达1000多页）。主要格式是特定出版商的 LaTeX 风格，但可以轻松生成 HTML 或 Sphinx 格式，例如 这个 Bootstrap 风格章节，或者许多人偏好的 solarized 颜色风格。可以从书籍中的原始文本快速生成幻灯片。以下是一些以 reveal.js（HTML5） 风格、更传统的 LaTeX Beamer 风格，甚至是现代 IPython notebook 工具的示例，该工具允许进行交互式实验和注释。

许可证

DocOnce 使用 BSD 许可证，请参阅包含的 LICENSE 文件。

作者

DocOnce 由 Hans Petter Langtangen 于 2006-2016 年在 hpl@simula.no 编写。Alessandro Marin（电子邮件地址）于 2020 年接管了开发者和主要维护者的角色。许多人已经为测试软件和提出改进建议做出了贡献。

如何引用

版权链接

可以使用命令行选项 --cite_doconce 将链接添加到当前页面，以装备版权字段。以下是一个涉及文档 mydoc.do.txt 的示例

TITLE: Some document
AUTHOR: Joe Doe
...

使用 DocOnce 链接编译为 HTML

Terminal> doconce format html mydoc --cite_doconce

第一页的页脚现在将包含 "用 DocOnce 制作"。

参考文献中的传统引用

BibTeX 格式

@misc{DocOnce,
  title = {{DocOnce} markup language},
  author = {H. P. Langtangen},
  url = {https://github.com/doconce/doconce},
  key = {DocOnce},
  note = {\url{https://github.com/doconce/doconce}},
}

发布格式

* misc
** {DocOnce} markup language
   key:       DocOnce
   author:    H. P. Langtangen
   url:       https://github.com/doconce/doconce
   status:    published
   sortkey:   DocOnce
   note:      \url{https://github.com/doconce/doconce}