On 21-4-2011 18:33, Darren New wrote:
> On 4/21/2011 8:39, Invisible wrote:
>>>> I would object to something like storing RFC822 as comments inside your
>>>> SMTP implementation.
>>>
>>> Yeah, that's really not very appropriate.
>>
>> I may be incorrect here, but didn't Knuth embed The TeX Book in the
>> source
>> code for TeX?
>
> Literate programming is something different. In that case, you simply
> have one file that has both the compilable code and the documentation
> discussing it, with a tool to extract the two. If you have a programming
> language in which comments are *designed* to generate books with tables
> of contents and all that sort of stuff, and what you're documenting is
> the process of writing the code, then sure, that's not bad.

I have used it in the past and in my experience it works extremely well. 
Most importantly because both me and the colleague that were developing 
a large package *enjoyed* writing nice documentation. Becasue the 
documentation is generally on the level of small chunks (10-50 lines) we 
tended more to document the why than the actual implementation 
('increase counter by one')

I effectively stopped slowly when he left. He had it all nicely set up 
on a linux box. With all sorts of interlocking make files and scripts*. 
The Windows environment is more geared towards instant satisfaction. 
Press a button and it will automatically build. Pity if you want 
something done at some specific time during the compilation process, we 
though about it and you (who we assume to be a below average user) don't 
need that.

It is entirely possible that even in a Windows environment I might have 
been able to get something workable in the end, but I did not have the 
time and money to research it properly. Knowing that it is almost 
trivial within the un*x way of thinking might have played a role.

When I switch to a linux box (that might be soon, because of ICT 
department in the hospital**) I'll try to recreate such an environment.

*) Some changes might trigger a tool to create a tool to be rebuild. It 
could cause a chain of extracting the C and Matlab files from a source 
file. Call one of the matlabfiles to create an image for metapost, call 
metapost. Include the resulting figure in the documentation. Rebuild all 
documentation in pdf. Call one or more preprocessing steps on the source 
(this might include lex and yacc). Build the tool. Find all files that 
use this tool. Rebuild those too. Oh and everything under revision 
control of course.

**) not because they want that. They actually want to force everybody to 
use Windows machines. Simply because I cannot work the way they want me 
to*** and using a Linux box will buy me a few years to proof they didn't 
think through all consequences.

***) nor can the department afford the ridiculous pricing scheme they 
try to force on us.

-- 
Apparently you can afford your own dictator for less than 10 cents per 
citizen per day.

Post a reply to this message