- status: open --> open-accepted
In version 0.2 of generguide, variables have been
implemented using ENTITIES.
However, ENTITIES have a number of deficencies.
1. Entities are not stored as XML. This makes it
difficult to process entities with the rest of
generguide framework which is based on XSLT.
2. Limited support from WYSIWYM editors. In
particular, the XXE docbook editor can handle all other
requirements of generguide, but cannot handle
generguide's use of ENTITIES.
Options mentioned so far include:
1. Continue to use ENTITIES for variables
2. Extend Simple Docbook Schema to include a <variable>
tag.
3. Use <xinclude> to point to a configuration file.
This works, but adds about 2 lines of typing to enter
one variable. This would not be too bad if editors we
designed to support this.
4. Use olinks.
Here is the description from the Users Guide:
---------------------------------------------------------------------------
Variables like "project_name", or "cvs_host_directory"
can be inserted into source documentation.
In version 0.2 of generguide, variables are implemented
using ENTITIES. ENTITIES have deficiencies and we are
considering alternative implementations for future
releases.
Variables are inserted in documentation using:
<<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE para PUBLIC "-//OASIS//DTD Simplified DocBook
XML V1.0//EN"
"http://www.oasis-open.org/docbook/xml/simple/1.0/sdocbook.dtd"
[
<!ENTITY % xinclude
PUBLIC
http://www.ga.gov.au/education/facts/mapproj/se_3_3.htm#map
"-//GenerGuide//ELEMENTS XInclude for SDocBook V1.0//EN"
"http://generguide.sourceforge.net/xinclude/1.0/xinclude.mod">
%xinclude;
<!ENTITY % entities
PUBLIC "-//GenerGuide//ENTITIES Customization for
GenerGuide//EN"
"resources/entities.ent">
%entities;
]>
<para>This project name is &projectname; </para>
Variables can be stored in entities.ent using something
like the following:
<!-- The name of this project -->
<!ENTITY projectname "Generguide">
---------------------------------------------------------------------------