iphone – Apple用来创建文档的工具或技术? [等候接听]

我相信他们使用真正想要创建他们的文档和指南的东西.一切都如此精简和平等,他们总是有一个HTML和一个PDF版本.现在我们做一个很大的框架,并希望提供一个很好的文档,这就是设置Apple的方式.以HTML格式在线,以PDF格式离线.

任何想法如何苹果的人呢?他们使用什么工具?

我不知道苹果在内部使用什么工具.既然我有完全相同的需要,我会分享我学到的东西,以及我最后做的事情.

我的两个开源项目需要“非常高质量”的文档,这与Apple所提供的文档无关.这两个项目是:

> RegexKit
> RegexKitLite

RegexKit是第一个项目.我周围寻找一些东西,任何东西,以帮助文档.只有两个工具,似乎是迎接挑战的是Doxygen,而且,相当于Xcode的工具:HeaderDoc.请记住,这是几年前,所以事情已经有所改变了.

现有工具

Doxygen被很多项目所使用,但我从来不喜欢它所产生的“风格”.更不用说这不像苹果文档那样,而且从我可以说,让它产生我真正想要的只是不实际.

最初,HeaderDoc看起来很有希望.事实上,几个框架头文件包括HeaderDoc标记,例如:

/System/Library/Frameworks/CoreFoundation.framework/Headers/CFArray.h

很快变得很明显,HeaderDoc只是不会削减它.它的速度很慢,很慢,其HTML输出本质上就是“镶嵌在石头上”,没有模板系统.无论什么出来,后端是你被困住的,除了你可以用CSS样式表进行一些微不足道的改变.

RegexKit解决方案

那么该怎么办?由于我已经使用HeaderDoc标记标记了一些标题,所以我决定自己滚动.如果你想看看它,它的所有部分.它绝对显示了它的血统,尽管如此,开始是一个快速的黑客,只是不断增长和成长.不漂亮,也不意味着被理解,更不用说修改,甚至被任何人使用.它本质上是一个完整的文档系统:它解析头文件,提取不只是HeaderDoc标记,而是标记的实际源代码.将所有原始信息转储到sqlite数据库中,然后脚本生成最终的HTML输出.因为一切都被解析,头文件之间的引用(对于类,类型等)没有问题.它还允许自动生成目录.

通过CSS样式表调整单像素距离相当多的努力,它(或至少在当时)是由Apple提供的HTML文档的近似像素完美的仿真.苹果文档风格对iPhone / 10.6有轻微的变化,但仍然非常接近.

不仅与HTML文档几乎完全相同,所以需要花费很多精力去使用特殊的“打印机介质”样式表,以便如果您从浏览器(特别是Safari)打印文档,则与Apple的PDF文档几乎相同.特别是如果你有正确的字体 – Palatino和Letter哥特式.由于Safari显然被调整为屏幕输出,而不是打印机输出,它将在不方便的地方进行分页符,但它绝对可以通过.对HTML进行零修改,所有这些都是通过CSS样式表更改自动完成的.

当我开始使用Mac OS X 10.5尚未发布.有了10.5版的DocSet,它允许将文档紧密地集成到Xcode编辑器中.由于一切都填充到一个sqlite数据库中,所以只需要几天的时间才能生成DocSet工具所需的XML文件.即使构建文档系统还有很多额外的工作,可以将所有文档直接集成到Xcode中,只需几天的时间就可以实现.

RegexKitLite解决方案

RegexKitLite晚些时候,您可以从“Lite”中猜出,这意味着更小.我只想要一个HTML文件的一切.我开始使用为RegexKit完成的模板和CSS样式表工作,“手工”构建了HTML文件,没有任何自动化.即使是DocSet所需的XML文件,也已经从RegexKit中删除了已经删除的文件,然后手工编辑.

如果您找不到解决方案并需要自行滚动,我强烈建议您获取RegexKitLite HTML文档的副本,并将其用作锅炉板.该文档由相同的BSD许可证覆盖,但是您可以自由地排除内容,并将剩余的框架作为模板,而不归属.

由于RegexKitLite是二者的“新”,所以得到最多的爱.我知道它的CSS样式表比RegexKit开始更好,并且有很多的改进.同样,你可以将所有的JavaScript< script>东西,因为它的唯一目的是允许你选择/突出显示文本中的正则表达式,然后做一些自动化的正则表达式 – >当您在Safari中执行复制/ Command-C时,NSString会转义.

理想的解决方案…或者我想要的圣诞节.

我的理想解决方案是一些易于使用的标记.最后,我并不喜欢HeaderDoc的标记风格.绝对需要灵活和用户可扩展,并面向模板. HTML,特别是XML,在我看来是冗长的.我想我喜欢更像MarkdownreStructuredText,但显然调整了手头的任务.特别地,对于引用类似其他类,类型等的东西,模板/后端将自动将其重写为目标输出格式(例如HTML),并根据需要为您自动超链接引用,这将是很好的.

对于高质量的打印输出,您几乎肯定会最终使用TeX,LaTeX或其衍生品之一.我没有必要广泛使用* TeX,但它是专门用于书籍/印刷媒体出版的.用几十行文本构建非常高质量的“图表”也是相当微不足道的.对于HTML,您几乎不得不使用另一个工具链(photoshop?visio?等)创建位图图像.

我也只是咬着子弹,完全移动到一个* TeX工具链,并从.tex源生成HTML.每次我尝试过,我刚刚被淹没了.这是一个非常强大的工具,并且.tex源/标记并不是那么糟糕…但是学习足够的东西来调整我想要的输出的确切样式,好吧,让我们这样说. * TeX是由Donald Knuth创作的计算机程序设计大师,因为当他去写他的书,这需要高质量的排版数学公式时,他对现有的解决方案感到不满.所以他花了几年时间写了自己的.他处于现代计算机排版和排版的边缘,在右边创造出了大块的排版.

翻译自:https://stackoverflow.com/questions/1930755/what-tool-or-technology-does-apple-use-to-create-its-documentation

转载注明原文:iphone – Apple用来创建文档的工具或技术? [等候接听]