To move the discussion forward I think it would be helpful to steer by requirements for a document format, and then decide wether its worthwhile to change.
I am by no means an expert on these formats and tools. However, I would view the following as important (in no particular order or rating): - vcs-friendly format - stable, open format - large user base - up-to-date tools in ubuntu/debian - most automatic conversion of existing document structure and content from current format - URI stability - good online browsing support wrt "Wiki vs other format" I have no dog in the race; I use the wiki for the two things I'm currently working on as I feel it is appropriate at this stage but I recognize it should be moved to the mainstream documentation format as things shake out and stabilize; eg gladevcp is due for that step, toolchange stuff not yet. -m Am 14.01.2011 um 16:34 schrieb Pavel Shramov: > 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 > [email protected] > https://lists.sourceforge.net/lists/listinfo/emc-developers ------------------------------------------------------------------------------ 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 [email protected] https://lists.sourceforge.net/lists/listinfo/emc-developers
