Re: [Edocs-development] Use case XML language and figures

SourceForge Headquarters 1320 Columbia Street Suite 310 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.

Derek,

XML is just for our internal use.It's the support that we'll use to write
raw project documentation
and transform applying a uniform stylesheet to HTML documents formatted in a
uniform way.

The idea isn't that users read directly XML files with thier browsers but
that they read HTML.
This is valid also for us. That HTML is under the target\doc\ad directory
and is obtained after XSL processing
with an ant task. In the XSL file I've created some rules that are applied
to certain XML element that
gives the ability to format HTML in the outputted format (<section>,
<detview-section>, <detview-section-item>, etc).

Also when we'll have a binary distribution of our product we'll not include
the original XML files but
just HTML in it.

I've followed this method because is the same I'm using with certain Apache
project where I'm working on
and I think is good.

The problems in our case remains again where to live the master files of
every diagram in their native format (Visio).
I think we can create a separate module on the cvs and live them there.

>
>
> 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).

This could be useful when we'll build user manuals or other
type of documentation. In any case the language for project
documentation is only in english.

In any case a good idea is to introduce the xml:lang="en-US" and
encoding="iso-8859-1"
in the xml. I'll do it immediately.

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

Your idea is right. My main objective where to leave things related with
every single major area separated from the others. So from here I had the
idea to have a
separate diags directory.
If we prefer to have all the diagrams in one single place we need to change
the naming
convention adding at the beginning of the filename of it's own area name.
Ex:

security_UC_AI_1.png

I like the idea to "hide" the images location and put a reference in the
stylesheet to be used in XML. I think
we can do that. If there will be the necessity to use more stylesheet file
we can build a single xsl file
with some "configuration parameters" including it in every stylesheet that
we're going to use.

I would like to agree on these things asap to terminate very quicly the
analysis phase and begin to write some
line of code.

>
> 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? This is the right way to say what you were asking me ->
(Che cosa ne pensi?)

Ciao

Sergio