With the introduction of EMC2 V2.5 comes a new method of generating the formal EMC2 documentation. The LyX document processor is no longer used. It has been replaced by a collection of tools known familiarly as AsciiDoc. This collection consists of AsciiDoc, dblatex, PDFTex, the a2x toolchain manager, and assorted scripts, filters, and stylesheets. Documentation about AsciiDoc and associated tools is available on the [AsciiDoc website].
The purpose of this note is to provide EMC2 documentation writers with an overview of the new process. All directory locations discussed below are relative to the top-level directory in an EMC2 distribution. These locations can be changed by modifying variables defined in the supporting (Sub)Makefile.
[the following statement is copied directly from BeyondWiki] 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.
Unlike LyX, AsciiDoc does not have a specialized GUI-based editor available. A documentation writer uses an ordinary text editor to create a AsciiDoc source file which contain plain text with text-based AsciiDoc markup. The markup is described on the [AsciiDoc website]. Markup cheatsheets are available for the impatient at http://powerman.name/doc/asciidoc-index. Be sure to follow the cheatsheet for the version of AsciiDoc being used. AsciiDoc Version 8.5.2 is distributed with Ubuntu 10.04LTS. The easiest way to get familiar with the markup is to choose an interesting existing EMC2 document and examine its source file(s).
The V2.5 documentation effort was jump-started by mechanically translating the V2.4 LyX source files into AsciiDoc source files. In the process, "place keeper" source files for a number of languages were created by simply copying over the English-language files. There is an active effort to generate French-language versions of the files, but most other language versions need contributors.
Current practice is to name a source file written in English simply as <filename>.txt and to name the similar file rewritten in another language as <filename>_<language code>.txt where <language code> is the ISO 636-1 two-character string for the language such as de, es, fr, pl, ru, etc. AsciiDoc knows about UTF-8 character sets but the full EMC2 documentation toolchains may be a bit shakey on the subject, so test...test...test.
The resulting source files are placed into appropriate directories below ./docs/src in the EMC2 distribution.
A documentation writer uses various means such as an interactive graphic editor, programmatic output, and screen capture to create the image files referenced in the AsciiDoc source files. While the state of image processing is still somewhat in flux in the EMC2 documentation toolchains, current documentation includes images sourced in PNG, EPS, GIF, and JPG/JFIF formats. Some CAD-generated drawings originally sourced in DXF have been preprocessed into EPS. We are trying to tighten the requirements on formats used. Formats such as SVG capable of capturing vector graphics are preferred over bit-mapped formats for almost all purposes except screen captures and icons, and lossless formats such as PNG are preferred over lossy alternatives for bitmapped graphics.
Good file-management practice dictates placing the image files into appropriate images directories below the directories in which their referencing source files are placed, but this discipline has not been applied universally.
The AsciiDoc source files are processed into PDF via the toolchain shown below. Note that the processing of image files is not depicted, nor is the extraction, aggregation, and processing of information needed to create tables of contents, indices, and the like.
The resulting PDF files are placed into the ./docs/src directory and hard links to them are created in the ./docs directory.
There is a lively, ongoing debate among the EMC2 developers about how to organize the PDF documentation. The existing organization into individual manuals based on themes like Developer, Integrator, and User is subject to change; one possibility is that the team will decide to produce a single, comprehensive PDF manual. The current organization is imposed in the make process, not in the individual source files.
The same AsciiDoc source files are processed into HTML via the toolchain shown below. Note that the processing of image files is not depicted, nor is the extraction, aggregation, and processing of information needed to create tables of contents, indices, and to resolve hyperlinks (cross references). The HTML is being generated in such a way that it can be browsed locally, without accessing the Internet, as well as accessed in the normal way via a Web server.
The resulting HTML files are placed into the ./docs/html directory and below, as are any local image files that the HTML references.
At the moment, the EMC2 Development Team is experimenting with several different approaches for realizing mathematical expressions (entered into AsciiDoc source files in latexmath notation) in the HTML documentation. One approach embeds the expressions as data in the HTML file to be rendered by the browser, another renders the expressions into image files that are referenced from the HTML file and must be stored along with the HTML files.
The EMC2 distribution contains traditional Unix/Linux man-page files which can be accessed from the command line in the usual way. As a convenience to users, the EMC2 V2.5 documentation process gathers a list of these man-page files, orders it, and from it produces collections of pages in both PDF and HTML format.
The HTML formatted documentation is generated directly from the man-page format using groff. The PDF formatted documentation is generated from the man-page format in a two-step process using groff to generate intermediary PostScript which is then processed using ps2pdf to generate PDF. Again, there is auxiliary processing to create tables of contents and the like.
The file ./docs/src/Submakefile contains a large number of rules that define the recipes for generating the EMC2 documentation in HTML and PDF formats from the source files discussed above.
In broad outline, these recipes tell make how to group the AsciiDoc source files according to language edition, document organization, etc., how to generate auxiliary files and intermediary files if needed, how to invoke the toolchains described above with appropriate attributes and options set to achieve the desired results, and how to place the results into the proper directories. Many of the lines in ./docs/src/Submakefile deal with the definitions of variables needed in the rules that make up the recipes. It's a riveting read (not!).
NOTE: ./docs/src/Submakefile must be modified when AsciiDoc source files are added so that they will be recognized, or when, for example, the organization of the PDF documents is to be changed.
Invoking the ./configure script while in the ./src directory generates the file ./src/Makefile.inc which defines variables needed during the EMC2 make process. Among them are three variables BUILD_DOCS, BUILD_DOCS_PDF, and BUILD_DOCS_HTML which are used during document processing. Depending on the presence or absence of the configure-script option --enable-build-documentation and its optional values =pdf or =html, the variable BUILD_DOCS can take the values yes or no, and the others the values yes or no or nothing.
The ./src/Makefile file explicitly 'includes' the above mentioned file ./src/Makefile.inc and also any files named SubMakefile it can find, in particular ./docs/src/SubMakefile.
When in the ./src directory, invoking make with an appropriate target such as docs, pdfdocs, htmldocs will trigger the appropriate recipes in ./docs/src/Submakefile if and only if the BUILD_... variables have been defined in ./src/Makefile.inc with values that allow it.
When in the ./docs/src directory, invoking make with an appropriate target triggers recipes in the local Makefile which (recursively) invoke make running in the ./src directory with the same target, which reduces to the previous case. The difference is visible to the user in messages emitted by make. The primary make process prefaces its messages with the string 'make:'. The secondary make prefaces its messages with the string 'make:'. The BUILD_... variables have to have been defined properly before invoking make in the ./doc/src directory.
The EMC2 Development Team uses a distributed revision control system named git to manage all of the EMC2 software including its documentation. See [Getting the source with git] for instruction on downloading the latest V2.5 sources. The sources also can be browsed through the [linuxcnc gitweb], although this is an inconvenient keyhole through which to look if one is just coming to grips with the distribution. The EMC2 BuildBot processes relevant git branches, including the V2.5 branch, frequently and posts the resulting EMC2 documentation to http://www.linuxcnc.org/docs/ for browsing and download.
Authorization will be required before edited and new files can be submitted to the git server.
The EMC2 Development Team tracks bugs and feature-requests in, what else, online [bug and feature trackers]. These are the preferred methods of submitting problem statements and suggestions for new capabilities.
Parties interested in contributing to the formal EMC2 V2.5 documentation are urged, before anything else, to join the relevant communication channels such as the emc-developers mail list or the emc-developers IRC. See the Communications Section in the EmcKnowledgeBase.
I've left out lots of details, for example, about the image file processing and about the creation of the tables of content, the indices, and the cross references, which concerns other files in the ./docs/src directory and their processing. There is more esoterica concerning files in the ./debian directory and their processing. There's probably things I don't know I don't know. You'll learn as you go along.