[Edocs-development] Use case XML language and figures

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

I'd like to recommend 3 minor changes to some of the
use case documents (before we get lots of them ;-)  ).

XML-STYL:ESHEET PROCESSING INSTRUCTION

Adding a processing instruction will permit Internet Explorer
to automatically apply a stylesheet to an XML document.

Presently, every use case, taking A1.xml as an example,
starts with,

- - - A1.xml (excerpt)
<?xml version="1.0"?>
- - -

I'd recommend adding an xml-stylesheet processing
instruction.  This instruction is presently Microsoft-specific
(although it is possible to modify Ant's action to use it
when locating that stylesheet to build docs with).

- - - A1.xml (excerpt, modified)
<?xml version="1.0" encoding="iso-8859-1" ?>
<?xml-stylesheet type="text/xsl" href="../../../UseCase.xsl" ?>
- - -

Unrecognized processing instructions don't affect other
applications [XML 1.0 + Namespaces specification],
so this addition should have no impact on non-Microsoft
browsers, while providing Internet Explorer browsers
with added value (IE users can open the XML document
and see the HTML automatically up-to-date).

While there, an encoding should be added for reasons
detailed in the next section.

INTERNATONALIZATION

I'd also recommend adding an encoding (to allow for
translation into other languages and character systems
in the future, for example, Big5 Chinese).  Although I
think the Latin 1 (ISO-8859-1) alphabet could be
sufficient for English and Italian.

Additionally, while this is optional, I'd like to recommend
we start supplying an "xml:lang" attribute with an RFC1766
lcid to the body element.   This way, each body (of which
perhaps there could be several) can be identified with
a language.

- - - A1.xml (excerpt, with changes)
<?xml version="1.0" encoding="iso-8859-1" ?>
<?xml-stylesheet type="text/xsl" href="../../../UseCase.xsl" ?>
:        :
        <body xml:lang="en-US" >
:        :        :
                <!-- English -->
:        :        :
        </body>

<!--    In the future, after use case is stable and translated ...

        <body xml:lang="it-IT" >
:        :        :
                <!-- Italiano -->
:        :        :
        </body>
-->
- - - 

Separate translations (one in English and one in Italian)
are represented as two bodies, one body in English and
the other body in Italian.  In XSLT, the lang function can
interpret this, and produce a corresponding HTML META
HTTP-EQUIV "Content-Language" tag.  This way, the
browser of the resulting document should see the English
version if the browser's preferred language is English, and
the Italian version if the browser's preferred language is
Italian (I have not tried this out thoroughly).

LOCATION-INDEPENDENT IMG ELEMENTS

The img elements in use case XML documents should not
assume knowledge about where their images are located.

For example, in A1.xml,

- - - A1.xml (excerpt)
<detview-section name="Use Case Diagrams">
    <img src="./diags/UC_A1_1.png"/>
			</detview-section>
- - - 

Suppose we change the directory where we store .PNG files in
the future?

All use case XML documents would have to be changed.  :-(

Better that the use case XML document is the image file is
co-located with itself ...

- - - A1.xml (excerpt, modified)
<detview-section name="Use Case Diagrams">
    <img src="UC_A1_1.png" />
</detview-section>
- - -

and we can "hide" our decision to place the diagrams in a diags
folder within the XSLT stylesheet like this,

- - - UseCase.xsl (imaginary excerpt)
<xsl:template
        match='img' >

        <img
                src='.\diags\{@src}'
                alt='{@alt}' />

</xsl:template>
- - -

What happens now if we change the directory where we store
.PNG files in the future?

One place, one change -- in the stylesheet.   Hmm, what if
there are multiple stylesheets?

In fact, it could be made a default parameter to the stylesheet,
when we have multiple stylesheets -- and then changes in the
build script percolate everyplace!   :-)

- - - UseCase.xsl (imaginary parameterized excerpt)
<?xml version='1.0' encoding='iso-8859-1' ?>
<xsl:stylesheet
        version='1.0'
        xmlns:xsl='http://www.w3.org/1999/XSL/Transform' >

        <xsl:param name='diagFolder' >./diags</xsl:param>
:        :
        <xsl:template
                match='img' >

                <img
                        src='{$diagFolder}/{@src}'
                        alt='{@alt}' />

        </xsl:template>
:        :
</xsl:stylesheet>
- - -

Che ne pensono?

Derek Harmon