[pdftex] pdftex compression -- proposed addition to manual
mark at astrid.upland.ca.us
Mon Aug 27 07:04:35 CEST 2001
At 06:45 PM 8/27/01 +1000, Greg Black wrote:
>Hans Hagen wrote:
>| At 03:12 PM 8/25/2001 +1000, Greg Black wrote:
>| >More comments does not mean good comments. And excess comments
>| >usually indicate poor code; and far too often they get out of
>| >synch with the code, at which point they become a hindrance.
>| It depends, in tex and mfont there are sections explaining the principles
>| behind breaking pars into lines, hyphenation, curve construction etc. Lit
>| prog at least makes sure that such background info ends up in the source
>| [with typeset formulas].
>No, LP does not ensure anything of the kind -- disciplined
>authors ensure the information ends up somewhere useful. If the
>information is best provided in typeset form, there's nothing to
>stop them from writing a suitable TeX document to accompany
>their code --- this is something I frequently do. But it's not
>something that just magically happens with LP.
Literate programming does not ensure that such documentation gets
written. Only -- as Greg points out -- positive action on the part of the
developers can do that.
In this context, "developer" has to mean "programmer", I think -- at least
I don't hear anyone volunteering to write documentation on the code as
others develop it.
Literate programming tools put the documentation next to the code, and
allow the code+documentation to be typeset (thus giving the documentation
more flexibility than comments alone). Proximity encourages writing the
documentation (although not requiring it). Providing an appropriate
environment for writing documentation (presumably TeX, for this project)
helps with the appearance of the result.
But at seventh and last, someone who understands the code has to make sure
its understandable and maintainable. Usually that involves both work in
the code itself (choice of variable names, etc, as Greg pointed out
earlier) and documentation. Literate programming provides a mechanism for
doing this, but doesn't enforce it.
Knuth claims that literate programming encourages authors to write the
appropriate documentation, as its lack is more obvious. My experience tends
to confirm this. But the word is "encourage". Not "require". Programmers
can, and sometimes do, ignore that encouragement. Writing good code is
hard work. Writing good code documentation is also hard work -- and it's a
different kind of work.
Only if the developers want to write clear, maintainable code will the
effort needed to make that happen be expended, regardless of the tools in use.
I believe casting the pdfTeX code in a literate programming form would make
it easier to write clear, maintainable code. Obviously there are
reasonable people who disagree. But the people whose opinions probably
count the most are the people actually writing the code (although I find LP
tools useful in "retro-documentation" as well :-).
Whether Knuth wrote good or bad code, and whether changing technology
affects the answer to that question is interesting, but perhaps off
topic. Whether Knuth is an example or not, I guarantee that it is possible
to write code that is poorly documented and difficult to understand even in
a literate programming tool. Neither the presence or absence of literate
programming will guarantee that the current authors will write good,
I'd like to suggest a more concrete discussion of alternatives:
1. Move to a "language aware" LP tool such as CWEB or FWEB. This option
requires finding a tool that supports the programming language(s) in use;
both CWEB and FWEB support C and C++, which I gather are the primary
development languages. In principle, it doesn't require a special (unique
to the tool) markup syntax for the documentation, but the examples I am
familiar with do in fact use unique markup systems (largely inspired by the
markup in the original WEB tool).
2. Move to a "language independent" LP tool, such as Nuweb. This may or
may not require a unique markup; Nuweb does not (which is one of the
reasons I suggested it as an example). Nuweb documentation is ordinary
LaTeX, which I suspect everyone developing for pdfTeX is at least somewhat
3. Continuing as currently is always an option.
Mark B. Wroth
<mark at astrid.upland.ca.us>
More information about the pdftex