It is my understanding that the intent of making examples literal is to
allow users to use them as is, to copy and paste them. This is great
when it's possible. With AS-specific paths, it's often not possible.
It seems to me there's no advantage in being literal when the user has
to substitute values that apply to him or her anyway.
June
Paul Davies wrote:
> 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
>>
>