当前位置:  开发笔记 > 编程语言 > 正文

用于生成用户手册的应用程序(非标记语言)

如何解决《用于生成用户手册的应用程序(非标记语言)》经验,为你挑选了2个好方法。

任何人都可以推荐一个程序来创建用户手册吗?不是标记语言(如LaTeX或DocBook),而是更像Scribus这样的交互式语言.因为我不是唯一一个会更新手册的人,软件应该是新手很容易接受的东西,但仍然有一些高级功能(比如从外部源/表中链接文本,处理主页/主题等) .

此致,奥斯卡



1> ConcernedOfT..:

技术出版软件 - 关于FrameMaker及其替代品的观点

我已经使用LaTeX和Framemaker完成了spec文档,并设计了一个Framemaker工作流程来支持由5名分析师组成的团队,为保险承保系统生成规范文档.该文件预计将达到2,000页左右.许多年前(大约在1992年至1993年),我还曾作为打字机做过短暂的工作.

Framemaker专为技术文档而设计,确实非常出色. 它还具有旨在支持具有多个作者的大型文档的功能 - 人们使用此系统来处理超过100,000页的文档.熟悉文字处理软件的用户也比LaTeX更容易访问.

Framemaker的主要特点:

由多个文件组成的文档:您可以将具有多个子部分的"Book"汇集在不同的文件中.该文档也可以保存在源代码管理中.

导入/导出的文本MIF格式:导入器有点挑剔(我发现生成工作的LaTeX更容易)但您可以生成数据字典等项目并将它们导入到文档中.该文件具有文本锚点(见下文),因此您可以创建跨导入的稳定的交叉引用链接.我发现这是规范的一个关键特性,因为它允许交叉引用直接链接到生成的项目.

强大的标记,索引和交叉引用系统:一切都基于Framemaker中的标签,并且很容易快速应用标签.这意味着交叉引用,索引,条件文本和应用样式都很容易并且 正常工作.您可以基于标记生成索引和TOC,因此可以轻松地使用多个专用索引(例如屏幕或数据字典中的数据字段列表).我上面描述的文件有4个单独的索引.

稳定: Framemaker是专为专业人士设计的,因此它不会以该词的方式猜测你.它在大型文档上也更加稳定.任何试图在Word上编写超过50-100页文档的人都应该非常了解这意味着什么.

Scriptable: FM有一个C API,并且有各种脚本插件(FrameScript和FMPython 可能是最广泛使用的),可用于自动化FM中的作业. Framemaker 10增加了对基于Javascript的脚本工具的支持,该工具名为Extendscript,可能是从InDesign中的脚本工具移植过来的.

单一来源:从单个FM文档中,您可以非常轻松地生成PDF,Windows帮助(CHM),HTML和打印文档.交叉引用也解析为超链接.

全局样式控件:您可以轻松地为文档设置样式并将其应用于整个文档.它还有助于运行页眉和页脚,具有很大的灵活性,可以跟踪部分,版本,章节等.

Framemaker的替代品

LaTeX/Lout:您已经表明您不需要标记语言,但TeX和 Lout系统用于大型结构化文档并且做得很好.

Ventura Publisher:如果您想要这种用户界面而不需要为特权支付身体部分,可能是Framemaker的唯一真正替代品.它强烈支持结构化文档和基于XML的文档交换格式.它现在由Corel拥有,Corel似乎仍在积极推广它.

市场上还有其他一些技术出版工具:Quicksilver (曾经被称为Interleaf)和ArborText.这两个是强大的工具--Interleaf曾经一度成为该领域的市场领导者 - 但相当昂贵.

Adobe Indesign:尽管Adobe声称您可以使用InDesign执行大型文档,但Framemaker afficionados可能会认为交叉引用和其他大型文档功能缺乏.然而,有一个名为 InCopy的文本输入系统显然确实具有这种功能和相当大的第三方插件,其中一些支持标记和其他此类设施.InDesign还具有脚本API和用于执行脚本的JavaScript解释器.

我没有使用Indesign,所以我无法评论它在实践中的运作情况.

DocBook: 这实际上只是结构化文档的标准格式,但它有一个围绕它的大型工具生态系统,用于编写和呈现文档.如果您不想使用LaTeX,您可能不会出于类似的原因使用DocBook.正如 Vinko Vrsalovic 指出的那样(+1),这个链接转到了某人在实践中使用DocBook描述的StackOverflow帖子.我从来没有真正使用DocBook,而且我已经对这篇文章进行了如此多的编辑,现在它已经处于Wiki模式,所以熟悉DocBook的人可能想详细说明这一点.

文字处理软件: Word 作为技术发布工具存在严重缺陷,不推荐使用. OpenOffice具有比word更好的结构化文档功能,如果使用.doc作为文档交换格式的政治或要求排除了更好的选择,则可能是更好的选择. Wordperfect对于大型文档来说也比单词更好,并且仍然存在于几个垂直市场,例如法律办公室.

Madcap Software的 Blaze和Flare:这些是街区的新生儿,与Framemaker大致相同.该公司由前eHelp(RoboHelp的创建者)员工创建,并且正在积极开发,每年发布多个版本.他们的产品在过去两年中大大扩展,不利于个别产品的质量.似乎重点在于推出新产品,因此每个产品都有很多"适合和完成"的问题.作者选择以多种方式重新发明轮子,导致混乱和经常破坏的实施.经常保存,您将遇到未处理的异常.源控制集成是不稳定的.例如,移动或删除一组文件将导致每个文件删除一次源控件提交.有源控制电子邮件通知时的Big PITA.你好500封电子邮件.Flare可以导入W​​ord和Framemaker文件,但导入远非无缝.期望保留所有内容,但计划从头开始完全重新设计样式.Flare分享Word的许多倾向,在幕后做太多事情并假设用户会选择什么.HTML看起来像Word导出HTML时输出的内容 - 大量自定义标记和属性,深层嵌套的内联样式等.文本编辑器令人抓狂,例如,它的光标模型与您曾经使用的任何其他软件不同.

Framemaker与LaTeX

这两个是我用来制作大型,可呈现的系统文档的主要系统,我两者都有很好的结果.

易于学习: TeX可以为您提供绝对控制,但实际上在复杂的LaTeX文档上实现这一点而不破坏其他项目并非易事,尤其是涉及大量宏包的情况下.基本的LaTeX并不难学,但如果你不是一个非常深的TeX黑客,那么制作仍然有用的.sty文件的修改版本需要一些修修补补.它可以做,但准备花很多时间摆弄.

Framemaker可以让您对文档的外观有很好的控制,并且不难学习.使用Framemaker可以更轻松地获得房屋风格并调整布局(您可能需要这样做).

易于文本输入:您可以使用Lyx等工具为LaTeX提供类似文字处理器的前端,如果您想要编写大量文本,这些工作都很有效.Framemaker的类似DTP的用户界面以熟悉字体管理软件的人熟悉的方式工作.从这个角度来看,几乎没有实际差异.

Templating Document Structure: Framemaker allows a document structure to be defined in terms of tags or an XML schema (if using Structured Framemaker). LaTeX has a set of canned structural elements that are flexible enough to be useful. Adding additional structural elements (e.g. a data dictionary item) can be done as a macro, but making them auto-number is a bit more challenging and you will need to poke around behind the scenes. Both can do it, but it's considerably more technical to do it in LaTeX in anything but trivial cases.

Also, LaTeX does not have the facility to template the document structure in the way that Structured Framemaker does. However, you can achieve this type of effect with DocBook and then generate to LaTeX if desired.

Ease of Integration: I found making a generator for non-trivially complex MIF files to be quite fiddly. The MIF parser is quite pernickety in FM and doesn't really give good diagnostics. LaTeX produces far better error messages and is quite a bit less fussy.

Technical Publishing Software vs. Layout Software

Page layout software started with Pagemaker and the other main players in this space were its competitor Quark Xpess and now InDesign, with which Adobe is essentially trying to deprecate and replace it and Framemaker. Scribus, which you mentioned before, lives in the same space as these products.

If you are producing a manual with less than (say) 50-100 pages, one of the packages would probably do an adequate job. They are really designed for advertising and layout-heavy publication tasks such as magazines, so their support for large-document features of the sort found in Framemaker is fairly limited. The key issue with these products is scalability - they do not work well on large documents.

Just for reference I have actually typeset a 200-page book (someone's autobiography) using Pagemaker. While the fine-grained kerning and leading control helps a bit for copyfitting, it is still a highly manual process to lay out a book sized document. In this case the book was just straight text with no significant cross-referencing or structure other than chapters. Doing a complex technical spec document or manual this size with Pagemaker would have been very fiddly and probably next to impossible to get right without any mistakes.

Technical Publishing vs. Word Processing Software

This is more of a description of key shortcomings of MS-Word for large spec documents. However, it will illustrate some of the main features required for documentation-in-the-large:

Indexing and Cross-Referencing: This is a real chore in Word, and quite unstable. Framemaker's tagging features and LaTeX's labels mean that you can assign a tag or known label (in a predictable format if necessary). The textual format for the tag anchors is exposed in the user interface, and is used for the linkage. In Word, the anchors are much more opaque and not easily controllable in this way. Combined with the clumsy user interface and instability of the product, this makes maintaining these fiddly, and often unstable - you often have to manually fix them up.

Templated Layouts: Style support in word are quite basic and numbering tends to be somewhat unstable. FrameMaker is all about driving from the tags and applying styles based on the tags. Global style changes just work in Framemaker in a way that they do not in Word.

Large multi-file Documents: I've never been able to make this work well in Word, but it is a key feature in Framemaker and LaTeX. Again, Word's instability means that you tend to spend a lot of time tidying up after it. As the document grows larger, the proportion of time spent on this work grows quadratically - propensity for breakage proportional to n (size of document)*time to fix proportional to size n (time to fix)

Why is Word so Unstable: Word does a lot behind the scenes to support novice users and intervene in layouts. It is also not really frame-based (text flow conceptually separate from document layout), but the developers try to implement various frame-like behaviours in the UI. When the A.I. second-guesses you on a complex document it often does the wrong thing. Framemaker 'treats the user as an adult' and does none of this so things stay where you put them.

Other word processors such as Open Office and WordPerfect do not misbehave in quite the same way as Word, which is one of the reasons that just about any word processor other than Word will do a better job of technical documents.

Pre-Flighting: In documentation-speak, this is the process of checking that your assemblage of files for the document (image files etc.) is correct before committing to print. The professional systems will complain about things that are wrong, giving you a chance to correct it. Word will just put on a happy face and try to fix things behind the scenes.

A good example of this is a word file with linked graphics. If you copy the file and graphics to another directory and update one of the graphics in situ, word may well still read the file from the old path (I've seen it do this) and not the new one you've just updated. However, this behaviour is not consistent and typifies the rampant abuse of unstable heuristics in that product.

Pre-Press Support: A publishing system extends into the pre-press phase of the workflow. This means it covers preparation for print. Word processing software tends not to have this functionality or have it in a very limited form.

Without getting too far into this, a key difference is that publishing software tends to treat you like a consenting adult and not get in the way when you want to scale or automate things. One can use word processing software for large scale documentation but it has many design decisions adapted to casual users writing short documents with little regard for quality. These adaptations come at the expense of fitness-for-task on large scale document preparation work. The main issues I find with Word for spec documents are the poor indexing and cross-referencing and general instability issues where I am always having to go back and fix things. However, political considerations in most environments (I'm a contractor) mean one is often stuck with it.

Some general comments on the state of technical documentation software

Framemaker would be the obvious choice if Adobe didn't keep giving off signals that they are trying to deprecate it and move its user base to InDesign. However, FM is widely used in aerospace, software and engineering circles and Adobe's management would face a lynch mob if they actually EOL'd the product without a credible migration path. From what one reads on the web, Adobe's acquisition of FM was driven by John Warnock, but he was ousted and FM became a victim of office politics. The net result is that it's been moved to maintenance mode and is quite stagnant.

Ventura Publisher has also been relegated to a niche market to some extent, but at least Corel do not have two competing product lines in the way that Adobe do. It is probably a passable substitute for FM and may be more politically acceptable to PHB types as it is marketed as a 'business publishing' system.

Quicksilver and Arbortext both seem to be viable products, but are very expensive. I've not used either, so I can't really make any real judgement on their merits.

The markup language systems are free and very powerful in many ways. Lout might be a bit easier to work with as it doesn't have quite the level of legacy baggage that LaTeX does. DocBook is also quite widely used and does have quite a bit of tool support. These technologies put a significant squeeze on the 'geek' end of Framemaker's market share and do so on their merits - they have probably taken quite a chunk out of Adobe's profit margins over the years. I would not dismiss these technologies out of hand, but they will be harder to learn in practice.

You might try evaluating InDesign and a selected set of plugins (concentrate on those for tagging and cross-ref/index management). Finally, some of the word processing software (Wordperfect and OpenOffice) give you a reasonable toolkit for structured documentation and work considerably better for this than MS-Word.

PostScript

Yes, that is a pun. I haven't touched on Pre-Press functionality of any of these products. Printing and Pre-Press are technical fields in their own right and the scope for expensive mistakes means you should probably leave this up to specialists. Framemaker, InDesign, Ventura, QuickSilver, Arbortext and (presumably) the MadCap products all come with facilities to do pre-press preparation. By and large, word processing software does not.

Doing pre-press with LaTeX tends to involve post-processing the PS output with software like psutils or rendering to PDF and taking the pre-press workflow from there. Generally, most pre-press houses can work from PDF, so a good PDF writing tool like Distiller is the best interface for work prepared from tools that are not designed for prepress work. Note that the quality of the output from Distiller tends to be better than the Ghostscript based ones like PDFCreator.

Note that the RGB colour space of a monitor does not have a direct map to a CYMK colour space used by a printing press. Actually getting colours - especially colour photos - to come out correctly on a press is somewhat fraught if you do not have the right kit. For print production, see a specialist unless you have reason to believe you know what you're doing. For a casual user I would still recommend this 15 years after I was involved in the industry, as mistakes are very expensive to fix once they're committed to print.

If you really do want to do colour print work in-house, you will probably need to calibrate your monitor. For best results, you should get a high-fidelity monitor like this one from HP. In order to calibrate the monitor you may also need a sensor like one of the ones described in this review if the monitor does not come with one. Most professional graphics cards like these from Nvidia, AMD or Matrox have facilities to support gamma correction; many consumer ones do as well. You will also need to get calibration data for the press you are going to be using to print, although the pre-press house will probably be able to do this.

As stated before, print media is quite technical in its own right, easy to get wrong and expensive to fix once it's gone to print. If you're not 100% certain you've got your calibration right, get a colour proof like a Chromalin. This is done from the actual film separations (and is thus quite expensive), so it gives an accurate rendition of the actual colour of the final printed article. Doing this for a few sample pages will give you accurate feedback about whether your calibration is set up right.

Acknowledgements: Thanks to Aidan Ryan for expanding the section on Madcap products.


已经写完了!;)
已经这样做了(至少有几个大型规格,白皮书和各种其他文件;-)
我见过的最好的答案之一.

2> Craig Lebakk..:

我建议使用 EC Software的" 帮助和手册 ".您可以从单个源文档创建印刷手册,PDF,Windows帮助文件(CHM)和基于HTML Web的帮助.

推荐阅读
小色米虫_524
这个屌丝很懒,什么也没留下!
DevBox开发工具箱 | 专业的在线开发工具网站    京公网安备 11010802040832号  |  京ICP备19059560号-6
Copyright © 1998 - 2020 DevBox.CN. All Rights Reserved devBox.cn 开发工具箱 版权所有