|
jplindstrom has asked for the wisdom of the Perl Monks concerning the following question:
How-Perl-saved-the-day today.
The problem: SQL tables and procedures are documented in the source code and now we want to include a subset of them in a written introduction/tutorial. Copying the text into the Word document is bound to make them go out of sync. And it's boring...
The solution: A little script to extract the documentation and write it to small Word files, grouped by sub system. These word files are then linked into the main document, so they can be re-generated independently from the main document.
Making it happen: At first I thought RTF would be the right choice for this , but that just ended up being messy, and I didn't have time to get to know the RTF format. So I turned to automating Word instead. Surprisingly, I couldn't find a simple wrapper around the Win32::OLE module, so I hacked something together using example code from the Net.
The code: Now I have an extremely simplistic module that does the not-so-heavy lifting. This is basically it:
package Word::Document::Writer;
use Data::Dumper;
use Class::MethodMaker new_with_init => "new",
get_set => [ "oWord", "oDocument", "oSelection", "hasWritten"
+];
sub init { my $self = shift;
my (%hParam) = @_;
$self->hasWritten(0);
$self->oWord( Win32::OLE->new('Word.Application', 'Quit') ) or die
+("Could not create OLE Word: $!\n");
$self->oDocument( $self->oWord->Documents->Add ) or die("Could not
+ add Word document\n");
$self->oSelection( $self->oWord->Selection ) or die("Could not get
+ Word selection\n");
return;
}
sub WriteText { my $self = shift;
my ($text, $level) = @_;
$level ||= 0;
my $style = $level ? "Heading $level" : "Normal";
$self->oSelection->TypeParagraph if($self->hasWritten);
$self->hasWritten(1);
$self->oSelection->TypeText($text);
$self->oSelection->{Style} = $style;
return(1);
}
sub SaveAs { my $self = shift;
my ($file) = @_;
return( $self->oDocument->SaveAs($file) );
}
__END__
I can use it like so:
my $oDocument = Word::Document::Writer->new();
$oDocument->WriteText("A level 1 Heading", 1);
$oDocument->WriteText("Basic Normal paragraph");
$oDocument->SaveAs("mydocument.doc");
The new problem: What do I do with this code?
It solves an actual problem, but the problem wasn't very difficult to solve. So it hardly does anything while being very useful in my little script. Is it useful enough to merit a CPAN upload (after adding POD and tests obviously)?
If it is, what namespace should I use? Hogging the namespace for this puny module seems almost rude. While Word::Document::Writer::Simple is an option, most other *::Simple modules are supposed to be simple to use, and a more proper name would be Word::Document::Writer::Simplistic :) But that sounds ridiculous.
So, rude or ridiculous? Or something completely different?
/J
|
Re: Module advice: when is it too insignificant to release?
by bart (Canon) on Nov 23, 2004 at 19:53 UTC
|
It solves an actual problem, but the problem wasn't very difficult to solve.
You say that now. It looks like you had a rather hard time making it, though, and it's an experience you probably want to avoid next time, thus: keep it stored somewhere. If you want to keep this, why not upload it? Somebody probably will be glad you did...
If it is, what namespace should I use?
I like what you have... but that's just me. Nobody complains about the Spreadsheet::* modules, either... Just don't call it Simple unless something similar, more complete/complex is available.
But personally, I'd be inclined to create something under Win32::OLE. Perhaps Win32::OLE::Word::Writer...
| [reply] |
Re: Module advice: when is it too insignificant to release?
by dragonchild (Archbishop) on Nov 23, 2004 at 20:26 UTC
|
If your module depends on Win32::OLE, I would strongly urge you to put it under that namespace or, at the very least, in the Win32 namespace. Windows-specific modules are definitely the exception rather than the rule in Perl1, so I would consider it polite to mark it in some way, rather than put it into the general population.
Personally, I'd call it Win32::Word::Writer::Simple - it's Win32-specific, it deals with Word, it writes, and it's simple. Or, if you feel ambitious, call it Win32::Word::Writer and allow yourself to be suckered into supporting all of the OLE commands that Word supports. :-)
- Frankly, any OS-specific module is the exception rather than the rule in Perl. It just so happens that Windows likes being exception-al more than most. *shrugs*
Being right, does not endow the right to be rude; politeness costs nothing.
Being unknowing, is not the same as being stupid.
Expressing a contrary opinion, whether to the individual or the group, is more often a sign of deeper thought than of cantankerous belligerence.
Do not mistake your goals as the only goals; your opinion as the only opinion; your confidence as correctness. Saying you know better is not the same as explaining you know better.
| [reply] |
Re: Module advice: when is it too insignificant to release?
by samtregar (Abbot) on Nov 23, 2004 at 20:52 UTC
|
Definitely release it. Just add some POD and some tests and you've got a fine first release. If other people need more complex functionality then they can contribute it to your module and at least you've saved them the trouble of getting started.
-sam
| [reply] |
Re: Module advice: when is it too insignificant to release?
by revdiablo (Prior) on Nov 23, 2004 at 20:03 UTC
|
I have read recommendations (I don't remember where, or I'd give a link) that your namespace should start out generic and get more specific. That makes sense to me -- that way, similar modules tend to get grouped together in similar namespaces (assuming people use the same generic words, but that's a different matter). Following this advice, you might consider something like Document::Writer::MSWord. This would allow, say, Document::Writer::WordPerfect, or even Document::Writer::HTML, to coexist in a happy little world.
| [reply]
[d/l]
[select] |
Re: Module advice: when is it too insignificant to release?
by rrwo (Friar) on Nov 24, 2004 at 11:44 UTC
|
It solves an actual problem, but the problem wasn't very difficult to solve. So it hardly does anything while being very useful in my little script. Is it useful enough to merit a CPAN upload (after adding POD and tests obviously)?
Why not, assuming that there isn't something exactly like it that you were previously unaware of.
And it doesn't sound so simple. Somebody who doesn't know how to use OLE would have to read up on how to do what you're doing. By sharing your module, you save somebody a lot of time.
I've uploaded some painfully simple modules to CPAN on the basis that I kept writing the same stupid little subroutines to do the same things, and figured it was worth it.
MSWord might be a better namespace than Word. You might try MSWord::Writer::Lite.
I would ask around on various forums as to namespace suggestions before uploading it though.
At first I thought RTF would be the right choice for this , but that just ended up being messy, and I didn't have time to get to know the RTF format.
RTF isn't so hard to learn, and has various advantages over Word.
| [reply] |
Re: Module advice: when is it too insignificant to release?
by ff (Hermit) on Nov 24, 2004 at 13:41 UTC
|
Thank you. I believe I've gone looking for easy/fast code which dumps to '.doc' format and been disappointed. I've used what I've found to great effect, but your offering appears to be a straightforward way to dump text to '.doc'.
A couple minor things "got" me in playing with your sample:
1. The package seemed to need a line saying use Win::OLE;
2. I thought the file would land in the current directory but instead it landed in "My Documents". No big deal for me to put an absolute path name like "C:\\mydocument2.doc"
3. I'm confused about SaveAs: it's calling a different SaveAs routine, isn't it, and so might your method stand having a different name?
As to how to name it WHEN you upload it, I like the "general to specific" approach previously mentioned. | [reply] |
|
|
Re: 1. and 2. Those are things that are actually in my script, but I lost them while copying the module to the node text. Especially the absolute file name thing. This piece of code:
my $fileModule = cwd() . "\\$module.doc";
is is something I should move into the module, so thanks for pointing that out!
Re: 3. The SaveAs() method delegates it's implementation to the Word Document object, so I think it's okay to name it that way. Or maybe I don't understand your point why it could be better named.
/J
| [reply]
[d/l] |
|
|
My preference is to have names that are unique as a way of preventing confusion. If you call your method SaveAs, and your module invokes a method by the very same name from another module, then at maintenance time I have to be smart enough to know that the good old SaveAs from Win::OLE is not what the code is referring to. In other words, since another module already uses the term SaveAs, can't the method within your module have a slightly different name?
And on the note that it's nice to have unique terms for new pieces of software: I see that WordWriter is actually a commercial package written in Java for creating Word documents and also that Ken Tomiak uses perl2word as the name of a sample Word document maker (Win32::ole and MSWord). However, I don't see any hits by google for pl2word and so perhaps this could be the name for your module. Although the letter l looks a lot like the number 1....
| [reply] |
Re: Module advice: when is it too insignificant to release?
by adamk (Chaplain) on Nov 25, 2004 at 12:13 UTC
|
If you had a need and fulfilled it in a way that can be encapsulated, then go ahead and put it up on CPAN. But a couple of things to note.
If you take the dominant and most obvious name for a particular idea, people are going to find you the most often when they are looking to solve the same problem.
This means your module is gradually going to become the authorative module on the topic, and any time you want to modify it, you are going to have support issues with the current users. Since we don't yet have a workable CPAN Statistics capability, this means that after a while (I normally set it at around 3 months) you have to take the attitude that you now have "users" and if you change stuff, it could break their applications.
So while you should by all means put it up, you should go over the design a couple of times and be 100% sure of yourself that
1. The basic design is correct.
Should it be OO or procedural, what sort of parameter and return value conventions should be used, are any major perl modules you use the best one for the job.
2. The API is both correct and extensible.
If you have bugs or sub-optimal stuff happening behind the scenes, you can always fix it, but you may well be stuck with the API FOREVER (or at least for a very long time, note that it can take 5 years to fully deprecate a function and remove support for it)
Are the class and method names the right ones? If you are only providing a very limited set of functions, can you see where you or someone else would be able to add other things later?
Take your time to get the design and API and any other interfaces right because it's painful to change. The code, well you can stuff with that all you like.
When the time comes to upload and take a piece of the namespace (the only limited resource CPAN has) you want to be 99% certain it's going in the right place.
If you want to upload experimentally, make sure to use a 0.00_01 type version so everyone/everything/everycode is aware it is not a "real" release.
I am by no means trying to dissuade you from uploading, I think what you have is perfect for turning into a module, I'm just suggesting not to rush to upload in an off-hand way just because you can. | [reply] |
Re: Module advice: when is it too insignificant to release?
by Jenda (Abbot) on Nov 25, 2004 at 01:03 UTC
|
back to the original task ... there are some RTF related modules on CPAN, neither makes creating the needed documents easy enough? Not sure if that would be of any help, but you might even like (unless you look under the cover) my Template::RTF. That'd allow you to make a bunch of templates using MS Word and then fill them in with content. Loops and conditionals included ;-)
I don't have any use for the module myself just now, but do not want to see it die. Anyone want's to take over from me?
Jenda
We'd like to help you learn to help yourself
Look around you, all you see are sympathetic eyes
Stroll around the grounds until you feel at home
-- P. Simon in Mrs. Robinson |
| [reply] |
|
|
Actually it was the complexity of the RTF format itself, and particularly how it relates to Word documents that steered me away from that solution. Lots of unknowns.
And when I saved a Word document as RTF I expected some kind of style sheet definition and logical markup, but that didn't seem to be the case. To me it seemed that Word would write the visual markup all over the place. I don't know, maybe that's how RTF is supposed to work, maybe Word does it in a brain-dead manner.
Like I said, I didn't have any clue how RTF worked, and I didn't have the time or resources to read up on it. RTF was my first shot but it didn't pan out, so I moved on to solve my actual problem.
Your module looked interesting though and I nearly gave it a test run, but at that time I had already begun looking into automating Word.
/J
| [reply] |
|
|
