First I want to thank Pavel for all his research and effort on this
subject as well as others.
The installed PDF documents:
They do not contain all the man page information automagically.
The G Code quick reference is only useful if your machine has an
internet connection.
IMHO menu items should only bring up and *reference* local documents
and not assume an internet connection is available.
Links can not be made between PDF's AFAIK.
One Master PDF document with all the other documents contained
would fix this
and reduce the menu count and possible confusion as to which
document to try and read.
Yes, I know you can type in man abs9 and view the info but how would a
new user know what components are in the man pages?
The HTML documents:
They don't follow the same flow as the PDF's (perhaps my fault)
They contain information not found in the PDF's
You have to have an Internet Connection to view them.
My thoughts on lyx are if you have to install a VirtualBox OSE with 8.04
to be able to edit documents that is no excuse to not edit documents.
That is how I edit them now and don't feel that is a valid reason to change.
If a change brings better documentation then that is a good reason to
change.
my 0.002 cents
John Thornton
Michael Haberler wrote:
> 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
>> Emc-developers@lists.sourceforge.net
>> 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
> Emc-developers@lists.sourceforge.net
> 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
Emc-developers@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/emc-developers
