Formal EMC Documents

: 5.1. Ubuntu

1. Introduction

The EMC uses the Lyx document preparation system as its standard document storage format. Lyx files are kept in the docs/src subdirectory of the emc2 module in the git repository. The current set of files has been prepared with lyx-1.3.6. You can find out a lot more about lyx by browsing http://www.lyx.org and http://wiki.lyx.org.

Lyx will run on Microsoft Windows(tm), Macintosh(tm), and most distributions of Linux. It is conveniently packaged for debian users including BDI and Ubuntu.

Master lyx files can be converted to html for web presentation, to pdf for document printing and viewing or to several other formats for further editing or publishing. Lyx works with many other packages to provide bibliography handling and image conversion. Lyx comes with many styles like book, article, slideshow, letter, and scripts. Additional styles are available for plugin.

The EMC documentation is licensed under the GFDL with no cover texts and no invariant texts, and some portions are dual licensed under the GFDL and the GPL (the dual license makes it clear that those portions of the documentation may be used freely within the source code, for instance in source code comments or in user interface text). All new contributions should be dual licensed.

2. Website structure

The documentation from the "master" development version of emc2 is updated from git several times a day. You can view and download it: http://www.linuxcnc.org/docs/devel

The documentation from the "v2_4_branch" is also automatically updated. You can view and download it: http://www.linuxcnc.org/docs/2.4/

The html directory includes not only the LyX-format (pdf) documentation for User, Developer, and Integrator manuals, but also HTML versions of the manpages.

The directory http://www.linuxcnc.org/docs/html/ and pdf's in http://www.linuxcnc.org/docs/ are symlinks to the docs for the latest release version.

Substituting "docview" for "docs" in any of the above URLs shows the documentation integrated in the linuxcnc.org website template.

3. Contributing to the documentation without installing Lyx

If you would like to contribute to the documentation, write in text, HTML, or openoffice format with your favorite editor. Prepare diagrams in a portable format such as svg, and bitmap drawings in a lossless format like png. Send your contribution to one of the volunteers below. (If you are willing to do the work of integrating documentation from other sources, please add your name and contact information below)

Jeff Epler <jepler@unypthonic.net> (I prefer to receive contributions in plain text)
Alex Joni <alex_joni AT users.sourceforge.net> (most formats will do)

When you contribute, please include a statement that your contribution is available under a dual GPL/GFDL license.

4. Translating the documentation into new languages

(This is a slightly modified version of a message that I sent to a user offering to translate the emc2 documentation into Brazilian Portuguese -- when you see 'pt' or 'pt_BR', substitute the language and country code for your own language)

The non-english translations are given a language suffix. For example, if you are translating the documentation for the original file config/ini_config.lyx, you would name your file config/ini_config_pt.lyx or config/ini_config_pt_BR.lyx. When you create alternate versions of images, they should likewise have a language suffix.

You should use only the version of lyx that is available for ubuntu 6.06 dapper drake, which is lyx version 1.3.7.

Much of the english-language documentation would benefit from review and proofreading before it is translated--if there is something you don't understand, it may not be understandable even to people whose first language is english. Please don't hesitate to ask questions, or for advice on which documents are most important to translate first. I recommend using our mailing lists (emc-developers or emc-users) or our IRC chat channels--more details about all of those are on our website

    http://www.linuxcnc.org/content/view/4/8/lang,en/

To begin with, you should send updated files directly to me and I will arrange for the improvements to be in the next released version of emc. Once you've gotten more comfortable with the work, you can be given the permission to directly make changes and improvements directly.

5. Installing Lyx

5.1. Ubuntu

Lyx is available as a package for Ubuntu. You must first enable the 'universe' and 'multiverse' repositories -- see [How to add extra repositories]. Then update your package list with

 sudo apt-get update

then install the packages with

 sudo apt-get install lyx imagemagick xsltproc dvipng

Once you have installed the necessary packages and re-run emc2's configure script with "--enable-build-documentation". Check the output of configure to make sure that the required programs are found. If configure detected everything properly, HTML and PDF documentation will be built as a part of the normal 'make' process. You can build the documentation alone with 'make docs'. If you are on a machine without a realtime system, then use "--enable-simulator".

6. Troubleshooting LyX errors

When LyX encounters trouble, it's often not very expressive about the problem:

 Building ../docs/src[/Master User]?.pdf
 make: *** [../docs/src[/Master User]?.pdf] Error 1

To make LyX more verbose, you can add the "-dbg=all" flag in docs/src/Submakefile?:

 -       @$(LYX) --export pdf2 $<
 +       @$(LYX) -dbg=all --export pdf2 $<

This makes it painfully verbose; you can experiment with other -dbg= flags (just run "lyx -dbg" at the terminal to see a list of possible flags). To review the output, you may want to "make docs 2>&1 | less" so that you can review it in a pager, or "make docs > make.log 2>&1; gedit make.log" to view it in your favorite text editor.

BeyondWiki