[Community] Comments on PrimaGIS 0.5 manual

[Kai Hänninen]

Thanks Yves for your thorough review of the user manual. I will reply to
the parts that I felt the need to comment, the parts not commented I
implemented as they were.


ke, 2005-12-14 kello 16:55 -0500, Moisan Yves kirjoitti:
> Hi Kai,
> Hi all,
> 
> Great initiative Kai!  It's a weird PDF doc though (text is not really
> selectable so it's a big image ??).  Anyhow, rushing thru my comments :

Yes, I only noticed this after you mentioned it in IRC. I've been using
two different approaches in creating the PDF version.

  LaTeX -> DVI -> PostScript -> PDF

which makes the un-selectable PDF and

  LaTeX -> PDF (using pdflatex)

which makes the text selectable. Unfortunately the version of pdflatex
I'm using has trouble getting all the figures correctly. I will need to
solve this before the final version.

[...]

> - sect 2.3.1 : It is a container (folderish); "containerish" doesn't
> sound too English; I would replace with folderish everywhere in the
> text;

I've seen the term "containerish" used in recent projects and chose to
use it. I guess this a mostly a matter of preference (I prefer
"container" over "folder"), but the term itself is not something I
invented myself.

> one thing you don't mention anywhere in the doc is how to manage
> transparency (but I guess that's more a ZCO manual duty to do)

Transparency in what context? Transparent map backgrounds are mentioned
in the PrimaGISMap object's configuration section.

[...]

> OT : I wonder if it would be useful to also have ZCOImage and ZCOIcon
> objects (even if an icon is just an image with constraint on size, for
> example); that would make it clearer what can be used as a symbolizer

I disagree on the need for explicit ZCOImage or ZCOIcon types.
Currently, AFAIK, any Zope Image will do. It's up to the Manager that
the image has reasonable size etc. In the future, when PrimaGIS possibly
manages the underlying ZCO transparently, we can implement constraints
on the images if need be.

[...]

> 
> - sect 4.3.3 : Zope Instances Products is the location for ZCO and
> Plone/Products is for PrimaGIS (in win 32 systems at least; no symlinks
> here)

I guess this is matter of convention/preference. I've got all my
products under the Zope instance's Products directory, including both
ZCO and PrimaGIS (and also Plone itself). It is naturally easy to use
multiple separate locations for Products.

[...]

> - sect 5.1.2 :  PROXY_SUBJECT_TYPE : somewhere else in the text
> DummyContent is presented as an option; do I understand it isn't (needed
> for PROXY_SUBJECT_TYPE ?); FONTSET_FILE : last sentence is repetition

DummyContent has caused a lot of confusion I guess. It is optional and
you should only use it if you don't have *any* other AT content types
available on your system (or you wish to run the PrimaGIS unit tests).
For Plone 2.1 users it is completely redundant and unnecessary. I will
change the default for PROXY_SUBJECT_TYPE to be "Document" in the 0.5
release and add a note to Plone 2.0 users that they may need to use
DummyContent instead. Hopefully this will clarify things.


> Page 19
> The figure doesn't add to the text IMO

Are you referring to the location of the figure? As you probably know,
LaTeX can take some liberties in positioning (floating) the figures
within the document unless told explicitly not to do so. As long as the
relevant parts in the text properly refer to the figures, I don't see
this as a big issue.

[...]

> Sect 7.2 : Example values "zco" isn,t the best example

Agreed, it is not the best example. The demo map does use it though, so
that's why I included it.


> Sect 11 (combine this section with 8 ??); sect 11.1 would becomce a 8.x
> section with title = IGeoAware interface : methods with 11.2 becoming
> IGeoAware interface : : inheriting from GeoAwareMixin and 11.3 IGeoAware
> interface : Building from scratch
> 
> Sect 11.2.x : factor out the boilerplate of all subsections : "Appending
> whatever schema to your Archetypes based ..." in 11.2

Agreed, that this needs to be done. I will go through the sections over
the weekend and try to re-arrange them. I would like to keep the pure
development stuff at the end of the document though.


Thanks again for your help!

cheers,
Kai

-- 
Kai Hänninen                  mobile:+358-44-541 9567
Software engineer             www.mbconcert.fi
MB Concert Ky                 kai.hanninen at mbconcert.fi