如何最好地编写针对 HTML 和 PDF 的文档？ [关闭]

Posted 2023-02-24

【中文标题】如何最好地编写针对 HTML 和 PDF 的文档？ [关闭]

【英文标题】：How best to write documentation targeting both HTML and PDF? [closed]

【发布时间】：2010-09-29 09:52:45

【问题描述】：

我过去见过的 Latex-to-html 转换器非常糟糕。编辑原始 html 并不好玩，而且似乎不能很好地转换为打印页面。其他人如何解决这个问题？示例（pdf 和 html）的链接会很棒。

补充：刚刚又问了一个类似的问题：

What formatting language should I use for project documentation

【参考方案1】：

对于记录代码，我还推荐 Sphinx。 ReStructured Text 很好，因为它可读并且在某种程度上以纯文本形式标记，并且可以很好地转换为 html 和 pdf。对于某些事情，我仍然喜欢 LaTeX。我和我的妻子使用 LaTeX 写圣诞信，然后通过普通邮件寄出。 pdf 版本非常漂亮，有两列，页眉和页脚。 html版本更简单。我用塑料转换。这里的例子： http://fedibblety.com/annualReports

对于 10 年后您可能想阅读的任何类型的文档，我认为任何二进制格式都不是一个好的选择（Word）。这是 LaTeX 的优点之一。

【参考方案2】：

是的，LaTeX-to-HTML 转换器过去很糟糕（您可能已经尝试过 LaTeX2HTML），但最近它们变得更好了。 Tex4ht 是高度可配置的，并且可以生成漂亮的 XHTML+CSS。另见other converters。

你也可以用Docbook，如果你能忍心写进去。有从 DocBook 到 HTML 和 LaTeX（或直接到 PDF）的转换器；后者的一个例子是dblatex。

看到这个帖子：LaTeX vs Docbook。

【讨论】：

tex4ht 也不是picknick，Hevea 也不是。不知何故，他们都糟透了。调试 latex2html (0.96) 是我整个编程生涯中最糟糕的经历。超过 1MB 的 perl 脚本 tex4ht 有时会完全拧紧链接，并且有一些不友好的初学者陷阱（例如连字）

他们都很糟糕，但有些人比其他人少。 :-)（你试过 plasTeX，顺便说一句？plastex.sourceforge.net）

不，我会看看，但看到它是用 Python 编写的，我并不高兴

【参考方案3】：

在经历了多年的痛苦和几次错误的开始之后，我将重新审视这一点，我将尝试Sphinx。它可以从ReStructured Text生成HTML或LaTeX。

我希望它会是一个比完整的 DocBook 更“轻便”的选项，但具有许多优点。

【讨论】：

这正是我的经验。我们的手册是用 docbook 写的，但是编辑起来很麻烦，所以我们从来没有写过手册（而且它还是很丑陋）。 reST 和 Sphinx 更容易使用（而且更漂亮）。

【参考方案4】：

您可以退后一步，使用 DocBook 之类的东西，并通过 LaTeX 和 HTML 直接从 DocBook 文件呈现为 PDF。或者，Adobe Technical Communication Suite (Framemaker) 可让您将文档单一来源转换为 PDF 和 HTML。请参阅 this posting 了解各种技术文档系统的概要。

【讨论】：

+1 - 您也可以直接从 docbook 转到 pdf 和 html（以及一些其他格式，如帮助文件），而无需在使用 docbook-xsl 之间使用 LaTeX

我敢打赌，当您绕过 LaTeX 时，PDF 的排版效果并不好 :) 除非有我没有听说过的重大变化......

【参考方案5】：

PlasTeX 看起来像一个不错的 Latex-to-html 转换器，虽然我自己没有尝试过。

我的朋友 Rob Felty 写了一篇博文来赞美它的优点： http://blog.robfelty.com/2008/03/19/finally-a-better-latex-to-html-converter/

【讨论】：

链接已损坏 :-( - 你有更新的链接吗？

【参考方案6】：

AsciiDoc 看起来很有趣。

【参考方案7】：

这是个人选择，但乳胶在理论上是完美的，但在实践中它很痛苦。我在需要时使用 VS.NET HTML 编辑器 + 原始 HTML 编辑器。

所以我认为使用 WSIWYG HTML 编辑器是最好的选择。您始终可以使用简单的工具将其转换为 PDF，并且您可以在需要高级内容时随时编辑 HTML。需要时也更容易上线。

这就是我管理软件文档的方式，对我来说效果很好。

【参考方案8】：

了解 EPUB 格式。它的电子书格式。 http://en.wikipedia.org/wiki/EPUB

【参考方案9】：

由于提到Asciidoc 的答案在示例中有些不足，因此您正在寻找以下一些内容：

使用 Asciidoc 生成的pdf cheatsheet 与 Asciidoc 标记和 html 结果并排显示。 list 使用 Asciidoc 完成的出版物，包括 O'Reilly 书籍和 git 文档（查看用户规模的两端）。

【参考方案10】：

我不确定乳胶是否真的是最好的工具。您在使用通常的乳胶到 html 转换器时遇到的问题表明了这个问题：html 很简单，不像乳胶那样富有表现力。

如果你坚持把latex转为html，请注意使用可以合理转换的有限子集。

【参考方案11】：

我过去使用过TeXinfo，它做得很好。这是一个示例：http://yootles.com/api。我宁愿坚持使用 LaTeX 而不是使用其他语言。

【参考方案12】：

如果一切都失败了，您可以获取一个 LaTeX 到 XML 转换器并编写一个简单的 XSLT 样式表将其转换为 HTML，或者创建一个 CSS 样式表并将其直接附加到 XML 文件。

【讨论】：

有趣。您想到了哪种乳胶到 xml 转换器？

【参考方案13】：

我们一直在使用 WebWorks ePublisher (www.webworks.com)，它提供多种单一来源格式（我们使用 Word）和输出多种输出格式的能力（我们输出到 Adob​​e PDF 和在线帮助 ( .CHM)。

【参考方案14】：

我们在一个涉及 Eclipse 软件的学术项目中遇到了这个问题，我们使用 plastex 将 Latex 转换为 HTML 和 Eclipse 帮助。让它工作起来相当困难，但最终结果看起来非常好。您可以在此处查看所有三个版本：

http://handbook.event-b.org/

此外，由于这是一个开放项目，代码（构建脚本）是可用的。我们有一个持续构建系统 (Jenkins)，它在签入新 Latex 时重建所有内容。这特别好，因为贡献者不需要在他们的系统上安装工具链。他们只需签入新的 Latex 并在服务器上检查 HTML 是否正确生成。资料来源：

http://sourceforge.net/p/rodin-b-sharp/svn/HEAD/tree/trunk/Handbook/org.rodinp.handbook.feature/

最好的，迈克尔

【参考方案15】：

我没有足够的评论点，但为了支持 plastex 的答案，这里是更新的 plastex 示例链接：

http://robfelty.com/2008/03/19/finally-a-better-latex-to-html-converter

【讨论】：

请注意 link-only answers 是不鼓励的，所以答案应该是寻找解决方案的终点（与另一个中途停留的参考相比，随着时间的推移往往会变得陈旧）。请考虑在此处添加独立的概要，并保留链接作为参考。

@kleopatra 这是一个非常有用的信息，我希望其他人在发表评论之前偶然发现。你解释了为什么这是一个糟糕的答案，而不是侮辱。希望我能给你另一个+1。抱歉，花了 3 年的时间才偶然发现。

【参考方案16】：

乳胶？严重地？我不知道学术界以外的任何人仍在使用它。我会使用 HTML，您可以从网络浏览器将其保存为 PDF。如果你真的必须有一些高级的印刷材料，请改用 Word - 它有一种保存为 HTML 的方法（可能不像人们想要的那样干净），你可以使用免费插件（可单独下载）另存为 PDF .

哦，我不会费心使用 InDesign 之类的东西 - 它们太过分了。此外，不要费心为 Acrobat Professional 付费 - 有无数免费的解决方案可供使用。

【讨论】：

我敢假设这个问题被 LaTeX 粉丝否决了吗？

不是我，但建议 Word 是乳胶的充分替代品对我来说似乎很难辩护......我通常向我不太喜欢技术的朋友推荐带有样式表的 Word，但他们不是一回事。

我也不是，但问题是“（最好是在 LaTeX 中）”和“html 不好玩，似乎不能很好地翻译到打印页面”，这个答案建议与想要的完全相反。另外，是的，我猜“一些高级印刷的东西，用 Word”听起来一定很疯狂 :-)

许多黑客在学术界，事实上，学术界喜欢它是有充分理由的。例如，如果你在文档中使用了很多数学，在我看来，没有其他东西可以真正比较。我认为有相反的意见很好。 （反对票可能只是因为难以置信的语气。）

好吧，如果你看看现在科学期刊和图书出版商使用什么格式，它是 Word，而不是 LaTeX。