In the light of upcoming 2.5 version and new branch I want to bring up again question about documentation format.
It was already discussed two years ago [1] but no descision was made. Readint that mail thread it seem that LyX is not in favor and asciidoc was seriously considered as replacement. So here is result of small investigation on the topic. There is at least one Big project using Asciidoc for documention - Git [2]. As Jeff already mentioned in [1] Python is using it's own tools and own RST format. Many other projects (linux kernel among them) are using other forms of lightweight markups. Current state of toolchains for such markups allow you to build PDFs, HTMLs and sometimes lot of other formats (that's depend on markup). Among them there are Asciidoc, Markdown and Python RST. As I understand Markdown lacks support for proper PDF creation and primary targets HTML. I'm not very confident with RST but it's backed by docutils [3] and allows at least two ways of PDF creation via latex or directly [4]. But for me it's syntax is a bit heavy. Last is Asciidoc which may be considered as a lightweight frontend for DocBook -- most of format conversion is supported via long chain of asciidoc -> docbook -> whatever you want. But a picture paints a thousand words, right? I've played a bit around current docs and here are examples of asciidoc format for gladevcp page: http://psha.org.ru/tmp/gladevcp.html http://psha.org.ru/tmp/gladevcp.txt http://psha.org.ru/tmp/gladevcp.pdf That page was cleaned up manualy after conversion. Next one is result of auto conversion: http://psha.org.ru/tmp/lathe-user.html http://psha.org.ru/tmp/lathe-user.txt Notice lost images - LyX export to latex strips filename extensions... Surely conversion only for conversion does not make sense so there must be some reasons to do it. For me it's outdated LyX - it's easier to setup development environment then one for documentation! Surely this is question mostly to JT, Jeff and other documentation contributors. Pavel -- [1] http://thread.gmane.org/gmane.linux.distributions.emc.devel/1315 [2] http://git.kernel.org/?p=git/git.git;a=tree;f=Documentation [3] http://docutils.sourceforge.net/index.html [4] http://code.google.com/p/rst2pdf/ ------------------------------------------------------------------------------ Protect Your Site and Customers from Malware Attacks Learn about various malware tactics and how to avoid them. Understand malware threats, the impact they can have on your business, and how you can protect your company and customers by using code signing. http://p.sf.net/sfu/oracle-sfdevnl _______________________________________________ Emc-developers mailing list Emc-developers@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/emc-developers
