[Generguide-bugs] [ generguide-Bugs-834305 ] How can docs implement variables?

[SourceForge.net <no...@so...>]

Bugs item #834305, was opened at 2003-11-02 08:38
Message generated for change (Settings changed) made by camerons
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=570159&aid=834305&group_id=83647

Category: generguide
Group: 0.2
Status: Open
>Resolution: Accepted
Priority: 7
Submitted By: Cameron Shorter (camerons)
Assigned to: Nobody/Anonymous (nobody)
Summary: How can docs implement variables?

Initial Comment:
Description:
=========
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:
======
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.

Description of variables from 0.2 Users Guide
===================================

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">
---------------------------------------------------------------------------

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=570159&aid=834305&group_id=83647