Ant based tool is not user friendly

[Broofa]

Hey Denis, as much as I like jGD, I have to say that as a user,
dealing with Ant is a major hassle.

The "ant"-ish nature of jgd is probably the biggest barrier to
adoption that jGD faces. New user should be able to get up and
running with jgd in a matter of minutes by going through the "normal"
workflow of ...
1 download package
2 run a one-line install command (unpack, unzip, whatever)
3 run "jgd *.js" or "cd [source dir]; jgd" (i.e. just point jgd at
the files you want to process)

But instead, they go through something like this ...
1 download package
2 run install command
3 install ant
4 copy and edit the ant configuration file
5 run ant

Steps 3 & 4 are both problematic. We've seen several users have
issues with the ant version they're running, and the ant configuration
file format is pretty cryptic. We're basically asking *javascript*
developers to become instant experts in ant config files.

And it's not just new users affected by this, as a contributer to the
project, my ability to do rapid iteration development is pretty
limited. I have an ant file set up to work on our javascript
codebase, but it takes jGD 5-10 minutes to process that. I would much
rather have a simple way to run jgd, directly from the dev directory
(instead of having to build/unpack the dist package each time), and
point it at a single file that I'm trying to debug.

But it's just not practical to do that. Creating a one-off
configuration file is too much of a hassle to bother with most of the
time. So I find myself shying away from doing development, and
skimping on the testing when I do.

Just some food for thought.

[denis.r...@gmail.com]

I'm not sure that I understand all the concerns.

Indeed, the current configuration of jGrouseDoc, where all
configuration properties are in XML file, is far from perfection and
there are plans to address it by moving all them into
separate .properties file. That should address the problem of
complexity.
You cannot get away from some kind of config file anyway, regardless
if you're using ANT-based tool or anything else.

I can hardly see how installation of ANT could be a problem - it is a
simple download/unzip. Nothing compared to installation of Perl with
required packages on Windows workstation (sure, not an issue for Linux/
Apple guys :-))

Nothing prevents you from running ANT from your dev directory. You
just need either to have run ant from your dev directory and pass the
name of build file. If build.xml is in your dev directory, then you
can simply run ANT without parameters.

Once the configuration properties are moved out from build.xml to a
separate file, there would be no need to update them manually every
time a new version is released, unless you would want to use new
configuration options offered by new release.

I also not quite understand the problem with rapid iteration
development and how it is related to usage of ANT.
If you want to troubleshoot problems with specific javascript file,
you can simply modify <jgdoc ...><fileset dir="${inputDir}"
includes="**/*.js"> line in build.xml to include only the file (or
files) that you need.

ANT is very powerful tool when it comes to specifications which files
should be processed or excluded from processing. If I was to build a
standalone command-line tool, I would have to re-implement a good deal
of functionality that is offered by it for tracking file dependencies,
selections of files to process, xslt task, etc.
Hey, for standalone tool I can see someone requesting "process files
in directories project1/, framework/ and mystuff/ but exclude any
files with names starting with test" - go figure what is the best
syntax for putting these conditions in a homegrown config file :-)

Am I missing something big time? I am willing to help, just want to
understand the problem.

BTW, just curious, what are you guys using for your build process?

regards,

[Broofa]

On Feb 6, 4:41 am, denis.riabtc...@gmail.com wrote:
> I'm not sure that I understand all the concerns.
>
> Indeed, the current configuration of jGrouseDoc, where all
> configuration properties are in XML file, is far from perfection and
> there are plans to address it by moving all them into
> separate .properties file. That should address the problem of
> complexity.
> You cannot get away from some kind of config file anyway, regardless
> if you're using ANT-based tool or anything else.

I guess I disagree. Why should a new user have to deal with a config
file if jgd has reasonable default settings (i.e. the default stuff
that's already in build.xml), and they can provide the files as
command line arguments?

Yes, a config file is useful when it comes to defining environment
customization, and for build scripts and the like. But at the end of
the day, ant config files are "power tools" that have a non-trivial
learning curve. For a new user that learning curve is a lot of
unnecessary work. :(

> I can hardly see how installation of ANT could be a problem - it is a
> simple download/unzip. Nothing compared to installation of Perl with
> required packages on Windows workstation (sure, not an issue for Linux/
> Apple guys :-))

True... but having to install secondary packages to get something
running is never the best user experience. Especially if there's any
possibility that the installation might go wrong (e.g. by installing
the wrong version). Even more so if the error messages you get as a
result are less than clear about the problem. (Which I think is the
case with jgd and the ant version).

> Nothing prevents you from running ANT from your dev directory. You
> just need either to have run ant from your dev directory and pass the
> name of build file. If build.xml is in your dev directory, then you
> can simply run ANT without parameters.

Hmm... I guess I just haven't figured out the magic incantation for
this. It doesn't help that our build file is using relative paths.

> Once the configuration properties are moved out from build.xml to a
> separate file, there would be no need to update them manually every
> time a new version is released, unless you would want to use new
> configuration options offered by new release.

Yup, and I look forward to this change. :)

> I also not quite understand the problem with rapid iteration
> development and how it is related to usage of ANT.
> If you want to troubleshoot problems with specific javascript file,
> you can simply modify <jgdoc ...><fileset dir="${inputDir}"
> includes="**/*.js"> line in build.xml to include only the file (or
> files) that you need.

That's _exactly_ the problem! I just want to test one file, not a
whole directory of files. And while I'm sure there's an obvious-after-
the-fact way to do that, I don't know what it is. 'Do I use <fileset
file="foo.js">? ... or <fileset dir="..." includes="foo.js">? ... or
something else?' I *know* the answer will be something reasonably
obvious, but as an ant-newbie, I don't know what it is. I have to
track down the ant documentation online, then sift through it to
figure out what tag/properties I should be using, and then find/edit
the config file.

Which is just silly.

> ANT is very powerful tool when it comes to specifications which files
> should be processed or excluded from processing. If I was to build a
> standalone command-line tool, I would have to re-implement a good deal
> of functionality that is offered by it for tracking file dependencies,
> selections of files to process, xslt task, etc.
> Hey, for standalone tool I can see someone requesting "process files
> in directories project1/, framework/ and mystuff/ but exclude any
> files with names starting with test" - go figure what is the best
> syntax for putting these conditions in a homegrown config file :-)
>
> Am I missing something big time? I am willing to help, just want to
> understand the problem.

I know ant makes your job (our job?), as the developer, much easier.
But exposing all the gory innards of ant to users is not a good idea.
It is does not result in a good user experience.

A simple invocation of "jgd *.js" or "jgd */*.js" would allow 95+% of
users to do exactly what they need, without ever having to muck around
in the configuration file. And while I agree a config file is
necessary for the more esoteric options and behaviors, I don't think
it's something those 95% of users should have to deal with.
And that goes double for new users.

If nothing else, it seems like there should be a simple bash script
that wraps the ant call, and that allows you to specify files on the
command line.

> BTW, just curious, what are you guys using for your build process?

Our main app is built using capistrano, but for the jgd docs, we use
custom bash script that runs hourly in a cron job.

[denis.r...@gmail.com]

1. The reason why at least basic editing of config file could be
required is in order to specify the "jgrousedoc home" directory. This
could be, of course, an environment variable, but certain setup would
be required anyway.
2. Hopefully the separation of config properties from build file would
make the start up least painful.
3. If wrong versions of ANT is a concern, then it should be possible
to provide a jGrouseDoc distribution pre-packaged with certified
version of ANT
4. No magic at all. Take a look at example provided with distribution.
Move all jGrouseDoc-related directories and files into another one
(everything except for build.xml and sample, which contains source
files). Update jGrouseHome property to the directory containing the
distribution and you're all set. Just run "ant" from directory
containing build.xml and that's it!
5. In your case you can use both options. I prefer simply modify
<fileset dir="${inputDir}" includes="**/foo.js" /> (assuming that
there is only one file called foo.js, otherwise specify the relative
path to file). Again, if that is a concern, then moving this thing out
to properties file would do the trick. Frankly speaking, the
documentation for ANT is excellent with tons of examples for all
possible cases (see for example http://ant.apache.org/manual/CoreTypes/fileset.html)
6. Again, moving the stuff into properties file should do the trick
7. If anyone would want to contribute a shell script to run jGrouseDoc
in simplified way I would gladly add it to standard distribution.

To summarize, I am still convinced that ANT based approach beats
custom configs. I am also willing to write Maven plugin if there is a
demand. But I don't think that it makes sense to reinvent the wheel
(again, for the 43245th time :-))

And of course, I am always willing to provide help regarding more
efficient use of the tool - just ask!

Regards,
Denis