On page 144, the style guide also says, "Try to use code variables
instead of specific operating system, platform, or address space text in
examples. The use of variables avoids duplicating information."
June
Paul Davies wrote:
> Hi June,
>> 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.
> I do not share your understanding.
>
> The purpose of making the examples literal is to turn something
> inscrutable like /as-install/ into something that from its format is
> obviously (in this case) a directory.
>
> The style guide that we're following on the GlassFish project supports
> this viewpoint. Page 105 of /Documentation Style Guide for
> OpenSolaris/ (PDF)
> <http://opensolaris.org/os/community/documentation/files/OSOLDOCSG.pdf>
> states:
>
> When providing an example, follow these guidelines:
> ...
> Use practical data in the example rather than replaceable or
> variable text.
>
>> 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.
> So why include any examples at all? After all, how many users will
> have a file that is named MyWSDemo.java to compile?
>
> Regards,
>