[interchange-docs] xmldocs - jon modified refs/OrderProfile

[Davor Ocelic]

On Sun, 12 Oct 2008 10:58:17 +0200
"Stefan Hornburg (Racke)" <racke at linuxia.de> wrote:

> docs at icdevgroup.org wrote:
> > User:      jon
> > Date:      2008-10-11 23:37:22 GMT
> > Modified:  refs     OrderProfile
> > Log:
> > Note pitfalls of broad * file glob.
> 
> Jon, thanks a lot for that patch. I think it is a good idea
> to make an entity out of it and include it in other places,
> namely for include configuration directive.

To do so, you would define an entity in docbook/literals.ent,
like all others you see there. Something like,

<!ENTITY GLOB-NOTE "<para>
A wildcard can be used instead of listing the files individually.
Beware of editor working files, backup files, etc., that would be
included with a broad file-matching glob of <literal>*</literal>
even though that would be easiest.
.</para>">

Then, in OrderProfile, you can write simply &GLOB-NOTE; , and it
can be reused on other places too.

Also, for extra bonus -- this note about globbing is a relatively
important piece of information and as such it deserves a place
directly in description or notes section (in this case
I think NOTES is best).

And it also helps keep our examples clean and straight to the point --
the policy I've been trying to maintain is that examples should not
tell a person anything new -- all information should be in 
description and/or notes section, and examples should just show
hands-on what was already explained there.

So in the end that would be:

__NAME__ notes
&GLOB-NOTE;
__END__


Many thanks,
-doc