[Home]History of BeyondWikiToo

LinuxCNCKnowledgeBase | RecentChanges | PageIndex | Preferences | LinuxCNC.org

Revision 10 . . (edit) January 20, 2012 9:50 pm by CNCDreamer [picked a couple of nits]
Revision 9 . . January 20, 2012 9:43 pm by CNCDreamer [edited to reflect rebranding]
Revision 8 . . January 19, 2012 8:25 am by CNCDreamer [*added disclaimer banner]
Revision 7 . . (edit) December 2, 2011 5:23 am by CNCDreamer [*center the figures, correct a typo]
Revision 6 . . (edit) December 1, 2011 6:32 am by CNCDreamer [*swap out figures, amend text]
Revision 5 . . (edit) November 30, 2011 2:16 am by CNCDreamer [*fix up some language and move the figures]
Revision 4 . . (edit) November 29, 2011 6:44 pm by CNCDreamer [*trivial fixes]
Revision 3 . . (edit) November 29, 2011 6:32 pm by CNCDreamer [*fixed up sections 8 and 9; made no headway on formatting and placing images]
Revision 2 . . November 29, 2011 9:51 am by CNCDreamer [*uploaded and inserted (ugly) figures]
Revision 1 . . November 29, 2011 8:44 am by CNCDreamer [*create new page about revised formal documentation process for V2.5]
  

Difference (from prior major revision) (minor diff)

Changed: 1,5c1
THIS PAGE IS IN PROCESS OF BEING EDITED TO REFLECT THE AGREEMENT TO REBRAND EMC2 TO LINUXCNC



Formal EMC2 Documents in V2.5



Formal LinuxCNC Documents in V2.5




Changed: 12c8
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].
With the introduction of LinuxCNC V2.5 comes a new method of generating the formal LinuxCNC 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].

Changed: 14c10
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 purpose of this note is to provide LinuxCNC documentation writers with an overview of the new process. All directory locations discussed below are relative to the top-level directory in a LinuxCNC distribution. These locations can be changed by modifying variables defined in the supporting (Sub)Makefile.

Changed: 16c12
[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.
[the following statement is copied directly from BeyondWiki with only a change to LinuxCNC] The LinuxCNC 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.

Changed: 21c17
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 plains 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).
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 plains 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 LinuxCNC document and examine its source file(s).

Changed: 25c21
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.
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 LinuxCNC documentation toolchains may be a bit shakey on the subject, so test...test...test.

Changed: 27c23
The resulting source files are placed into appropriate directories below ./docs/src in the EMC2 distribution.
The resulting source files are placed into appropriate directories below ./docs/src in the LinuxCNC distribution.

Changed: 29c25
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.
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 LinuxCNC 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.

Changed: 41c37
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.
There is a lively, ongoing debate among the LinuxCNC 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.

Changed: 51c47
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.
At the moment, the LinuxCNC 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.

Changed: 55c51
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 LinuxCNC 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 LinuxCNC 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.

Changed: 59c55

1. The Make Recipes for Generating the Formal EMC2 Documentation



2. The Make Recipes for Generating the Formal LinuxCNC Documentation




Changed: 61c57
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.
The file ./docs/src/Submakefile contains a large number of rules that define the recipes for generating the LinuxCNC documentation in HTML and PDF formats from the source files discussed above.

Changed: 69c65
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.
Invoking the ./configure script while in the ./src directory generates the file ./src/Makefile.inc which defines variables needed during the LinuxCNC 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.

Changed: 79c75
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.
Parties interested in contributing to the formal LinuxCNC V2.5 documentation are urged, before anything else, to join the relevant communication channels such as the linuxcnc-developers mail list or the linuxcnc-developers IRC. See the Communications Section in the LinuxCNCKnowledgeBase.

Changed: 81c77
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.
The LinuxCNC Development Team uses a distributed revision control system named git to manage all of the LinuxCNC 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 LinuxCNC BuildBot processes relevant git branches, including the V2.5 branch, frequently and posts the resulting LinuxCNC documentation to http://www.linuxcnc.org/docs/ for browsing and download.

Changed: 85c81
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.
The LinuxCNC 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.

Changed: 92c88
This page was created 20111129 by Kent A Reed
This page was created 20111129 by Kent A Reed and edited 20120120 by same to reflect LinuxCNC

LinuxCNCKnowledgeBase | RecentChanges | PageIndex | Preferences | LinuxCNC.org
Search:
Published under a Creative Commons License