Hi,
I think we're talking at cross purposes here.
The requirement is intended for examples as static text in, say, HTML
or PDF in documentation, for examples, code snippets or sequences of
administration commands. For example, Deploying a Web Service in the
Developer's Guide
<
http://docs.sun.com/app/docs/doc/819-3672/gbixz?a=view> contains this
example:
javac -cp javaee.jar -d domain-dir/autodeploy MyWSDemo.java
This example is potentially confusing because only some of the
replaceable items are actually replaced (javaee.jar, autodeploy,
MyWSDemo.java), whereas others are not (/domain-dir/).
The aim is to avoid such a mixture in examples,so the following example
would be reworked as something like:
javac -cp javaee.jar -d
/home/asuser/SUNWappserver/domains/domain1/autodeploy MyWSDemo.java
The whole purpose of the examples is to make the generic specific and to
make the abstract concrete. Examples don't have to be (and in fact
should not be) comprehensive. They just need to be plausible. If
necessary the explanation can clarify that, say, the domains directory
is /home/asuser/SUNWappserver/domains and that the domain is domain1.
I agree that we should avoid inventing our own environment variables for
examples.
I can understand that in example files, users will need to set paths to
correspond to what they have actually installed, otherwise the examples
won't work.
Regards,
-Paul
June.Parks_at_Sun.COM wrote:
> This could work for many code examples. For the domain.xml file,
> there is already a system property that can be substituted for the
> domain directory, and there may be one for the installation directory
> as well. For deployment descriptors, a build.xml file could be used
> in some cases. But the one thing all these have in common is that the
> true path is not shown directly, but represented by a variable.
>
> However, for path examples, and for deployment descriptor examples
> where the path is being discussed, this doesn't work so well. Most of
> the time it's the part of the path below the installation or domain
> directory that matters. The path of the installation or domain
> directory has so many variations that to show them all becomes quite
> cumbersome. And so far our books have only covered Sun Java System
> Application Server paths. When you consider the GlassFish paths too,
> it's really a mess.
>
> If there are standard environment variables that can be substituted
> for the installation and domain directories, I would be willing to
> change the text entities to use those. But this is ONLY a good idea
> if they are standard. We shouldn't be making things up willy-nilly as
> we've done in the past.
>
> June
>
> Ian Evans wrote:
>> Debbie Carson wrote:
>>> Ian could better answer this than I, but I think he's out of touch
>>> for now. In the Java EE tutorials, there is an
>>> examples\bp\project\build.properties file that the user must edit to
>>> provide the location of their tutorial and GlassFish installations.
>>> This file is used by the build.xml file when the example is built.
>>
>> Right. The user sets a few properties, and these are used by all the
>> common build scripts for the tutorial examples.
>>
>> A more sophisticated build system might make some educated guesses,
>> based on the OS, of the location of GlassFish. If it can't find
>> GlassFish, it would then display an error with instructions for how
>> the user should explicitly set the necessary properties.
>>
>> The point is, engineer the examples so that any OS-specific settings
>> are either figured out automatically, or set once.
>>
>> -ian
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe_at_glassfish.dev.java.net
> For additional commands, e-mail: docs-help_at_glassfish.dev.java.net
>
--
Paul Davies, Senior Technical Writer, Sun Microsystems, Inc.
http://blogs.sun.com/techscribe/