You are viewing a plain text version of this content. The canonical link for it is here.
Posted to user@forrest.apache.org by Ross Gardler <rg...@apache.org> on 2005/04/05 20:34:14 UTC
Re: Newbie question: defining ENTITY values in a separate configurati
on file
Paterline, David L. wrote:
> Hello all -
>
> I'm a new user of Forrest and the associated technologies, so I hope I can
> find some help with a basic question or two.
>
> Basically, I'm looking for a way to centralize definitions of text variables
> to be used throughout the various XML files in my project.
>
> I'm using entity references to refer to contents of pre-defined entities
> within my XML files. Within each file, I define the entity and then
> reference it:
>
> <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN"
> "http://apache.org/forrest/dtd/document-v12.dtd" [
> <!ENTITY frtzum '../xdocs/md/fretz/fretz_um.pdf'>
> ]>
> ...
> <td><link href="&frtzum;">User Manual</link></td>
> ...
>
> This works fine, within each XML file. For a couple of reasons, I'd like to
> collect all these entity definitions into a single configuration file
> (mainly to minimize maintenance issues, such as using a single definition in
> multiple XML files).
You might want to read the docs on linking for some interesting tricks.
See http://forrest.apache.org/docs/linking.html#indirect-linking in
particular see the "site:" psuedo-protocol for internal linking and the
"ext:" pseudo-protocol for external linking.
Ross
Re: Newbie question: defining ENTITY values in a separate configurati on file
Posted by David Crossley <cr...@apache.org>.
Ross Gardler wrote:
> Paterline, David L. wrote:
> >Hello all -
> >
> >I'm a new user of Forrest and the associated technologies, so I hope I can
> >find some help with a basic question or two.
> >
> >Basically, I'm looking for a way to centralize definitions of text
> >variables
> >to be used throughout the various XML files in my project.
> >
> >I'm using entity references to refer to contents of pre-defined entities
> >within my XML files. Within each file, I define the entity and then
> >reference it:
> >
> > <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN"
> >"http://apache.org/forrest/dtd/document-v12.dtd" [
> > <!ENTITY frtzum '../xdocs/md/fretz/fretz_um.pdf'>
> > ]>
> > ...
> > <td><link href="&frtzum;">User Manual</link></td>
> > ...
> >
> >This works fine, within each XML file. For a couple of reasons, I'd like to
> >collect all these entity definitions into a single configuration file
> >(mainly to minimize maintenance issues, such as using a single definition
> >in
> >multiple XML files).
>
> You might want to read the docs on linking for some interesting tricks.
>
> See http://forrest.apache.org/docs/linking.html#indirect-linking in
> particular see the "site:" psuedo-protocol for internal linking and the
> "ext:" pseudo-protocol for external linking.
Yes, as Ross said, using site.xml to define these links
is a good idea. See examples in a fresh site from doing
'forrest seed' in a new directory.
If you have other reasons for wanting to use xml entities
(e.g. common words and phrases) then you can define them all
in one centralised file in your project's
src/documentation/resources/schema/ directory. Declare the
file in your src/documentation/resources/schema/catalog.xcat
giving it a Public Identifier.
Here is a demo ...
The file src/documentation/resources/schema/my-entities-v10.ent
contains ...
----
<!ENTITY foo "This Foo">
<!ENTITY bar "That Bar">
----
The file src/documentation/resources/schema/catalog.xcat
added ...
----
<public publicId="-//Acme//ENTITIES My Special Entities V1.0//EN"
uri="my-entities-v10.ent"/>
----
The file src/documentation/content/xdocs/index.xml
----
<?xml version="1.0"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd" [
<!ENTITY % MyEnts-v10 PUBLIC
"-//Acme//ENTITIES My Special Entities V1.0//EN"
"this-system-id-gets-ignored.ent">
%MyEnts-v10;
]>
<document>
<header>
<title>Welcome to MyProj</title>
</header>
<body>
<section>
<title>Congratulations</title>
<p>Entity replacement demo ... &foo; and &bar;</p>
</section>
</body>
</document>
----
And the result is ...
----
Congratulations
Entity replacement demo ... This Foo and That Bar
----