DocOnce 1.5.15

DocOnce是一种标记语言，具有类似Markdown的标记，但功能更丰富，针对包含大量文本中数学和代码的文档（如科学报告、软件文档、书籍、博客文章和包含大量数学和代码的幻灯片）。从DocOnce源可以生成LaTeX、Sphinx、HTML、IPython笔记本、Markdown、MediaWiki和其他格式。这意味着您可以从单个源获得最新的出版技术，用于纸张、平板电脑和手机。

文档

• 教程：Sphinx，HTML，PDF
• 手册：Sphinx，HTML，PDF
• 快速参考：Sphinx，HTML，PDF
• 故障排除和FAQ：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

全面安装

要执行全面安装，请在本地的计算机上克隆此存储库，然后在那个目录中运行pip install

git clone --recurse-submodules git@github.com:doconce/doconce.git
cd doconce
pip install -r requirements.txt
python setup.py 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做出贡献

请参考指南开发入门。在那里您可以了解DocOnce项目的结构，以及如何为Python IDE编写运行/调试配置脚本。

演示

一篇简短的科学报告展示了DocOnce可以生成多种格式，以及数学和计算机代码的样式。（注意：页面底部有一个链接，可以访问包含完整DocOnce命令的演示版本。）

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

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

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

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

许可证

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}