yekigoc / akomantoso Goto Github PK

Understanding the rationale in elements name may arise when reading the 
documentation about 
Akoma Ntoso. Here I expose (maybe for the first time) my understanding about 
the 
singular/plural distinction.

An element with a singular name contains data that can be associated to the 
concept behind the 
element's name. Thus it is the registration of an instance of that thing that 
is named by the 
element's name. 

On the other hand, an element with a plural name is ALWAYS a list of individual 
elements with a 
corresponding singular name. 

E.g.: 
<telephones> 
     <telephone/>
     <telephone/>
     <telephone/>
</telephones>

<employees> 
     <employee/>
     <employee/>
     <employee/>
</employees>



An exception to this rule is when the singular term reflects the name of a 
*subclass* of the class 
corresponding to the plural term. In this case it is still acceptable even 
though technically the 
singular is a singular of a different term than the plural: 

<telephones> 
     <cellphone/>
     <fax/>
     <landline/>
</telephones>

<employees> 
     <manager/>
     <worker/>
     <agent/>
</employees>

Thus the plural corresponds to a single term for the container of all types of 
singulars in their 
specificities. 

Understanding the rationale in elements name may arise when reading the 
documentation about 
Akoma Ntoso. Here I expose (maybe for the first time) my understanding about 
the issue of name 
length.

It is common wisdom that common names must be shorter than less-common names. 
That is, 
elements that you expect to use many many times should have a shorter name than 
elements that 
are used once or twice. 

In HTML, for instance, we use <p> instead of <paragraph>, <b> instead of <bold> 
and <i> 
instead of <italic>, but we use <meta http-request> instead of <m h>. 
Analogously, we should 
aim at choosing short names for frequent terms, and longer ones for less common 
ones. 

Some element names start with Capital letters while others don't.
Document the naming policy for elements in Akoma Ntoso, and the
significance of starting element names with capitals.

Currently the schema has the element "attachment" :

The attachment element refers to another AKOMA NTOSO document containing
the content of the attachment

and the element "Attachment" :

A reference to a document that is attached to the current document. 

Since both elements can appear in the same document, and both are
referenceType-s the name needs to be more clearly differentiated than the
current differentiation by Upper and LowerCase characters.

Understanding the rationale in elements name may arise when reading the 
documentation about 
Akoma Ntoso. Here I expose (maybe for the first time) my understanding about 
the 
use of cases in element names.

Although this situation is not as clear-cut as the plural/singular one, there 
is a basic approach 
designing element names: 

lowercase elements are concrete elements, that contain a specific instance of 
the concept 
represented by the name. 

Uppercase elements are abstract elements or generic elements, that contain 
either a 
representation of the concept itself (as opposed to a representation of an 
instance of the 
concept) or a generic element (i.e., an instance of a concept whose actual name 
does not exist in 
the schema and needs to be added in a generic way). 

Thus: <Block> is a generic term, FRBRWork is an abstraction, etc. 

This issue proposes a way to use the Google Code tool for correct and 
proficient use of its 
features. 

When dealing with issues, the labels and the other fields are as important as 
the description of 
the problem, as they allow to track the development of the story from its 
initial narration to its 
conclusion. 

When dealing with an issue, we should always remember the following steps:
1) The creator of the issue must specify "New" as status, as he is just 
creating it. He should also 
specify the owner (i.e., who is responsible for fixing the issue), and three 
types of labels: the 
type, the priority and the component, from the selected list of values. Issues 
that do not require 
actions (such as this message) need to have "Stable" as status and never 
change. 

2) The owner of the issue is notified by mail of the existence of the new 
issue, and upon 
checking it into GoogleCode he/she MUST change the status to either "Received" 
(if the issue has 
been read but no action has been taken) or "Started" if the issue has been 
considered and fixes 
are being done, or close the issue with an appropriate Status selection (Fixed, 
Invalid, Duplicate, 
WonTFix). 

3) The submitter of the issue is then notified via mail of the completion of 
the issue, and needs to 
respond to it with a "Verified" status if the issue has been satisfyingly dealt 
with, or "Reopen" 
otherwise. 

4) No actions should be taken  by the owner on issues that haven't been 
reopened. 

Current values for the Labels field in the application Google Code are prefixed 
by categories, 
which are: 

Type: defect, enhancement, task, patch, other
Priority: Critical, High, Medium, Low
OpSys: Windows, Linux, OSX, All
Component: blah blah
and others. 

If it is possible in this applications, these values should be changed: Here is 
a list of possible 
values: 

Type: Bug, enhancement, suggestion, documentation, other
Priority: GeneratesANewRelease, AtTheNextRelease, OpenForDiscussion, 
SoonerOrLater
Component: AkomaNtoso, NamingConvention, BungeniWorkflow, BungeniEditor, 
NormaEditor, 
Thesaurus, TrackingSystem

Of course more values can be added, if we agree on their meaning. 

During a certain point of the debate the Speaker of the assembly can say
that the "Declaration of vote" may begin and then each party/group is
allowed to make a statement about the items to be voted on. 

So, it could be something like question and speech, we first have an
identifying container for "voteDeclaration" that carries information about
what is the topic/object of the declaration and then there are
sub-containers for the party/MPvoteDeclaration (like speeches, but with
references to "groups" rather than to "persons" ) 

AKOMA NTOSO, I am quoting, aims <<to be “self-explanatory”, that is to be
able to provide all information for their use and meaning through a simple
examination>>


How do we deal with "descriptiveness" in non English contexts?

Needless to say that issue about maintenance and cost for possible adaption
of tools should be carefully considered.

Thanks

Flavio

The Google Code interface for reporting an issue has a field called "Status". 

For reasons unknown, by default the value in the "Status" field is "accepted". 
Unfortunately, the 
keyword "accepted" is used to refer to the situation in which the owner of the 
issue *recognizes* 
from the submitter the existence of the new issue and *accepts* it. 

Submitters should always use the keyword "New" when creating a new issue. 
Possibly, the keyword 
"New" should be specified as the default value for the Status field in the 
settings of the application, 
which I do not have access to. 

The differences in usage of <heading> and <title> needs to be documented.
How is <heading> different from <title> ?

The container element <body> can be confused with the xhtml "body" element,
as Akoma Ntoso uses certain XHTML elements (but not <body>). 

It is suggested that the element be renamed to <ActBody> or similar

It has been suggested by Monica (skype conversation) that although the element 
<uri> allows for 
the expression of the URI of the whole work, expression and manifestation the 
document belongs 
to, there is no such provision for the URI of the actual document. 

For instance, nowhere an attachment reports its own URI, but just the one of 
the document it 
belongs to. 

For this reason, a new element is proposed, <this> that has syntax identical to 
<uri>, but specifies 
the URI of to the specific document it is used by, and not the whole Work, 
Expression or 
Manifestation it belongs to.  

It is important that Monica is given access to the tickets being discussed in 
this application. 

Please add her to the list of users. 

Dear Fabio, 
I think that there is a little issue with the last release of AKOMA NTOSO 
-05/05/2009-.
In all the previous releases, the "mainContent" element could hold all the 
hierarchies of all the 
document's types (because it is the body of the document that have an open 
structure).
This not happen in the last release . Is it an error or are there some 
motivations for this change? 

Thank you very much. 

I ask to include in the element FRBRexpression/component the attribute @type.

The Attachment and AttachmentOf in the Reference block have the attribute
@type, but because these elements are used NOW ONLY for the external
schedules (external to the manifestation) we have lost the place where to
define the type of schedules (act, annex, informative) in the current
manifestation.

A top-level-class element TLCConcept introduced with the most recent Akoma
Ntoso release neeeds to be documented better.  What would be its usage ?

Prior discussion indicated that "MultipleVersions" could not be supported
in a real scenario. It was suggested that this particular version type be
removed.

"MultipleVersions: this value reflects the fact that the content of the
document is the juxtaposition of fragments belonging to two or more
different versions of the same act, each fragment marked as belonging to
one or many of these versions. Thus in a MultipleVersions act there could
be two or more copies of article 2, each associated to the date it started
enactment and ended enactment."


<xsd:simpleType name="VersionType"  >
    <xsd:restriction base="xsd:string">
        <xsd:enumeration value="OriginalVersion" />
        <xsd:enumeration value="SingleVersion" />
        <xsd:enumeration value="MultipleVersions" />
    </xsd:restriction>
</xsd:simpleType>