These are the software tools (or perhaps more accurately this is my peculiar orchestration of software tools written by many others) that I use for writing and maintaining my own Notebooks and other writings (and drawings, and photographs, and whatever else). A portion of this writing appears on the CircuitousRoot.com website and, to a lesser extent, parts of the lemur.com website.
I've lost track, but this is at least my tenth attempt at some coordinated toolset for my personal writing since the early 1990s. Apparently, practice does not always make perfect.
The word "graphein" is simply the Greek present active infinitive of the verb meaning "scratch," "carve," or "write" (γράφειν). It seems general enough to cover the words, drawings, photographs, CAD models, webs of notes, and the like on which I use these tools. The Greek infinitive indicates "aspect," not time, and the infinitive named the "present" indicates that which is ongoing or habitual. This, too, seems appropriate.
I'm not presenting these tools online here with any desire to promote them as tools. As I use them, they aren't good general-purpose tools (and I can imagine quite reasonable arguments to the effect that they aren't even good special-purpose tools). They're just what I happen to use. Although they rely upon some sophisticated tools and standards such as the TEI, GNU make, VARKON, and so forth (which are not my work, and which, unlike my own contributions are in fact good tools), the way in which I patch them all together here might well strike some as absurd.
Rather, I'm presenting them here because it seems to me that they're a necessary complement to the open licensing under which I release most of my texts. It seems to me that in order for a text to be fully open it must not only be open under the terms of its license and transparent in its encoding, but also be modifiable with the tools used originally to create it. These are those tools.
These tools are licensed under the Free Software Foundation's GNU General Public License, version 2 or later, as described in their source files. Their documentation (what you're reading now) is licensed simultaneously in two ways (I can do this, since I wrote it): under the GNU Free Documentation License, version 1.2 (so that it can be redistributed cleanly with the programs in a GPL/GFDL environment) and under the Creative Commons Attribution-ShareAlike license, version 2 (for those preferring this type of license; note that Creative Commons recommends the use of the GPL for programs, as I have done here).
If for some reason you need them licensed under some other good free license, ask me. I don't think that they're important enough to fuss much over.
The name "graphein" is just the name I'm using for this set of tools. I don't think that its use here is important enough to warrant claiming it as any kind of service mark or trade mark. As I noted earlier, I'm only distributing these tools out of a sort of hyperactive sense of completion/closure. I'd be quite surprised if anyone at all noticed them.
As described here, I maintain all of the writing (/etc.) done with these tools in the "Subversion" revision control system. However, unlike many open-source projects which also maintain revision control (through Subversion, CVS, RCS, GNU Arch, or whatever) I do not distribute or provide the entire source tree. This is, after all, my own writing; it is not a "warts and all" public project.
What I distribute are the current drafts of that subset of my writing that is (more or less; often less) ready for some kind of public distribution, together with the current drafts of this set of tools which (along with many public tools, of course) I use to maintain this writing. Each document is distributed with its own licensing terms. Some are proprietary terms, but most of the licenses are open/free (e.g., the Creative Commons Attribution/ShareAlike license). Please check each document for its licensing terms and respect those terms.
For those documents which are distributed under licensing terms which permit modification, you could, if you so desired, set up your own copy of this γράφειν tool system and relatively easily produce modified versions. (I would hope that you have better things to do with your time, though.)
This seems to me to be a reasonable balance between the almost brutal openness of a true public project (which is admirable, but this is not such a project) and the more private, contemplative nature of essays, musings, personal scholarly research, and notebooks. You may differ. If so, that's great: take these tools or others and create something entirely your own which matches your vision.
I use the Linux environment, in a relatively modern "install-everything" desktop environment (SuSE 10.0 as I write this, though I started on earlier distributions and releases and my environment will change as distributions and their releases evolve). I isolate my work systems entirely from the public Internet - cutting the cable completely. No part of this tool set should be thought of as secure or ever run on a computer connected to the public Internet. Really. Never, ever.
At a basic level, all of the files are UTF-8 encoded in the Unicode/ISO10646 character encoding.
At a markup level, I use the Text Encoding Initiative's (TEI) markup language, release P5 (itself defined by the XML markup metalanguage). I edit my source files using the vi text editor. The non-CAD vector drawings are encoded in SVG (edited presently with Inkscape). CAD drawings are written (yes, written) in the VARKON system's MBS programming language plus the m4 macro processor, using the "Minimalist" Literate Programming facilities of graphein ("gMLP"). They are plotted in VARKON's PLT format (GKS, really), and converted to Postscript using a VARKON utility. Bitmapped images are presented in PNG and JPEG, as appropriate (and are edited using The GIMP). The hyperlinked note-taking system is built on WebDot and GraphViz.
The process of turning it into various presentable formats is driven by GNU make, using bash and Awk at times. Images are transformed and identified using programs from the ImageMagick suite. The transformation to XHTML (appropriate for screens) is specified by XSLT and accomplished via the Saxon processor and the the XML Commons Resolver. The transformation to PDF (appropriate for paper) is specified by XSL-FO and accomplished by the the Saxon processor, the XML Commons Resolver, and the Apache FOP XSL-FO Processor. [Note: Actually, though this is sketched in, I haven't yet written the XSL-FO parts.] The various programs, scripts, and stylesheets which comprise the working components of the system are themselves encoded in TEI source files using gMLP (graphein Minimalist Literate Programming).
All of this is stored in a Subversion revision control system repository.
I only test this by reading it (and not always even that; source in vi is often enough). As such the testing involves mostly Mozilla, gv, and, as appropriate, VARKON.
In current usage, the rather overly abstract name "Content Management System" refers to an arrangement where texts and other data are all stored in a database and then filtered on output into nicely formatted web documents. CMSs are used, for example, to manage many blogging websites. Each user's contributions appear as if they're web pages, but really they're database entries underneath, transformed on the fly into their presentational form. This is all very interesting, and there are several well developed Content Management Systems in the open source world.
What I need, however, is a system which focusses on the markup of (often complex) texts themselves. While it would be possible to implement this in a sufficiently complex database design, there wouldn't be much point in it. More to the point, a relational database is too flexible. It is (deliberately) syntax-free, and allows the definition of any relationship. This isn't quite what I need. What is important to me is to ensure that a particular Greek verb is marked up with all of its principle parts correctly identified, not to retrieve the blog entries of all users under the age of 30 since last Tuesday.
In both graphein and a Content Management System, the final output form is less important than the core data. But the difference is the difference between a markup approach and a database approach.
A database is like a warehouse for many items which can in some way be described in common terms. Text markup is, by architectural analogy, like a museum gallery where every item, though analyzed minutely in a common critical vocabulary, is distinct.
All portions of this document not noted otherwise are Copyright © 2006-2007, 2022 by David M. MacMillan.
Circuitous Root is a Registered Trademark of David M. MacMillan.
This work is licensed under either of two licenses, at your option:
(A) Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled " GNU Free Documentation License".
(B) This work is licensed under the Creative Commons "Attribution - ShareAlike" license. See http://creativecommons.org/licenses/by-sa/3.0/ for its terms.
Presented originally by Circuitous Root®
