-
Notifications
You must be signed in to change notification settings - Fork 1
Code Lit
Refs:
- [Paratexts: Thresholds of Interpretation] (http://books.google.com/books/about/Paratexts.html?id=AmWhQzemk2EC) by Gerard Genette, Cambridge University Press 1997
- Palimpsests: Literature in the Second Degree, Gerard Genette, University of Nebraska Press, 1997
- The Problem of Speech Genres, in Speech Genres and Other Late Essays, by Mikhail Bakhtin, University of Texas Press, 1986. Bootleg copies can be found on the web.
- On Philology, ed. Jan Ziolkowski, Penn State Press, 1990
- Future Philology? The Fate of a Soft Science in a Hard World
- Training Textual Critics in Textual Criticism Hans Gabler
- Text
- Codetext
- Code
- Metacode, in languages like Clojure. Metacode uses the same language as code (that is, the Clojure language) but functions as a kind of metadata or metacode.
- Datatext - the paradigmatic example is a file of numbers to be read into a program that crunches them, e.g. a CSV file containing data to be analyzed counts as a datatext. But codetext is also datatext; to a parser, every codetext (program) looks like a datatext. Datatext can be embedded in codetext.
- Paratext
- Metatext - distinct from metacode. Text that is about the codetext, e.g. explanatory documentation, is metatext in this sense.
Text may be address different audiences, for different purposes. The requirements (norms) in each case may vary drastically.
- Pedagogical. It is often assumed implicitly that pedagogical text involves lots of hand-holding and careful explicit guidance for the poor benighted reader. But this not a requirement. Case in point: Smullyan's First Order Logic is a small pedagogical masterpiece that does almost no handholding. Smullyan wastes no words explaining why things are the way they are, he just provides lots of definitions and examples that show that reader what things are (e.g. analytic tableaux and lots of other stuff), all in about 150 pages. It is up to the student to do the work necessary to come to a genuine understanding of the material. See also Requiem for Philology, which makes a strong case for teaching the old-fashioned, where the teacher is a master who has something important to say, and not a nanny for students cannot or will not do the work themselves.
The relevance of this for LP is that the kind of detailed exegetical text usually recommended (Knuth's LP programs are paradigmatic) cannot be deemed the best way to do things, even for teaching purposes. I think the example Knuth gives in his LP paper is a good example: I suspect that the raw code could be greatly improved, to the point that most if not all of his explanatory text could be eliminated.
-
Scholarly communication. The purpose is to communicate research to fellow professionals. The needs here are quite distinct from the needs of pedagogical writing.
-
Professional. I.e. code written solely for the purpose of supporting some product or service for sale. The ideal for this sort of code is that it would never be read by anybody except a computer. The need to read it only arises when bugs appear that need to be fixed or enhancements are required. Even then, the commercial imperative dictates that the smallest possible amount of code be read; maintainers are virtually never expected to read all of the code of a largish system. The programmers are expected to be professionals, so writing detailed pedagogically-oriented documentation would be a dereliction of duty in most cases.
The ideal here is engineering. Bridge engineers do not (I assume) "document" their designs by explaining fundamental principles of engineering. If they do need to include some kind of technical documentation they will do so by referring to the professional literature. Software engineers should do likewise - if the code uses some specialized algorithm, it should not be documented directly in the code; rather, the code should contain a reference to literature whose purpose is explication of the algorithm. That's not always possible, but even if there is no accessible literature, the algorithm should not be documented as part of an application. Document the algorithm separately, in a document devoted solely to the explication of the algorithm.
A palimpsest is basically a text inscribed on paper from which a previous text has been erased or scraped off. Back before the days of cheap paper this was not uncommon.
A program text under the control of a modern version control system can be viewed as a palimpsest.
One text making reference to or using another; the paradigmatic example is quotation. So-called hyperlinks on the web implement a form of transtextuality.
Today "hypertext" means, just about everywhere, HTTP-based links to other documents. But that's really a misnomer; transtext would be more appropriate. Genette takes the "hyper" in hypertext literally, and uses "hypertext" to refer to "superimposition of a later text on an earlier one that includes all forms of imitation, pastiche, and parody as well as less obvious superimpositions". (Paratexts, p. xix). So a hypertext is superimposed on top of a hypotext (hyper=above, hypo=below). Version control systems can be viewed as hyper-hypotext systems in this sense.