Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Merge pull request #39 from aejh/master

Document tidy up
  • Loading branch information...
commit b585c99070d5e8db6d10a448e8c8b828d40ae9a9 2 parents aceb0ba + 3b03fe3
Arjan Molenaar authored
1  doc/.gitignore
... ... @@ -0,0 +1 @@
  1 +_build/
130 doc/Makefile
... ... @@ -0,0 +1,130 @@
  1 +# Makefile for Sphinx documentation
  2 +#
  3 +
  4 +# You can set these variables from the command line.
  5 +SPHINXOPTS =
  6 +SPHINXBUILD = sphinx-build
  7 +PAPER =
  8 +BUILDDIR = _build
  9 +
  10 +# Internal variables.
  11 +PAPEROPT_a4 = -D latex_paper_size=a4
  12 +PAPEROPT_letter = -D latex_paper_size=letter
  13 +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
  14 +
  15 +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
  16 +
  17 +help:
  18 + @echo "Please use \`make <target>' where <target> is one of"
  19 + @echo " html to make standalone HTML files"
  20 + @echo " dirhtml to make HTML files named index.html in directories"
  21 + @echo " singlehtml to make a single large HTML file"
  22 + @echo " pickle to make pickle files"
  23 + @echo " json to make JSON files"
  24 + @echo " htmlhelp to make HTML files and a HTML help project"
  25 + @echo " qthelp to make HTML files and a qthelp project"
  26 + @echo " devhelp to make HTML files and a Devhelp project"
  27 + @echo " epub to make an epub"
  28 + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
  29 + @echo " latexpdf to make LaTeX files and run them through pdflatex"
  30 + @echo " text to make text files"
  31 + @echo " man to make manual pages"
  32 + @echo " changes to make an overview of all changed/added/deprecated items"
  33 + @echo " linkcheck to check all external links for integrity"
  34 + @echo " doctest to run all doctests embedded in the documentation (if enabled)"
  35 +
  36 +clean:
  37 + -rm -rf $(BUILDDIR)/*
  38 +
  39 +html:
  40 + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
  41 + @echo
  42 + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
  43 +
  44 +dirhtml:
  45 + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
  46 + @echo
  47 + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
  48 +
  49 +singlehtml:
  50 + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
  51 + @echo
  52 + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
  53 +
  54 +pickle:
  55 + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
  56 + @echo
  57 + @echo "Build finished; now you can process the pickle files."
  58 +
  59 +json:
  60 + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
  61 + @echo
  62 + @echo "Build finished; now you can process the JSON files."
  63 +
  64 +htmlhelp:
  65 + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
  66 + @echo
  67 + @echo "Build finished; now you can run HTML Help Workshop with the" \
  68 + ".hhp project file in $(BUILDDIR)/htmlhelp."
  69 +
  70 +qthelp:
  71 + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
  72 + @echo
  73 + @echo "Build finished; now you can run "qcollectiongenerator" with the" \
  74 + ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
  75 + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Gaphor.qhcp"
  76 + @echo "To view the help file:"
  77 + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Gaphor.qhc"
  78 +
  79 +devhelp:
  80 + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
  81 + @echo
  82 + @echo "Build finished."
  83 + @echo "To view the help file:"
  84 + @echo "# mkdir -p $$HOME/.local/share/devhelp/Gaphor"
  85 + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Gaphor"
  86 + @echo "# devhelp"
  87 +
  88 +epub:
  89 + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
  90 + @echo
  91 + @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
  92 +
  93 +latex:
  94 + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
  95 + @echo
  96 + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
  97 + @echo "Run \`make' in that directory to run these through (pdf)latex" \
  98 + "(use \`make latexpdf' here to do that automatically)."
  99 +
  100 +latexpdf:
  101 + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
  102 + @echo "Running LaTeX files through pdflatex..."
  103 + make -C $(BUILDDIR)/latex all-pdf
  104 + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
  105 +
  106 +text:
  107 + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
  108 + @echo
  109 + @echo "Build finished. The text files are in $(BUILDDIR)/text."
  110 +
  111 +man:
  112 + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
  113 + @echo
  114 + @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
  115 +
  116 +changes:
  117 + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
  118 + @echo
  119 + @echo "The overview file is in $(BUILDDIR)/changes."
  120 +
  121 +linkcheck:
  122 + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
  123 + @echo
  124 + @echo "Link check complete; look for any errors in the above output " \
  125 + "or in $(BUILDDIR)/linkcheck/output.txt."
  126 +
  127 +doctest:
  128 + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
  129 + @echo "Testing of doctests in the sources finished, look at the " \
  130 + "results in $(BUILDDIR)/doctest/output.txt."
28 doc/actions.txt
@@ -22,10 +22,11 @@ Where it should lead:
22 22
23 23 * Actions should behave more like adapters. E.g. when a popup menu is created
24 24 for an Association item, the menu actions should present themselves in the
25   - context of that menu item (with toggles set right)
  25 + context of that menu item (with toggles set right).
  26 +
26 27 - Could be registered as adapters with a name.
27 28
28   - * Each window has it's own action group (every item with a menu?)
  29 + * Each window has its own action group (every item with a menu?)
29 30 * One toplevel UIManager per window or one per application/gui_manager?
30 31 * Normal actions can be modeled as functions. If an action is sensitive or
31 32 visible depends on the state in the action. Hence we require the update()
@@ -45,7 +46,7 @@ Hence an interface IActionProvider has to be defined::
45 46 menu_xml = interface.Attribute("The menu XML")
46 47 action_group = interface.Attribute("The accompanying ActionGroup")
47 48
48   -Support for actions can be arranged by decorating actions with an @action
  49 +Support for actions can be arranged by decorating actions with an :ref:`@action <action_doc>`
49 50 decorator and let the class create an ActionGroup using some
50 51 actionGroup factory function (no inheritance needed here).
51 52
@@ -57,11 +58,21 @@ They can register handlers in order to update their state.
57 58
58 59 Maybe it's nice to configure those through the egg-info system. I suppose
59 60 gaphor.service will serve well (as they need to be initialized anyway)
60   - ==> also inherit IActionProvider from IService?
  61 +
  62 + * also inherit IActionProvider from IService?
  63 +
  64 +::
61 65
62 66 [gaphor.services]
63 67 xx = gaphor.actions.whatever:SomeActionProviderClass
64 68
  69 +----
  70 +
  71 +.. _action_doc:
  72 +
  73 +.. autoclass:: gaphor.action.action
  74 + :members:
  75 +
65 76
66 77 Solution for context sensitive menus
67 78 ------------------------------------
@@ -71,18 +82,19 @@ on and off on demand.
71 82
72 83 Technically they should be enabled through services/action-providers.
73 84
74   -It becomes even tougher when popup menu's should act on parts of a diagram item
  85 +It becomes even tougher when popup menus should act on parts of a diagram item
75 86 (such as association ends). This should be avoided. It may be a good idea to
76 87 provide such functionality through a special layer on the canvas, by means of
77 88 some easy clickable buttons around the "hot spot" (we already have something
78 89 like that for text around association ends).
79 90
80 91 Scheme:
  92 +
81 93 1. User selects an item and presses the rigth mouse button: a popup menu
82 94 should be displayed.
83   -2. find the actual item (this may be a composite item of the element drawn).
  95 +2. Find the actual item (this may be a composite item of the element drawn).
84 96 Use an IItemPicker adapter for that (if no such interface is available,
85 97 use the item itself).
86   -2. Find a IActionProvider adapters for the selected (focused) item.
87   -3. update the popup menu context (actions) for the selected item.
  98 +3. Find a IActionProvider adapters for the selected (focused) item.
  99 +4. Update the popup menu context (actions) for the selected item.
88 100
217 doc/conf.py
... ... @@ -1,8 +1,213 @@
1   -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo']
2   -project = 'Gaphor'
3   -version = '0.15'
4   -release = version
  1 +# -*- coding: utf-8 -*-
  2 +#
  3 +# This file is execfile()d with the current directory set to its containing dir.
  4 +#
  5 +# Note that not all possible configuration values are present in this
  6 +# autogenerated file.
  7 +#
  8 +# All configuration values have a default; values that are commented out
  9 +# serve to show the default.
  10 +
  11 +import sys, os
  12 +
  13 +# If extensions (or modules to document with autodoc) are in another directory,
  14 +# add these directories to sys.path here. If the directory is relative to the
  15 +# documentation root, use os.path.abspath to make it absolute, like shown here.
  16 +#sys.path.insert(0, os.path.abspath('.'))
  17 +
  18 +# -- General configuration -----------------------------------------------------
  19 +
  20 +# If your documentation needs a minimal Sphinx version, state it here.
  21 +#needs_sphinx = '1.0'
  22 +
  23 +# Add any Sphinx extension module names here, as strings. They can be extensions
  24 +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
  25 +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', 'sphinx.ext.coverage']
  26 +
  27 +# Add any paths that contain templates here, relative to this directory.
  28 +templates_path = ['_templates']
  29 +
  30 +# The suffix of source filenames.
5 31 source_suffix = '.txt'
  32 +
  33 +# The encoding of source files.
  34 +#source_encoding = 'utf-8-sig'
  35 +
  36 +# The master toctree document.
6 37 master_doc = 'contents'
7   -#html_theme = 'traditional'
8   -#unused_docs = 'constraints.txt index.txt tools.txt comparison.txt'
  38 +
  39 +# General information about the project.
  40 +project = u'Gaphor'
  41 +copyright = u'2012, Gaphor development team'
  42 +
  43 +# The version info for the project you're documenting, acts as replacement for
  44 +# |version| and |release|, also used in various other places throughout the
  45 +# built documents.
  46 +#
  47 +# The short X.Y version.
  48 +version = '0.17.1'
  49 +# The full version, including alpha/beta/rc tags.
  50 +release = '0.17.1'
  51 +
  52 +# The language for content autogenerated by Sphinx. Refer to documentation
  53 +# for a list of supported languages.
  54 +#language = None
  55 +
  56 +# There are two options for replacing |today|: either, you set today to some
  57 +# non-false value, then it is used:
  58 +#today = ''
  59 +# Else, today_fmt is used as the format for a strftime call.
  60 +#today_fmt = '%B %d, %Y'
  61 +
  62 +# List of patterns, relative to source directory, that match files and
  63 +# directories to ignore when looking for source files.
  64 +exclude_patterns = ['_build']
  65 +
  66 +# The reST default role (used for this markup: `text`) to use for all documents.
  67 +#default_role = None
  68 +
  69 +# If true, '()' will be appended to :func: etc. cross-reference text.
  70 +#add_function_parentheses = True
  71 +
  72 +# If true, the current module name will be prepended to all description
  73 +# unit titles (such as .. function::).
  74 +#add_module_names = True
  75 +
  76 +# If true, sectionauthor and moduleauthor directives will be shown in the
  77 +# output. They are ignored by default.
  78 +#show_authors = False
  79 +
  80 +# The name of the Pygments (syntax highlighting) style to use.
  81 +pygments_style = 'sphinx'
  82 +
  83 +# A list of ignored prefixes for module index sorting.
  84 +#modindex_common_prefix = []
  85 +
  86 +
  87 +# -- Options for HTML output ---------------------------------------------------
  88 +
  89 +# The theme to use for HTML and HTML Help pages. See the documentation for
  90 +# a list of builtin themes.
  91 +html_theme = 'default'
  92 +
  93 +# Theme options are theme-specific and customize the look and feel of a theme
  94 +# further. For a list of options available for each theme, see the
  95 +# documentation.
  96 +#html_theme_options = {}
  97 +
  98 +# Add any paths that contain custom themes here, relative to this directory.
  99 +#html_theme_path = []
  100 +
  101 +# The name for this set of Sphinx documents. If None, it defaults to
  102 +# "<project> v<release> documentation".
  103 +#html_title = None
  104 +
  105 +# A shorter title for the navigation bar. Default is the same as html_title.
  106 +#html_short_title = None
  107 +
  108 +# The name of an image file (relative to this directory) to place at the top
  109 +# of the sidebar.
  110 +#html_logo = None
  111 +
  112 +# The name of an image file (within the static path) to use as favicon of the
  113 +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
  114 +# pixels large.
  115 +#html_favicon = None
  116 +
  117 +# Add any paths that contain custom static files (such as style sheets) here,
  118 +# relative to this directory. They are copied after the builtin static files,
  119 +# so a file named "default.css" will overwrite the builtin "default.css".
  120 +html_static_path = ['_static']
  121 +
  122 +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
  123 +# using the given strftime format.
  124 +#html_last_updated_fmt = '%b %d, %Y'
  125 +
  126 +# If true, SmartyPants will be used to convert quotes and dashes to
  127 +# typographically correct entities.
  128 +#html_use_smartypants = True
  129 +
  130 +# Custom sidebar templates, maps document names to template names.
  131 +#html_sidebars = {}
  132 +
  133 +# Additional templates that should be rendered to pages, maps page names to
  134 +# template names.
  135 +#html_additional_pages = {}
  136 +
  137 +# If false, no module index is generated.
  138 +#html_domain_indices = True
  139 +
  140 +# If false, no index is generated.
  141 +#html_use_index = True
  142 +
  143 +# If true, the index is split into individual pages for each letter.
  144 +#html_split_index = False
  145 +
  146 +# If true, links to the reST sources are added to the pages.
  147 +#html_show_sourcelink = True
  148 +
  149 +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
  150 +#html_show_sphinx = True
  151 +
  152 +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
  153 +#html_show_copyright = True
  154 +
  155 +# If true, an OpenSearch description file will be output, and all pages will
  156 +# contain a <link> tag referring to it. The value of this option must be the
  157 +# base URL from which the finished HTML is served.
  158 +#html_use_opensearch = ''
  159 +
  160 +# This is the file name suffix for HTML files (e.g. ".xhtml").
  161 +#html_file_suffix = None
  162 +
  163 +# Output file base name for HTML help builder.
  164 +htmlhelp_basename = 'Gaphordoc'
  165 +
  166 +
  167 +# -- Options for LaTeX output --------------------------------------------------
  168 +
  169 +# The paper size ('letter' or 'a4').
  170 +#latex_paper_size = 'letter'
  171 +
  172 +# The font size ('10pt', '11pt' or '12pt').
  173 +#latex_font_size = '10pt'
  174 +
  175 +# Grouping the document tree into LaTeX files. List of tuples
  176 +# (source start file, target name, title, author, documentclass [howto/manual]).
  177 +latex_documents = [
  178 + ('contents', 'Gaphor.tex', u'Gaphor Documentation',
  179 + u'Gaphor development team', 'manual'),
  180 +]
  181 +
  182 +# The name of an image file (relative to this directory) to place at the top of
  183 +# the title page.
  184 +#latex_logo = None
  185 +
  186 +# For "manual" documents, if this is true, then toplevel headings are parts,
  187 +# not chapters.
  188 +#latex_use_parts = False
  189 +
  190 +# If true, show page references after internal links.
  191 +#latex_show_pagerefs = False
  192 +
  193 +# If true, show URL addresses after external links.
  194 +#latex_show_urls = False
  195 +
  196 +# Additional stuff for the LaTeX preamble.
  197 +#latex_preamble = ''
  198 +
  199 +# Documents to append as an appendix to all manuals.
  200 +#latex_appendices = []
  201 +
  202 +# If false, no module index is generated.
  203 +#latex_domain_indices = True
  204 +
  205 +
  206 +# -- Options for manual page output --------------------------------------------
  207 +
  208 +# One entry per manual page. List of tuples
  209 +# (source start file, name, description, authors, manual section).
  210 +man_pages = [
  211 + ('contents', 'gaphor', u'Gaphor Documentation',
  212 + [u'Gaphor development team'], 1)
  213 +]
39 doc/connect.txt
... ... @@ -1,10 +1,12 @@
1 1 Connection protocol
2 2 ===================
3 3
4   -In Gaphor, if a connection is made on a diagram between an element and a relationship, the connection is also made at semantic level (the model). From a GUI
5   -point of view it all starts with a button release event:
  4 +In Gaphor, if a connection is made on a diagram between an element and a
  5 +relationship, the connection is also made at semantic level (the model).
  6 +From a GUI point of view it all starts with a button release event.
6 7
7   -With "item" I refer to objects in a diagram (graphical), with "element" I refer to symantic (model) objects.
  8 +With "item" I refer to objects in a diagram (graphical), with "element" I
  9 +refer to symantic (model) objects.
8 10
9 11 Is relation with this element allowed?
10 12 No:
@@ -13,22 +15,27 @@ Is relation with this element allowed?
13 15 Yes:
14 16 connect_handle()
15 17 Is opposite end connected?
  18 +
16 19 No:
17 20 Do nothing
18 21 Yes:
19   - Does the item already have a subject element relation?
20   - Yes:
21   - Is the previous item the same as the current?
22   - Yes:
23   - Do nothing
24   - No:
25   - Let subject end point to the new element
26   - No:
  22 + Does the item already have a subject element relation?
  23 + Yes:
  24 + Is the previous item the same as the current?
  25 + Yes:
  26 + Do nothing
  27 +
  28 + No:
  29 + Let subject end point to the new element
  30 +
  31 + No:
27 32 Create relation or find existing relation in model
28   - Search for an existing relation in the model:
29   - Found:
30   - Use that relation
31   - Nothing:
32   - Create new model elements and connect to item
  33 +
  34 + Search for an existing relation in the model:
  35 + Found:
  36 + Use that relation
  37 + Nothing:
  38 +
  39 + Create new model elements and connect to item
33 40
34 41 The check if a connection is allowed should also check if it is valid to create a relation to/from the same element (like associations, but not generalizations)
25 doc/contents.txt
@@ -2,17 +2,16 @@
2 2 Documentation contents
3 3 ######################
4 4
5   -
6 5 *The source is the documentation.*
7 6
8 7 Well, not for us.
9 8
10   -Currently, there's not a lot of documentation though. For those of you interested in Gaphor there's
  9 +Currently, there's not a lot of documentation though. For those of you interested in Gaphor there's:
11 10
12 11 * A :doc:`manual <manual/index>`. It outlines some of the ideas in and behind Gaphor.
13 12 * The :ref:`tech-section` contains some interesting articles about the technology that drives Gaphor and Gaphas, Gaphor's canvas widget.
14 13
15   -If you're into writing plug-ins for Gaphor you should have a look at our fabulous :url:`Hello world <http://github.com/amolenaar/gaphor.plugins.helloworld>` plug-in.
  14 +If you're into writing plug-ins for Gaphor you should have a look at our fabulous `Hello world <http://github.com/amolenaar/gaphor.plugins.helloworld>`_ plug-in.
16 15
17 16 .. toctree::
18 17 :maxdepth: 2
@@ -22,11 +21,12 @@ If you're into writing plug-ins for Gaphor you should have a look at our fabulou
22 21 Running Gaphor on different platforms:
23 22
24 23 .. toctree::
25   - :maxdepth: 2
  24 + :maxdepth: 1
26 25
27   - custominstall
28 26 linux
29 27 win32
  28 + custominstall
  29 +
30 30
31 31 .. _tech-section:
32 32
@@ -34,24 +34,29 @@ Tech section
34 34 ------------
35 35
36 36 .. toctree::
37   - :maxdepth: 2
  37 + :maxdepth: 1
38 38
39   - model
40 39 framework
41   - actions
42   - connect
  40 + model
  41 + stereotypes
43 42 datamodel
  43 + connect
  44 + actions
  45 + items
44 46 services
45 47 so
46 48 storage
47 49 undo
48 50 xml-format
49   -
  51 +
  52 +.. toctree::
  53 + :maxdepth: 2
50 54
51 55 External links
52 56 ^^^^^^^^^^^^^^
53 57
54 58 * You should definitely check out http://www.agilemodeling.com.
  59 +
55 60 * The `UML diagrams <http://www.agilemodeling.com/essays/umlDiagrams.htm>`_ (although Gaphor does not see it that black-and-white).
56 61 * http://www.agilemodeling.com/essays/
57 62 * The `official UML metamodel specification <http://www.omg.org/technology/documents/modeling_spec_catalog.htm#UML>`_. This ''is'' our data model.
104 doc/datamodel.txt
... ... @@ -1,49 +1,81 @@
1   -= Description of Gaphors data model =
  1 +Description of Gaphors data model
  2 +=================================
2 3
3   -Gaphor is an UML tool. In order to keep as close as possible to the UML specification the data model is based on the UML Metamodel. Since the OMG has an XMI (XML) specification of the metamodel, the easiest way to do that is to generate the code directly from the model. Doing this raises two issues:
  4 +Gaphor is an UML tool. In order to keep as close as possible to the UML
  5 +specification the data model is based on the UML Metamodel. Since the OMG has
  6 +an XMI (XML) specification of the metamodel, the easiest way to do that is to
  7 +generate the code directly from the model. Doing this raises two issues:
4 8
5 9 1. There are more attributes defined in the data model than we will use.
6 10 2. How do we check if the model is consistent?
7 11
8 12 The first point is not such a problem: attributes we don't use don't consume memory.
9 13
10   -There are no consistency rules in the XML definition, we have to get them from the UML syntax description. It is probably best to create a special consistency module that checks the model and reports errors.
11   -
12   -In the UML metamodel all classes are derived from {{{Element}}}. So all we have to do is create a substitute for {{{Element}}} that gives some behaviour to the data objects (see {{{gaphor/UML/element.py}}}).
13   -
14   -The data model is described in Python. Since the Python language doesn't make a difference between classes and objects, we can define the possible attributes that an object of a particular kind can have in a dictionary (name-value map) at class level. If a value is set, the object checks if an attribute exists in the class' dictionary (and the parents dictionary). If it does, the value is assigned, if it doesn't an exception is raised.
15   -
16   -== Bidirectional references ==
17   -
18   -But how, you might wonder, do you handle bidirectional references (object one references object two and visa versa)? Well, this is basically the same as the uni-directional reference. Only now we need to add some extra information to the dictionary at class level. We just define and extra field that gives us the name of the opposite reference and viola, we can create bi-directional references. You should check out the code in {{{gaphor/UML/element.py}}} for more details.
19   -
20   -== Implementation ==
21   -
22   -This will allow the user to assign a value to an instance of {{{Element}}} with name '{{{name}}}'. If no value is assigned before the value is requested, it returns and empty string ''.
23   -
24   -{{{
25   -m = Class()
26   -print m.name # Returns ''
27   -m.name = 'MyName'
28   -print m.name # Returns 'MyName'
29   -}}}
  14 +There are no consistency rules in the XML definition, we have to get them from
  15 +the UML syntax description. It is probably best to create a special consistency
  16 +module that checks the model and reports errors.
  17 +
  18 +In the UML metamodel all classes are derived from :ref:`Element <uml_element>`. So all we have
  19 +to do is create a substitute for :ref:`Element <uml_element>` that gives some behaviour to the
  20 +data objects.
  21 +
  22 +The data model is described in Python. Since the Python language doesn't make
  23 +a difference between classes and objects, we can define the possible
  24 +attributes that an object of a particular kind can have in a dictionary
  25 +(name-value map) at class level. If a value is set, the object checks if an
  26 +attribute exists in the class' dictionary (and the parents dictionary). If it
  27 +does, the value is assigned, if it doesn't an exception is raised.
  28 +
  29 +Bidirectional references
  30 +------------------------
  31 +
  32 +But how, you might wonder, do you handle bidirectional references (object one
  33 +references object two and visa versa)? Well, this is basically the same as the
  34 +uni-directional reference. Only now we need to add some extra information to
  35 +the dictionary at class level. We just define and extra field that gives us
  36 +the name of the opposite reference and viola, we can create bi-directional
  37 +references. You should check out the code in ``gaphor/UML/element.py`` for more details.
  38 +
  39 +Implementation
  40 +--------------
  41 +
  42 +This will allow the user to assign a value to an instance of ``Element`` with
  43 +name ``name``. If no value is assigned before the value is requested, it
  44 +returns and empty string ''::
  45 +
  46 + m = Class()
  47 + print m.name # Returns ''
  48 + m.name = 'MyName'
  49 + print m.name # Returns 'MyName'
  50 +
  51 + m = Element()
  52 + c = Comment()
  53 + print m.comment # Returns an empty list '[]'
  54 + print c.annotatedElement # Returns an empty list '[]'
  55 + m.comment = c # Add 'c' to 'm.comment' and add 'm' to 'c.annotatedElement'
  56 + print m.comment # Returns a list '[c]'
  57 + print c.annotatedElement # Returns a list '[m]'
  58 +
  59 +All this wisdom is defined in the data-models base class: ``Element``.
  60 +The datamodel itself code is generated.
30 61
  62 +Extensions to the data model
  63 +----------------------------
31 64
32   -{{{
33   -m = Element()
34   -c = Comment()
35   -print m.comment # Returns an empty list '[]'
36   -print c.annotatedElement # Returns an empty list '[]'
37   -m.comment = c # Add 'c' to 'm.comment' and
38   - # add 'm' to 'c.annotatedElement'
39   -print m.comment # Returns a list '[c]'
40   -print c.annotatedElement # Returns a list '[m]'
41   -}}}
  65 +A few changes have been made to Gaphors implementation of the metamodel. First
  66 +of all some relationships have to be modified since the same name is used for
  67 +different relationships. Some n:m relationships have been made 1:n. These are
  68 +all small changed and should not restrict the usability of Gaphors model.
42 69
43   -All this wisdom is defined in the data-models base class: {{{Element}}}. The datamodel itself code is generated.
44   -Extensions to the data model
  70 +The biggest change is the addition of a whole new class: Diagram. Diagram is
  71 +inherited from Namespace and is used to hold a diagram. It contains a
  72 +``gaphas.canvas.Canvas`` object which can be displayed on screen by a
  73 +``DiagramView`` class.
45 74
46   -A few changes have been made to Gaphors implementation of the metamodel. First of all some relationships have to be modified since the same name is used for different relationships. Some n:m relationships have been made 1:n. These are all small changed and should not restrict the usability of Gaphors model.
  75 +.. _uml_element:
47 76
48   -The biggest change is the addition of a whole new class: Diagram. Diagram is inherited from Namespace and is used to hold a diagram. It contains a {{{gaphas.canvas.Canvas}}} object which can be displayed on screen by a {{{DiagramView}}} class.
  77 +UML.Element
  78 +-----------
  79 +.. autoclass:: gaphor.UML.element.Element
  80 + :members:
49 81
25 doc/epydoc.conf
... ... @@ -1,25 +0,0 @@
1   -[epydoc]
2   -
3   -name: Documentation Index
4   -url: ./index.html
5   -modules: gaphor
6   -verbosity: 1
7   -
8   -# Extraction
9   -docformat: restructuredtext
10   -parse: yes
11   -introspect: yes
12   -#exclude: .*\.tests.*
13   -inheritance: listed
14   -private: no
15   -imports: no
16   -include-log: no
17   -
18   -# HTML output
19   -output: html
20   -target: doc/html/
21   -#css: doc/style/epydoc.css
22   -top: gaphor
23   -frames: no
24   -sourcecode: no
25   -
44 doc/framework.txt
... ... @@ -1,7 +1,10 @@
1 1 Gaphor's Framework
2 2 ==================
3 3
4   -Gaphor is built in a light, service oriented fashion. The application is split in a series of services, such as a file manager, undo manager and GUI manager. Those services are loaded based on entry points defined in Python Eggs (see :doc:`Service oriented design <so>`).
  4 +Gaphor is built in a light, service oriented fashion. The application is split
  5 +in a series of services, such as a file manager, undo manager and GUI manager.
  6 +Those services are loaded based on entry points defined in Python Eggs
  7 +(see :doc:`Service oriented design <so>`).
5 8
6 9 Objects communicate with each other through events. Whenever something of
7 10 importance happens (e.g. an attribute of a model element changes) an event is
@@ -13,27 +16,48 @@ in (so the diagram item should check if the element that sent the event is
13 16 actually the event the item is representing).
14 17
15 18
16   -Gaphor is transactional. Transactions work simply by sending an event when a transaction starts and sending another when a transaction ends. E.g. undo management is transactional.
  19 +Gaphor is transactional. Transactions work simply by sending an event when a
  20 +transaction starts and sending another when a transaction ends. E.g. undo
  21 +management is transactional.
17 22
18   -It all starts with an Application. Only one Application instance is permitted. The Application will look for services defined as `[gaphor.services]`. Those services are loaded and initialized.
  23 +It all starts with an Application. Only one Application instance is permitted.
  24 +The Application will look for services defined as :doc:`gaphor.services
  25 +<services>`. Those services are loaded and initialized.
19 26
20 27 The most notable services are:
21 28
22 29 gui_manager
23   - For the Gaphor the GUI manager is one of the major services that have to be loaded. The GUI manager is responsible for loading the main window and displaying it on the screen.
  30 + The GUI manager is one of the major services that have to be loaded. The
  31 + GUI manager is responsible for loading the main window and displaying it
  32 + on the screen.
24 33
25   - This by itself doesn't do a thing though. The Action manager (`action_manager`) is required to maintain all actions users can perform. Actions will be shown as menu entries for example.
  34 + This by itself doesn't do a thing though. The Action manager
  35 + (`action_manager`) is required to maintain all actions users can perform.
  36 + Actions will be shown as menu entries for example.
26 37
27 38 file_manager
28 39 Loading and saving a model is done through this service.
29 40
30 41 element_factory
31   - The data model itself is maintained in the element factory. This service is used to create model elements and can be used to lookup elements or query for a set of elements.
  42 + The :doc:`data model <datamodel>` itself is maintained in the element
  43 + factory. This service is used to create model elements and can be used to
  44 + lookup elements or query for a set of elements.
32 45
33   -undo_manager
34   - One of the most appreciated services. It allows users to make a mistake every now and then.
  46 +:doc:`undo_manager <undo>`
  47 + One of the most appreciated services. It allows users to make a mistake
  48 + every now and then!
35 49
36   - The undo manager is transactional. Actions performed by a user are only stored in a transaction is active. If a transaction is completed (committed) a new undo action is stored. Transactions can also be rolled back, in which case all changes are played back directly.
  50 + The undo manager is transactional. Actions performed by a user are only
  51 + stored in a transaction is active. If a transaction is completed (committed)
  52 + a new undo action is stored. Transactions can also be rolled back, in which
  53 + case all changes are played back directly.
37 54
38 55 element_dispatcher
39   - Although Gaphor makes use of a central dispatch engine, this solution is not efficient when it comes to dispatching events of UML model elements. For this purpose the `element_dispatcher` can help out. It maintains a path of elements reaching from the root (e.g. from a diagram item) to the element of interest and will only signal in case this element changes. This makes complex dispatching very efficient.
  56 + Although Gaphor makes use of a central dispatch engine, this solution is not
  57 + efficient when it comes to dispatching events of UML model elements. For
  58 + this purpose the `element_dispatcher` can help out. It maintains a path of
  59 + elements reaching from the root (e.g. from a diagram item) to the element of
  60 + interest and will only signal in case this element changes.
  61 + This makes complex dispatching very efficient.
  62 +
  63 +.. autoclass:: gaphor.services.elementdispatcher.ElementDispatcher
77 doc/items.txt
... ... @@ -1,27 +1,56 @@
1 1 Gaphor Diagram Items
2 2 ====================
3   -The Gaphor diagram items (or in short `items`) represent UML metamodel on a
4   -diagram.
5   -
6   -Basic items
7   -
8   - DiagramItem
9   - Basic diagram item supporting item style, text elements
10   - and stereotypes.
11   - ElementItem
12   - Rectangular canvas item.
13   - NamedItem
14   - NamedElement (UML metamodel) representation using rectangular
15   - canvas item.
16   - CompartmentItem
17   - An item with compartments (i.e. Class or State)
18   - ClassifierItem
19   - Classifer (UML metamodel) representation.
20   - DiagramLine
21   - Line canvas item.
22   - NamedLine
23   - NamedElement (UML metamodel) representation using line canvas item.
24   - FeatureItem
25   - Diagram representation of UML metamodel classes like property,
26   - operation, stereotype attribute, etc.
  3 +The diagram items (or in short `items`) represent UML metamodel on a diagram.
  4 +The following sections present the basic items.
  5 +
  6 +DiagramItem
  7 +-----------
  8 +Basic diagram item supporting item style, text elements and stereotypes.
  9 +
  10 +.. autoclass:: gaphor.diagram.diagramitem.DiagramItem
  11 + :members:
  12 +
  13 +ElementItem
  14 +-----------
  15 +Rectangular canvas item.
  16 +
  17 +.. autoclass:: gaphor.diagram.elementitem.ElementItem
  18 +
  19 +NamedItem
  20 +---------
  21 +NamedElement (UML metamodel) representation using rectangular canvas item.
  22 +
  23 +.. autoclass:: gaphor.diagram.nameditem.NamedItem
  24 +
  25 +CompartmentItem
  26 +---------------
  27 +An item with compartments (i.e. Class or State)
  28 +
  29 +.. autoclass:: gaphor.diagram.compartment.CompartmentItem
  30 +
  31 +ClassifierItem
  32 +--------------
  33 +Classifer (UML metamodel) representation.
  34 +
  35 +.. autoclass:: gaphor.diagram.classifier.ClassifierItem
  36 +
  37 +DiagramLine
  38 +-----------
  39 +Line canvas item.
  40 +
  41 +.. autoclass:: gaphor.diagram.diagramline.DiagramLine
  42 +
  43 +NamedLine
  44 +---------
  45 +NamedElement (UML metamodel) representation using line canvas item.
  46 +
  47 +.. autoclass:: gaphor.diagram.diagramline.NamedLine
  48 +
  49 +FeatureItem
  50 +-----------
  51 +Diagram representation of UML metamodel classes like property, operation,
  52 +stereotype attribute, etc.
  53 +
  54 +.. autoclass:: gaphor.diagram.compartment.FeatureItem
  55 +
27 56
39 doc/linux.txt
... ... @@ -1,25 +1,28 @@
1   -= Linux Distro Packages =
2   -Examples of Gaphor and Gaphas RPM spec files can be found in
3   -[http://www.pld-linux.org/ PLD Linux]
4   -[http://cvs.pld-linux.org/cgi-bin/cvsweb/SPECS/ repository]
5   - * [http://cvs.pld-linux.org/cgi-bin/cvsweb/SPECS/python-gaphas.spec gaphas]
6   - * [http://cvs.pld-linux.org/cgi-bin/cvsweb/SPECS/gaphor.spec gaphor]
  1 +Gaphor on Linux
  2 +===============
  3 +
  4 +Examples of Gaphor and Gaphas RPM spec files can be found in `PLD Linux <http://www.pld-linux.org/ PLD Linux>`_
  5 +`repository <http://cvs.pld-linux.org/cgi-bin/cvsweb/SPECS/>`_:
  6 +
  7 + * http://cvs.pld-linux.org/cgi-bin/cvsweb/SPECS/python-gaphas.spec
  8 + * http://cvs.pld-linux.org/cgi-bin/cvsweb/SPECS/gaphor.spec
7 9
8 10 Please, do not hesistate to contact us if you need help to create Linux package
9 11 for Gaphor or Gaphas.
10 12
11   -= Dependencies =
  13 +Dependencies
  14 +------------
12 15
13   -Gaphor depends on Zope libraries
14   - * component
15   - * interface
16   -and
17   - * gaphas (of course :)
18   - * pygtk
  16 +Gaphor depends on Zope libraries:
  17 + * component
  18 + * interface
  19 +and:
  20 + * gaphas (of course :)
  21 + * pygtk
19 22
20 23 Above Zope modules require
21   - * deferredimport
22   - * deprecation
23   - * event
24   - * proxy
25   - * testing
  24 + * deferredimport
  25 + * deprecation
  26 + * event
  27 + * proxy
  28 + * testing
155 doc/make.bat
... ... @@ -0,0 +1,155 @@
  1 +@ECHO OFF
  2 +
  3 +REM Command file for Sphinx documentation
  4 +
  5 +if "%SPHINXBUILD%" == "" (
  6 + set SPHINXBUILD=sphinx-build
  7 +)
  8 +set BUILDDIR=_build
  9 +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
  10 +if NOT "%PAPER%" == "" (
  11 + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
  12 +)
  13 +
  14 +if "%1" == "" goto help
  15 +
  16 +if "%1" == "help" (
  17 + :help
  18 + echo.Please use `make ^<target^>` where ^<target^> is one of
  19 + echo. html to make standalone HTML files
  20 + echo. dirhtml to make HTML files named index.html in directories
  21 + echo. singlehtml to make a single large HTML file
  22 + echo. pickle to make pickle files
  23 + echo. json to make JSON files
  24 + echo. htmlhelp to make HTML files and a HTML help project
  25 + echo. qthelp to make HTML files and a qthelp project
  26 + echo. devhelp to make HTML files and a Devhelp project
  27 + echo. epub to make an epub
  28 + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
  29 + echo. text to make text files
  30 + echo. man to make manual pages
  31 + echo. changes to make an overview over all changed/added/deprecated items
  32 + echo. linkcheck to check all external links for integrity
  33 + echo. doctest to run all doctests embedded in the documentation if enabled
  34 + goto end
  35 +)
  36 +
  37 +if "%1" == "clean" (
  38 + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
  39 + del /q /s %BUILDDIR%\*
  40 + goto end
  41 +)
  42 +
  43 +if "%1" == "html" (
  44 + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
  45 + echo.
  46 + echo.Build finished. The HTML pages are in %BUILDDIR%/html.
  47 + goto end
  48 +)
  49 +
  50 +if "%1" == "dirhtml" (
  51 + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
  52 + echo.
  53 + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
  54 + goto end
  55 +)
  56 +
  57 +if "%1" == "singlehtml" (
  58 + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
  59 + echo.
  60 + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
  61 + goto end
  62 +)
  63 +
  64 +if "%1" == "pickle" (
  65 + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
  66 + echo.
  67 + echo.Build finished; now you can process the pickle files.
  68 + goto end
  69 +)
  70 +
  71 +if "%1" == "json" (
  72 + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
  73 + echo.
  74 + echo.Build finished; now you can process the JSON files.
  75 + goto end
  76 +)
  77 +
  78 +if "%1" == "htmlhelp" (
  79 + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
  80 + echo.
  81 + echo.Build finished; now you can run HTML Help Workshop with the ^
  82 +.hhp project file in %BUILDDIR%/htmlhelp.
  83 + goto end
  84 +)
  85 +
  86 +if "%1" == "qthelp" (
  87 + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
  88 + echo.
  89 + echo.Build finished; now you can run "qcollectiongenerator" with the ^
  90 +.qhcp project file in %BUILDDIR%/qthelp, like this:
  91 + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Gaphor.qhcp
  92 + echo.To view the help file:
  93 + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Gaphor.ghc
  94 + goto end
  95 +)
  96 +
  97 +if "%1" == "devhelp" (
  98 + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
  99 + echo.
  100 + echo.Build finished.
  101 + goto end
  102 +)
  103 +
  104 +if "%1" == "epub" (
  105 + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
  106 + echo.
  107 + echo.Build finished. The epub file is in %BUILDDIR%/epub.
  108 + goto end
  109 +)
  110 +
  111 +if "%1" == "latex" (
  112 + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
  113 + echo.
  114 + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
  115 + goto end
  116 +)
  117 +
  118 +if "%1" == "text" (
  119 + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
  120 + echo.
  121 + echo.Build finished. The text files are in %BUILDDIR%/text.
  122 + goto end
  123 +)
  124 +
  125 +if "%1" == "man" (
  126 + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
  127 + echo.
  128 + echo.Build finished. The manual pages are in %BUILDDIR%/man.
  129 + goto end
  130 +)
  131 +
  132 +if "%1" == "changes" (
  133 + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
  134 + echo.
  135 + echo.The overview file is in %BUILDDIR%/changes.
  136 + goto end
  137 +)
  138 +
  139 +if "%1" == "linkcheck" (
  140 + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
  141 + echo.
  142 + echo.Link check complete; look for any errors in the above output ^
  143 +or in %BUILDDIR%/linkcheck/output.txt.
  144 + goto end
  145 +)
  146 +
  147 +if "%1" == "doctest" (
  148 + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
  149 + echo.
  150 + echo.Testing of doctests in the sources finished, look at the ^
  151 +results in %BUILDDIR%/doctest/output.txt.
  152 + goto end
  153 +)
  154 +
  155 +:end
30 doc/manual/documentation.txt
... ... @@ -1,30 +0,0 @@
1   -Documentation
2   -=============
3   -
4   -
5   - ''The source is the documentation.''
6   -
7   -Well, not for us.
8   -
9   -Currently, there's not a lot of documentation though. For those of you interested in Gaphor there's
10   -
11   - * A manual_. It outlines some of the ideas in and behind Gaphor.
12   - * The Tech section contains some interesting articles about the technology that drives Gaphor and Gaphas, Gaphor's canvas widget.
13   - * We're working on a `new manual`_.
14   -
15   -If you're into writing plug-ins for Gaphor you should have a look at our fabulous [source:/gaphor-plugins/gaphor.plugins.helloworld Hello world] plug-in.
16   -
17   -External links
18   -==============
19   -
20   - * You should definitely check out http://www.agilemodeling.com.
21   - * The `UML diagrams <http://www.agilemodeling.com/essays/umlDiagrams.htm>`_ (although Gaphor does not see it that black-and-white).
22   - * http://www.agilemodeling.com/essays/
23   - * The `official UML metamodel specification <http://www.omg.org/technology/documents/modeling_spec_catalog.htm#UML>`_. This ''is'' our data model.
24   -
25   -Odds and ends
26   -=============
27   -
28   -* A somewhat older document about [wiki:Documentation/GtkWin32 how to get GTK+ with Python bindings working on Win32].
29   -
30   -.. _manual: manual.html
7 doc/manual/index.txt
... ... @@ -1,8 +1,9 @@
1   -The new Gaphor manual
  1 +The Gaphor manual
2 2 =====================
3 3
4   -
5   -This section of the site is dedicated to some user documentation. Although most users will have previous experience with Gaphor, it is evident that some aspects of the application need a little more explanation.
  4 +This section of the site is dedicated to some user documentation. Although most
  5 +users will have previous experience with Gaphor, it is evident that some
  6 +aspects of the application need a little more explanation.
6 7
7 8
8 9 .. toctree::
13 doc/manual/introduction.txt
@@ -3,19 +3,24 @@ Introduction
3 3
4 4 Welcome to the Gaphor!
5 5
6   -Gaphor is a UML modelling application written in Python. It is designed to be easy to use while not substituting completeness, that is, Gaphor implements a fully-compliant UML 2 data model. You can use Gaphor to quickly visualize different aspects of a system as well as create complete, highly complex models.
  6 +Gaphor is a UML modelling application written in Python. It is designed to be
  7 +easy to use while not substituting completeness, that is, Gaphor implements a
  8 +fully-compliant UML 2 data model. You can use Gaphor to quickly visualize
  9 +different aspects of a system as well as create complete, highly complex models.
7 10
8 11 Gaphor is designed around the following principles:
9 12
10 13 Consistency
11   - UML is a graphical modelling language, so every aspect should be represented in a diagram[1]_.
  14 + UML is a graphical modelling language, so every aspect should be represented in a diagram [#f1]_ .
12 15 Simplicity
13 16 The application should be easy to use. Only some basic knowledge of UML is required.
14 17 Workability
15 18 The application should not bother the user every time (s)he does something non-UML-ish.
16 19
17   -This manual serves as a reference for all Gaphor as to offer. So, you may read it from start to finish, or jump to a section that interests you.
  20 +This manual serves as a reference for all Gaphor has to offer. So, you may read it from start to finish, or jump to a section that interests you.
  21 +
  22 +
  23 +.. [#f1] We take this quite literally: even stereotypes are modelled in diagrams.
18 24
19   -.. _[1] We take this quite literally: even stereotypes are modelled in diagrams.
20 25
21 26
36 doc/manual/modelling.txt
... ... @@ -1,36 +1,54 @@
1 1 Creating models
2 2 ===============
3 3
4   -.. image:: oneclass.png
  4 +Once Gaphor is started a new empty model is automatically created. The `main`
  5 +diagram is already open in the :doc:`Diagram section <working>`.
5 6
6   -Once Gaphor is started a new empty model is automatically created. The ''main'' diagram is already open in the :doc:`Diagram section <working>`.
  7 +Select an element you want to place (e.g. a class) by clicking on the icon in
  8 +the :doc:`Toolbox <working>` and click on the diagram. This will place a new
  9 +Class item instance on the diagram and add a new Class to the model (it shows
  10 +up in the :doc:`Navigation <working>`). The selected tool will reset itself to
  11 +the Pointer tool if the option ''Diagram -> Reset tool'' is selected.
7 12
8   -Select an element you want to place (e.g. a class) by clicking on the icon in the :doc:`Toolbox <working>` and click on the diagram. This will place a new Class item instance on the diagram and add a new Class to the model (it shows up in the :doc:`Navigation <working>`). The selected tool will reset itself to the Pointer tool if the option ''Diagram -> Reset tool'' is selected.
  13 +.. image:: oneclass.png
9 14
10 15 It's simple to add elements to a diagram.
11 16
12   -Some elements are not directly visible. The section in the toolbox is collapsed and needs to be clicked first to reveal its contents.
  17 +Some elements are not directly visible. The section in the toolbox is collapsed
  18 +and needs to be clicked first to reveal its contents.
13 19
14   -Gaphor does not make any assumptions about which elements should be placed on a diagram. A diagram is a diagram. UML defines all different kinds of diagrams, such as Class diagrams, Component diagrams, Action diagrams, Sequence diagrams. But Gaphor does not restrict the user.
  20 +Gaphor does not make any assumptions about which elements should be placed on a
  21 +diagram. A diagram is a diagram. UML defines all different kinds of diagrams,
  22 +such as Class diagrams, Component diagrams, Action diagrams, Sequence diagrams.
  23 +But Gaphor does not restrict the user.
15 24
16 25 Creating new diagrams
17 26 =====================
18 27
19 28 .. image:: navpopup.png
20 29
21   -To create a new diagram, use the Navigation. Select an element that can contain a diagram (a Package or Profile) and right-click [1]_. Select `New diagram` and a new diagram is created.
  30 +To create a new diagram, use the Navigation. Select an element that can contain
  31 +a diagram (a Package or Profile) and right-click [1]_. Select `New diagram`
  32 +and a new diagram is created.
22 33
23 34 Copy and paste
24 35 ==============
25 36
26   -Items in a diagram can be copied and pasted (in the same diagram or another). A paste will create new items in the diagrams, the items they represent (e.g. the Class that's shown in the Naviagtion) is *not* copied (call it a shallow copy if you like).
  37 +Items in a diagram can be copied and pasted (in the same diagram or another).
  38 +A paste will create new items in the diagrams, the items they represent (e.g.
  39 +the Class that's shown in the Naviagtion) is *not* copied (call it a shallow
  40 +copy if you like).
27 41
28 42 Drag and drop
29 43 =============
30 44
31   -Adding an existing element to a diagram is simple: drag the element from the Navigation section onto a diagram. Not all element that show up in the Navigation can be added: Diagrams and attribute/operations of a Class can not be added.
  45 +Adding an existing element to a diagram is simple: drag the element from the
  46 +Navigation section onto a diagram. Not all element that show up in the
  47 +Navigation can be added: Diagrams and attribute/operations of a Class can not
  48 +be added.
32 49
33   -Elements can also be dragged within the Navigation section. This way classes and packages can be rearranged for example.
  50 +Elements can also be dragged within the Navigation section. This way classes
  51 +and packages can be rearranged for example.
34 52
35 53 .. [1] Command-Click for MacOS X users running Gaphor in X11.
36 54
23 doc/manual/plugins.txt
@@ -6,7 +6,11 @@ There is little difference in writing a plugin or a service.
6 6 Accessing model related data
7 7 ----------------------------
8 8
9   -The datamodel classes are located in the `gaphor.UML` module. Data objects can be accessed through the ElementFactory. This is a special class for creating and managing data objects. Items can be queried using this element factory. It's registered in the application as `element_factory`. When writing a service or plugin the element factory can be injected into the service like this::
  9 +The datamodel classes are located in the `gaphor.UML` module. Data objects can
  10 +be accessed through the ElementFactory. This is a special class for creating
  11 +and managing data objects. Items can be queried using this element factory.
  12 +It's registered in the application as `element_factory`. When writing a service