ePiX Tutorial and Reference Manual. Hwang, A. D.
ePiX Tutorial and Reference Manual [link]Paper  abstract   bibtex   
[Excerpt: Introduction] ePiX, a collection of batch utilities, creates mathematically accurate figures, plots, and animations containing LATEX typography. The input syntax is easy to learn, and the user interface resembles that of LATEX itself: You prepare a scene description in a text editor, then ” compile” the input file into a picture. LATEX- and web-compatible output types include a LATEX picture-like environment written with PSTricks, tikz, or eepic macros; vector images (eps, ps, and pdf); and bitmapped images and movies (png, mng, and gif). [\n] ePiX's strengths include: [::] Quality of output: ePiX creates accurate, publication-quality figures whose appearance matches that of LATEX. Typography may be put in a figure as easily as in an ordinary LATEX document. [::] Ease of use: Figure objects and their attributes are specified by simple, descriptive commands. [::] Flexibility: Objects are described by attributes and Cartesian location; as in LATEX, printed appearance is determined when the figure is compiled. A well-designed figure can be altered dramatically, yet precisely, with command-line switches or minor changes to the input file. [::] Power and extendibility: ePiX inherits the power of C++ as a programming language; variables, data structures, loops, and recursion can be used to draw complicated plots and figures with just a few lines of input. External code can be incorporated in a figure with a command line option or by using a Makefile. [::] Economy of storage and transmission: For a document containing many figures, a compressed tar file of the LATEX sources and ePiX files is typically a few percent the size of the compressed PostScript file. [::] License: ePiX is free software. You are granted the right to use the program for whatever purpose, and to inspect, modify, and re-distribute the source code, so long as you do not restrict the rights of others to do the same. In short, the license is similar to the terms under which theorems are published. [\n] ePiX facilitates logical, as opposed to visual, structuring of mathematical figures, analogous to the relationship between LATEX and a word processor. A few stylistic defaults streamline the creation of simple figures, but there are few internal restrictions on the contents or appearance of a figure; aesthetic and practical decisions are left to you. [\n] If you are a: [::] Potential user, you may wish to skip immediately to ” Software Dependencies” before investing additional time. [::] New user, proceed from here until you have enough understanding to run the software, then experiment with the samples files while reading Chapter 2, or return to the manual as needed. [::] More advanced user, browse at will, probably starting with Chapter 3. [\n] This manual is relatively conversational, and occasionally redundant, especially between portions meant for readers at different levels of familiarity. Throughout, you are assumed to be familiar with LATEX and basic linear algebra: the description of points, vectors, lines, and planes in three-dimensional space. Other material, such as C++ syntax, is introduced as needed. [\n] [...] [Appendix A - Software Freedom] Academics in general, and mathematicians in particular, depend on free exchange of information. We prove theorems or establish experimental results, write up formal accounts, place preprints on public file servers, and submit papers to peer-reviewed journals. If accepted, the results – data, techniques, methods of reasoning, citations, and conclusions – are published in print and become part of the public record, governed by copyright law. Libraries purchase journal subscriptions, but researchers and scholars may use ideas from the literature merely by giving appropriate citations in their own work. ” Theft” arises from false claims of authorship. [\n] Carried over to software, the academic process would guarantee rights similar to those provided by the GNU General Public License (GPL): [::] (GPL 0) To run a program for any purpose. [::] (GPL 1) To study how the program works, and adapt it to your needs. [::] (GPL 2) To redistribute copies of the program. [::] (GPL 3) To improve the program, and release improvements to the public, so that the whole community benefits. [\n] In reality, attitudes toward software differ markedly. Most academics work on a proprietary platform, use proprietary software for research and teaching, and share information with colleagues and students in proprietary, even obfuscated, data formats. Contrary to the academic ethic, proprietary software licenses restrict access to information: preventing users from learning how a program works internally ( ” reverse engineering”), limiting the number of users who may run a piece of software, and forbidding users from running (or sometimes even installing) a purchased copy on multiple machines. [\n] Restrictions on use aside, if one cannot examine a program's source code, one cannot fully trust the output, any more than one can trust (for purposes of scientific publication) results of a commercial testing lab. [\n] Consider a hypothetical future world in which scholarly results are disseminated like software. Instead of subscriptions, journals sell licenses granting readership to a specified number of individuals. Photocopying an article for a class or research seminar constitutes ” piracy”, though if the institution has purchased a sufficiently large site license the teacher or speaker may bring the physical volume to class and project the pages onto a screen. [\n] Of course, reading an article is scarcely enlightening. Mathematics papers contain only the statements of theorems. Merely opening the journal binds the reader to a lengthy legal agreement, stating that theorems be used only for specific purposes and threatening serious legal consequences for attempting to discover the author's proofs. [\n] The actions of a single student, employee, or faculty member can expose an institution to a costly ” journal audit” from the Mathematical Society of America (MSA), with the institution responsible for legal costs if the audit reveals license violations anywhere in the organization. [\n] Mathematicians who long for the Old Days when papers contained proofs and were shared freely are dismissed as idealistic cranks or labeled antibusiness communists. Common knowledge asserts the obvious superiority of proprietary journals, and the necessity of licenses for keeping mathematicians gainfully employed. [\n] Back in our world, some vendors have attempted to placate opponents of closed source with ” shared source” licenses, under which one may sign a nondisclosure agreement and subsequently examine source code. In the future world analogy, a shared source agreement would allow journal licensees to sign an NDA, then see the proofs of theorems. Readers could thereby correct errors in proofs (benefitting the publisher by improving the reliability of the journal), but would be legally forbidden from using the ideas elsewhere (denying benefit to other mathematicians). [\n] Legally and conceptually codifying software as a commodity ignores a fundamental reality: Like an idea or recipe, software can be copied without loss of the original. The perception of ” theft” by copying arises from an artificial belief that software has an owner who must be monetarily compensated each time a person acquires a copy. The nature of software does not enforce the ” sale” model in the way services and physical commodities do. It therefore seems philosophically inappropriate to treat software as a commodity, and perilous to conform the legal system to the enforcement of such a model. [\n] At its best, software enhances our productivity and creativity. Sharing software, like sharing ideas, benefits a larger number of people without detriment to existing users. I hope this modest program is, in conjunction with the much larger efforts of others (especially Donald Knuth, Richard Stallman, and the many people who have contributed to the authorship of LATEX and its packages), useful to you in your mathematical work. [\n] [...]
@book{hwangEPiXTutorialReference2008,
  title = {{{ePiX}} Tutorial and Reference Manual},
  author = {Hwang, Andrew D.},
  date = {2008},
  url = {http://mfkp.org/INRMM/article/14159312},
  abstract = {[Excerpt: Introduction] ePiX, a collection of batch utilities, creates mathematically accurate figures, plots, and animations containing LATEX typography. The input syntax is easy to learn, and the user interface resembles that of LATEX itself: You prepare a scene description in a text editor, then ” compile” the input file into a picture. LATEX- and web-compatible output types include a LATEX picture-like environment written with PSTricks, tikz, or eepic macros; vector images (eps, ps, and pdf); and bitmapped images and movies (png, mng, and gif).

[\textbackslash n] ePiX's strengths include:

[::] Quality of output: ePiX creates accurate, publication-quality figures whose appearance matches that of LATEX. Typography may be put in a figure as easily as in an ordinary LATEX document.

[::] Ease of use: Figure objects and their attributes are specified by simple, descriptive commands.

[::] Flexibility: Objects are described by attributes and Cartesian location; as in LATEX, printed appearance is determined when the figure is compiled. A well-designed figure can be altered dramatically, yet precisely, with command-line switches or minor changes to the input file.

[::] Power and extendibility: ePiX inherits the power of C++ as a programming language; variables, data structures, loops, and recursion can be used to draw complicated plots and figures with just a few lines of input. External code can be incorporated in a figure with a command line option or by using a Makefile.

[::] Economy of storage and transmission: For a document containing many figures, a compressed tar file of the LATEX sources and ePiX files is typically a few percent the size of the compressed PostScript file.

[::] License: ePiX is free software. You are granted the right to use the program for whatever purpose, and to inspect, modify, and re-distribute the source code, so long as you do not restrict the rights of others to do the same. In short, the license is similar to the terms under which theorems are published.

[\textbackslash n] ePiX facilitates logical, as opposed to visual, structuring of mathematical figures, analogous to the relationship between LATEX and a word processor. A few stylistic defaults streamline the creation of simple figures, but there are few internal restrictions on the contents or appearance of a figure; aesthetic and practical decisions are left to you.

[\textbackslash n] If you are a:

[::] Potential user, you may wish to skip immediately to ” Software Dependencies” before investing additional time.

[::] New user, proceed from here until you have enough understanding to run the software, then experiment with the samples files while reading Chapter 2, or return to the manual as needed.

[::] More advanced user, browse at will, probably starting with Chapter 3.

[\textbackslash n] This manual is relatively conversational, and occasionally redundant, especially between portions meant for readers at different levels of familiarity. Throughout, you are assumed to be familiar with LATEX and basic linear algebra: the description of points, vectors, lines, and planes in three-dimensional space. Other material, such as C++ syntax, is introduced as needed.

[\textbackslash n] [...]

[Appendix A - Software Freedom] Academics in general, and mathematicians in particular, depend on free exchange of information. We prove theorems or establish experimental results, write up formal accounts, place preprints on public file servers, and submit papers to peer-reviewed journals. If accepted, the results -- data, techniques, methods of reasoning, citations, and conclusions -- are published in print and become part of the public record, governed by copyright law. Libraries purchase journal subscriptions, but researchers and scholars may use ideas from the literature merely by giving appropriate citations in their own work. ” Theft” arises from false claims of authorship.

[\textbackslash n] Carried over to software, the academic process would guarantee rights similar to those provided by the GNU General Public License (GPL):

[::] (GPL 0) To run a program for any purpose.

[::] (GPL 1) To study how the program works, and adapt it to your needs.

[::] (GPL 2) To redistribute copies of the program.

[::] (GPL 3) To improve the program, and release improvements to the public, so that the whole community benefits.

[\textbackslash n] In reality, attitudes toward software differ markedly. Most academics work on a proprietary platform, use proprietary software for research and teaching, and share information with colleagues and students in proprietary, even obfuscated, data formats. Contrary to the academic ethic, proprietary software licenses restrict access to information: preventing users from learning how a program works internally ( ” reverse engineering”), limiting the number of users who may run a piece of software, and forbidding users from running (or sometimes even installing) a purchased copy on multiple machines.

[\textbackslash n] Restrictions on use aside, if one cannot examine a program's source code, one cannot fully trust the output, any more than one can trust (for purposes of scientific publication) results of a commercial testing lab.

[\textbackslash n] Consider a hypothetical future world in which scholarly results are disseminated like software. Instead of subscriptions, journals sell licenses granting readership to a specified number of individuals. Photocopying an article for a class or research seminar constitutes ” piracy”, though if the institution has purchased a sufficiently large site license the teacher or speaker may bring the physical volume to class and project the pages onto a screen.

[\textbackslash n] Of course, reading an article is scarcely enlightening. Mathematics papers contain only the statements of theorems. Merely opening the journal binds the reader to a lengthy legal agreement, stating that theorems be used only for specific purposes and threatening serious legal consequences for attempting to discover the author's proofs.

[\textbackslash n] The actions of a single student, employee, or faculty member can expose an institution to a costly ” journal audit” from the Mathematical Society of America (MSA), with the institution responsible for legal costs if the audit reveals license violations anywhere in the organization.

[\textbackslash n] Mathematicians who long for the Old Days when papers contained proofs and were shared freely are dismissed as idealistic cranks or labeled antibusiness communists. Common knowledge asserts the obvious superiority of proprietary journals, and the necessity of licenses for keeping mathematicians gainfully employed.

[\textbackslash n] Back in our world, some vendors have attempted to placate opponents of closed source with ” shared source” licenses, under which one may sign a nondisclosure agreement and subsequently examine source code. In the future world analogy, a shared source agreement would allow journal licensees to sign an NDA, then see the proofs of theorems. Readers could thereby correct errors in proofs (benefitting the publisher by improving the reliability of the journal), but would be legally forbidden from using the ideas elsewhere (denying benefit to other mathematicians).

[\textbackslash n] Legally and conceptually codifying software as a commodity ignores a fundamental reality: Like an idea or recipe, software can be copied without loss of the original. The perception of ” theft” by copying arises from an artificial belief that software has an owner who must be monetarily compensated each time a person acquires a copy. The nature of software does not enforce the ” sale” model in the way services and physical commodities do. It therefore seems philosophically inappropriate to treat software as a commodity, and perilous to conform the legal system to the enforcement of such a model.

[\textbackslash n] At its best, software enhances our productivity and creativity. Sharing software, like sharing ideas, benefits a larger number of people without detriment to existing users. I hope this modest program is, in conjunction with the much larger efforts of others (especially Donald Knuth, Richard Stallman, and the many people who have contributed to the authorship of LATEX and its packages), useful to you in your mathematical work.

[\textbackslash n] [...]},
  keywords = {*imported-from-citeulike-INRMM,~INRMM-MiD:c-14159312,computational-science,epistemology,free-scientific-knowledge,free-software,knowledge-freedom,latex,mathematics,open-science,reproducible-research,science-ethics,scientific-communication,scientific-knowledge-sharing,technology-mediated-communication,visual-notation,visualization},
  pagetotal = {113}
}
Downloads: 0