Please help me with document extraction.

[Max TenEyck Woodbury]

On 02/28/2011 08:08 AM, André Hentschel wrote:
> Am 27.02.2011 20:37, schrieb Max TenEyck Woodbury:
>> I've picked up Perl in the last couple weeks. An interesting language
>> with lots of adopted features. It's been easy to learn, so I think I
>> will _not_ need help with the language itself, but I will listen to any
>> advice.
>
> When i started with Wine developing i tackled winemaker which is also in perl.
> I also had to learn Perl for it, so i know you situation. Perl is truely cool,
> but the "inline" use of RegEx is sometimes confusing (So are $_ and friends)
> and i hate to use curly brackets for every "if".
>
Perl's focus seems to be on compact code. Since I have an existing
program to work from, I don't have to learn it all at once. The Perl
regex is quite a bit more advanced than some others and I'm happy to
learn the new features it present. I find it easy to learn.

Curlies are frustrating if you insist on a style that emphasize them,
but I think that is due to the conflict between a 'lots of white space'
style and the compact philosophy built into the language. The focus
should be on the purpose of the code, not on the syntax of the
language.

>> The c2man.pl code is extensive and sparsely commented. In order to
>> understand what it does, I've made a transcription of it with a more
>> compact style and lots more comments. I check the rewrite against the
>> source code so there should not be any serious errors. There are also a
>> number of what I believe to be defects in the original and places where
>> my comments may be inappropriate or my style may be very objectionable.
>> _This_ is what I need help with.
>>
>> Would someone be willing to review my rewrite? If so, send me e-mail so
>> I can arrange to get a copy of it to you.
>
> Remember that you won't get one big patch in at once, you need to split it up later.
>
I was going to try for a whole hog replacement, call it c2man2 or
something like that, but I can retro-fit as needed.

>> P.S. to AJ et al.
>>
>> There is a _lot_ of documentation embedded in the wine code, but it is
>> hard to find at the moment. I'd like to see it indexed and this is the
>> program that does the extraction and indexing. Advice on making this
>> new version available and active are in order.
>>
>
> I think the idea of building upon the existing "documentation" somewhere else
> has a better chance than the "deal on the 100"
>
Frankly, I believe embedded documentation is the way to go. It is _not_
a panacea, but it is better than trying to maintain a separate set of
functional documentation. I have seen cases where it worked. Not great
but OK. I tried the separate document approach and got _very_
frustrated, and _no_one_ was really interested.

Max