[pdftex] pdftex compression -- proposed addition to manual

[M. Wroth]

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, 
maintainable code.

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 
familiar with.

3.  Continuing as currently is always an option.



Mark B. Wroth
<mark at astrid.upland.ca.us>