From odf-dev-return-929-apmail-incubator-odf-dev-archive=incubator.apache.org@incubator.apache.org Sun Jul 1 21:31:43 2012 Return-Path: X-Original-To: apmail-incubator-odf-dev-archive@minotaur.apache.org Delivered-To: apmail-incubator-odf-dev-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 8B394D5DC for ; Sun, 1 Jul 2012 21:31:43 +0000 (UTC) Received: (qmail 23633 invoked by uid 500); 1 Jul 2012 21:31:43 -0000 Delivered-To: apmail-incubator-odf-dev-archive@incubator.apache.org Received: (qmail 23591 invoked by uid 500); 1 Jul 2012 21:31:43 -0000 Mailing-List: contact odf-dev-help@incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: odf-dev@incubator.apache.org Delivered-To: mailing list odf-dev@incubator.apache.org Received: (qmail 23583 invoked by uid 99); 1 Jul 2012 21:31:43 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 01 Jul 2012 21:31:43 +0000 X-ASF-Spam-Status: No, hits=-0.7 required=5.0 tests=RCVD_IN_DNSWL_LOW,SPF_PASS X-Spam-Check-By: apache.org Received-SPF: pass (athena.apache.org: domain of noahktilton@gmail.com designates 209.85.217.175 as permitted sender) Received: from [209.85.217.175] (HELO mail-lb0-f175.google.com) (209.85.217.175) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 01 Jul 2012 21:31:37 +0000 Received: by lbol5 with SMTP id l5so6463936lbo.6 for ; Sun, 01 Jul 2012 14:31:16 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :content-type; bh=pUFDz3PWo/46Kx4G7oXBSTol9kPKm5z10l5zxzfUpuA=; b=wczzSLvcvuKSSokJfycfEb5emJpEI9chQHk5biHDXO/Satxn0iULQLCBAGZE2X4sVy eAyLQtTOg4sa+x05d9ZsAwvimCrXaBMrIkSdmeIAeWoPQ3hVJMXkDYulexDatCFqgenm UCaOADYE8Uyw9AVs/01pjmVw1DmwopS+VXP0clsAwfZXxCZgVaAiY3ozg9BoT615rNrb ILhDFpbEO/XC6YLj61jQCjlbhmnPc3eyrDOzbBDHziiv/rf0m1cz9iHeOME2MY37S6S+ yh9tSvhAu0+8K+5zmTSUqwaZg/emvQ7WKN6LM2IJk4Y8MsZS9+ghaCPO/SBHFMf0rZ0Z to3Q== Received: by 10.112.36.163 with SMTP id r3mr5000479lbj.87.1341178276177; Sun, 01 Jul 2012 14:31:16 -0700 (PDT) MIME-Version: 1.0 Received: by 10.112.23.101 with HTTP; Sun, 1 Jul 2012 14:30:35 -0700 (PDT) In-Reply-To: References: <4FAB91A6.1070800@apache.org> <4FC48DE3.3030502@apache.org> From: Noah Tilton Date: Sun, 1 Jul 2012 16:30:35 -0500 Message-ID: Subject: Re: ODF Command Line Tools -- Request for community feedback To: odf-dev@incubator.apache.org, Rob Weir Content-Type: text/plain; charset=UTF-8 X-Virus-Checked: Checked by ClamAV on apache.org Hi Rob, I just pushed to Github, please see below for an explanation of the changes and some questions regarding next steps. https://github.com/noah/odf-command-line-tools On Sun, Jun 3, 2012 at 12:47 PM, Rob Weir wrote: > > OK. Thanks for trying. Maven is great for managing Java project > dependencies. Well, at least for pure Java projects targeting > standard Java outputs like JAR's, WAR's, EAR's, etc. But the > Java/JRuby combination may be more complicated. > > I'm using Ubuntu 11.04 with bash. It isn't liking parts of that > script. But I was able to modify it as follows and it worked fine: > > #!/bin/sh > > if [ ! -d ./jars ]; then > > echo "Downloading jars" > mkdir -p ./jars > cd jars > > wget http://mirrors.gigenet.com/apache//xerces/j/binaries/Xerces-J-bin.2.11.0.tar.gz\ > http://apache.osuosl.org/incubator/odftoolkit/binaries/odftoolkit-0.5-incubating-bin.tar.gz > > for targz in *.tar.gz; do > echo "Extracting $targz" > tar zxf $targz > done > > cd .. > fi > > echo "Running test" > > JAVA_HOME="$(dirname $(dirname $(readlink -f $(which java))))" > echo "set JAVA_HOME to $JAVA_HOME" > CLASSPATH=./jars/xerces-2_11_0/xercesImpl.jar:./jars/xerces-2_11_0/xml-apis.jar:./jars/odftoolkit-0.5-incubating/simple-odf-0.7-incubating.jar:./jars/odftoolkit-0.5-incubating/odfdom-java-0.8.8-incubating.jar > export CLASSPATH > > jruby lib/oclt.rb I incorporated your portability changes to test.sh, and renamed it to setup.sh, to reflect the fact that it doesn't actually run the code -- it merely downloads jars and sets environment variables. To run the code from the odf-command-line-tools directory, type: source ./setup && jruby main.rb "source" is necessary because the script needs to export shell variables in the parent shell (i.e., not a subshell). If you want to use rdoc to build the documentation you may need to run: % jruby -S gem install rdoc before running % rdoc --main * from the top level directory (odf-command-line-tools). > Two things: build env and runtime env. For runtime env we should be > cross platform, right? For bulld env, cross platform is ideal, but I > would not get bogged down on that. Linux is fine. Yes, Linux for build only; runtime will be cross-platform. Added to TODO > I'm looking forward to seeing more on the DSL. The initial version of the DSL has support for generating new Text documents; loading modifying existing Text documents, iterating over Paragraphs, changing mode and font attributes of new Paragraphs ... This first version should give you a flavor of what the DSL might eventually look like, and I hope it is general enough that we can easily add other document types (e.g., Presentation). It's made up of 2 parts: the DSL proper (lib/oclt.rb) and a client script (main.rb). Assuming you're okay with what I've done so far, I'd like the discussion to focus on how the mapping of DSL methods => SimpleAPI methods should look. A 1-1 mapping works "out of the box" with the way the DSL is currently written. I.e., any SimpleAPI TextDocument method can now be called from the DSL, and will work. So if we don't want to change the interface/API, all that's left to do is write documentation and more examples. But that won't provide much of an improvement over the original Java API, only those benefits which Ruby provides at the most basic level before any "sugar" is applied. In other words, while a 1-1 mapping works, it leads to unnecessary initialization, overall verbosity, and (IMHO) is exactly what a good DSL should seek to avoid! As a next step, I propose creating a more concise set of keywords for the TextDocument API, and working from there. I'm hoping we can iterate very fast now that there is a working version. If we can come up with (or better yet, find) some conventions for how to map a standard API to a DSL, I can use that and hit the list when I have specific questions. For an example of what I'm talking about, do we really need to say "set_horizontal_alignment(HorizontalAlignmentType)" or will "center" suffice? Should that really be done instead as a parameter in add_paragraph()? (e.g., doc.add_paragraph(:alignment => :center)). Should we let it work both ways for flexibility At the same time, we don't want to take the sugar too far -- the interface should be logical to end users without being too "cute". A couple of examples of things I changed/added are: page_break instead of add_page_break; paragraphs as a new iterable method. The heavy lifting in the code is currently being done in the file lib/oclt.rb, specifically the method_missing call. Inside I have some logic that tests whether a certain method exists at runtime, and if it does, delegates appropriately. If the method doesn't exist the program bombs out, but there's no reason not to make it do something more intelligent, like search the SimpleAPI for a method which is similar to or begins with the given method name, and then perhaps give the user an informative error message. More formally, I think the code as written is (loosely) an implementation of the Adapter pattern (http://en.wikipedia.org/wiki/Adapter_pattern) but using open classes rather than an explicit adapter class. In ruby this can be done a number of ways, I was going for brevity. I invite your feedback, and the rest of the community too. Thanks and enjoy the 4th! -- Noah