Chris Radek wrote: > On Tue, Oct 07, 2008 at 11:16:54AM -0500, Jeff Epler wrote: > > >> Personally, I'd go for option B. Both AsciiDoc and ReST have a lot of >> users. In particular I recently learned that the Python project >> transitioned from LaTeX to ReST for all their documentation. Their >> HTML and PDF documentation look better than ever, while the source code >> is also very readable as plain text. Here's one short example (this is the >> *source code* for the documentation, not a file that it produces as output!): > > > AsciiDoc looks very simple to write. No harder than wiki markup to > learn. With a cheat sheet it would be simple (and I found a cheat > sheet) > > http://powerman.name/doc/asciidoc > > On the AsciiDoc home page you can see sample PDF output: > > http://www.methods.co.nz/asciidoc/#_example_articles > > At first glance this looks like a really good solution to me.
No one has mentioned images yet, so I will. Screenshots (bitmaps) and drawings (vector graphics) are both very useful in documentation. "A picture is worth a thousand words." Both HTML and PDF output can contain images, but getting them there can be a problem. A quick scan of the AsciiDoc user guide shows that it does have an "image" macro. The actual handling of the image is left to "backend" programs (I assume that means the asciidoc to HTML or PDF converters). Documentation about the limitations of the image macro is sketchy. It seems to support PNG and JPG. PNG is fine for screenshots, and JPG would work if we needed any photos, but there is no indication of support for vector artwork. Printing can generally deliver 5x higher resolution than on-screen display, which means 25x as many pixels. If we are stuck with bitmaps, we probably have to generate multiple versions - maybe even three - a thumbnail for inline, then a "click to enlarge" full screen version, and finally a print version. Our existing vector artwork toolchain is even worse than the main chain. Many of the HAL drawings exist as either EasyCad files or as .DXF files, and need to be converted to some form of postscript using a CAD program. Then the postscript is linked to the document, and somehow that results in images in both the HTML and PDF output. Regards, John Kasunich ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Emc-developers mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/emc-developers
