Skip to content

Commit

Permalink
Correct typos and difficult word choices for all text files (zim-desk…
Browse files Browse the repository at this point in the history 
…top-wiki#1409)

* Correct typos and difficult word choices in top level markdown files
* Correct typos and language in zim help
* Correct typos and language in zim plugin instructions
* Correct typos and language in zim manual/usage
* Correct typos and language in zim website
  • Loading branch information
@sanjarcode
sanjarcode authored Apr 12, 2021
1 parent 158496c commit 13d8c46
Show file tree
Hide file tree
Showing 66 changed files with 322 additions and 322 deletions.
66 changes: 33 additions & 33 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
Contributing
============

Thank you for considering to contribute to the zim desktop wiki project. Zim
is an open source project and run by volunteers, so all help is welcome.
Thank you for considering contributing to the zim desktop wiki project. Zim
is an open-source project and run by volunteers, so all help is welcome.


**Help wanted:** there are many issues in the bug tracker that need someone to pick
them up. To get started please have a look at the
them up. To get started, please have a look at the
[good first issue](https://github.com/zim-desktop-wiki/zim-desktop-wiki/labels/good%20first%20issue)
and
[plugin idea](https://github.com/zim-desktop-wiki/zim-desktop-wiki/labels/plugin%20idea) labels.
Expand All @@ -32,73 +32,73 @@ and [Development Planning](https://github.com/zim-desktop-wiki/zim-desktop-wiki/
To file a bug report, please go to the bug tracker at
https://github.com/zim-desktop-wiki/zim-desktop-wiki/issues

* Make sure the issue is not already in the list by trying out a few key words
* Make sure the issue is not already in the list by trying out a few keywords
in the search box
* Describe what you did and what happened in such a way that another user can
follow step by step and reproduce the same result
* Please include information on your operating system, language settings, and
other relevant context information

## Requesting new functionality
Also feature requests can go in the bug tracker. In this case:
Also, feature requests can go in the bug tracker. In this case:

* Please provide a use case description, explain the problem you are trying to
solve with the proposed feature before describing the solution. This allows
solve with the proposed feature before describing the solution. This allows
other users to think along and maybe improve on your solution.
* Make sure the use case is generic enough that it will benefit other users
as well. If it is highly tailored for your specific work flow, chances are
as well. If it is highly tailored for your specific work-flow, chances are
that no-one will work on it (and no-one will want to maintain it in working
state over the years).


## Getting started with the code

See [README.md](./README.md) for instructions to setup zim from source code. Checkout
the github repository at https://github.com/zim-desktop-wiki/zim-desktop-wiki
the GitHub repository at https://github.com/zim-desktop-wiki/zim-desktop-wiki
to get the latest development branch.

The zim code is kept under version control using the git version control system.
zim code is kept under version control using the git version control system.
See the website for documentation on using this system: https://git-scm.com/

For indenting of python code the code base uses TABs (not spaces) with a
tabstop set to the equivalent of 4 spaces. (Yes I know this breaks the PEP8
For indenting of python code, the code base uses TABs (not spaces) with a
tabstop set to the equivalent of 4 spaces. (Yes, I know this breaks the PEP8
recommendation.)


## Bug fixes
For obvious bugs with simple fixes a merge request can be opened directly.
For obvious bugs with simple fixes, a merge request can be opened directly.
These should be very easy to review and merge. If you consider something a bug
even though the code does what it is supposed to do, please discuss first on
even though the code does what it is supposed to do, please discuss it first on
the mailing list or through an issue ticket.


## Adding new features
Many features can be added through a plugin. Where possible this is the
preferred way of extending zim. Using a plugins allows adding lot of
preferred way of extending zim. Using a plugin greatly increases
configurability via the plugin preferences and properties while keeping the
core interfaces simple.

See [PLUGIN_WRITING.md](./PLUGIN_WRITING.md) for documentation on writing plugins. Also if you want
to work on the core functionality, this is a good introduction on the code
to work on the core functionality, this is a good introduction to the code
structure.

Only very generic features that are obviously useful for all users should be
part of the core package. When in doubt please discuss first - either via the
mailing list or via a github issue ticket.
mailing list or via a GitHub issue ticket.

In some cases there is a good compromise by extending the core functionality
In some cases, there is a good compromise by extending the core functionality
with certain capabilities, but exposing the user interface to take advantage of
these capabilities via a plugin. An example of this is the support for tags;
tags are part of the core wiki parsing methods, however to see a special index
tags are part of the core wiki parsing methods, however, to see a special index
view for tags you need to enable a plugin.

### Test suite

Zim comes with a full test suite, it can be executed using the `test.py`
script. See `test.py --help` for it's commandline options.
Zim comes with a full test suite, that can be executed using the `test.py`
script. See `test.py --help` for its commandline options.

It is good practice to run the full suite before committing to a development
branch and especially before generating a merge request. This should ensures the
branch and especially before generating a merge request. This should ensure that a
new patch doesn't break any existing code.

For any but the most trivial fixes test cases should be written to ensure the
Expand All @@ -107,31 +107,31 @@ You'll be surprised how often the same bug comes back after some time if there i
no test case in place to detect it. Some bugs are just waiting to happen
again and again.

For writing tests have a look at the existing test code or check the
For writing tests, have a look at the existing test code or check the
documentation for the "unittest" module in the python library.

A most useful tool for developing tests is looking at test **coverage**. When
you run `test.py` with the `--coverage` option the "coverage" module
will be loaded and a set of html pages will be generated in `./coverage`. In
these pages you can see line by line what code is called during the test run and
what lines of code go untested. It is hard to really get to 100% coverage, but
the target should be to get the coverage above at least 80% for each module.
will be loaded and a set of HTML pages will be generated in `./coverage`. In
these pages, you can see line by line what code is called during the test run and
what lines of code go untested. It is hard to really get 100% coverage, so
the target should be to get a coverage of at least 80% for each module.

If you added e.g. a new class and wrote a test case for it have a look at the
coverage to see what additional tests are needed to cover all code.
If you added e.g. a new class and wrote a test case for it, have a look at the
coverage to see what additional tests are needed to cover all of the code.

Of course having full coverage is no guarantee we cover all possible inputs, but
Of course, having full coverage is no guarantee that we covered all possible inputs, but
looking at coverage combined with writing tests for reported bugs should ensure
good project quality and satisfaction for all Zim users.


## Merge requests
Please use github to upload your patches and file a merge request towards the
zim repository. If you mention relevant issue numbers in the merge request it
Please use GitHub to upload your patches and file a merge request towards the
zim repository. If you mention relevant issue numbers in the merge request, it
will automatically be flagged in those issue tickets as well.

## Known Zim limitations
Main assumption about the whole file handling and page rendering is that files
The main assumption about file handling and page rendering is that files
are small enough that we can load them into memory several times. This seems a
valid assumption as notebooks are spread over many files. Having really huge
files as wiki content is outside the scope of the design. If this is what you want
Expand All @@ -145,7 +145,7 @@ To contribute to translations online please go to either
https://hosted.weblate.org/projects/zim/master/
or https://hosted.weblate.org/projects/zim/develop/.

The first one (ending in "master") contains translation strings for the current / upcoming releases. The second one (ending in "develop") could contain strings for new features.
The first one (ending in "master") contains translation strings for the current/upcoming releases. The second one (ending in "develop") could contain strings for new features.

Or you can edit the template zim.pot with your favorite editor. In that case you should add you new .po file to the po/ directory.

Expand Down
48 changes: 24 additions & 24 deletions PLUGIN_WRITING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,10 @@ Plugins

Plugins are one of the two extension mechanisms supported by zim. Plugins are loaded
as part of the application code and can modify key components of the interface.
In fact one of our design goals is to keep the core functionality limited and
One of our design goals is to keep the core functionality limited and
ship default plugins for anything a user would want to be able to disable.

( The other extension mechanism being "custom tools". The later allows defining
( The other extension mechanism being "custom tools". The latter allows defining
tools in the zim menu that call an external script or application. This can be
used to add some simple functions that only act on the files in the notebook. )

Expand All @@ -30,11 +30,11 @@ To allow plugins to be installed locally, the `$XDG_DATA_HOME/zim/plugins`
folder and all `$XDG_DATA_DIRS/zim/plugins` folders are added to the search
path for `zim.plugins`.

By default the home folder would be `~/.local/share/zim/plugins`.
By default, the home folder would be `~/.local/share/zim/plugins`.

The best for packaging is then is to organize your plugin as a folder with a
`__init__.py` containing the main plugin class. Users can then directly unpack
this folder to `~/.local/share/zim/plugins` or directly branch you git
this folder to `~/.local/share/zim/plugins` or directly branch your git
repository to this location.

The main plugin class should provide information for Zim to recognize the plugin
Expand All @@ -54,43 +54,43 @@ Example plugin class:
}
```

**NOTE:** when testing your plugin you will have to quite zim and restart after
changing the plugin code because once a plugin is loaded it keeps using the copy
**NOTE:** when testing your plugin you will have to quit zim and restart after
changing the plugin code because once a plugin is loaded, it keeps using the copy
from memory.

## Adding functionality to your plugin

The plugin class itself does not do much other than providing information about
the plugin and it's preferences.
the plugin and its preferences.

To add functionality to your plugin you need to define one or more classes that
do the actual work. These will be "extension" classes and must derive from a
do the actual work. These will be "extension" classes and must derive from an
extension base-class.

You can find all extension points in the application by searching for the
`@extendable` class decorator. Classes that are extendable have this decorator
and thus declare what extension base class they support.

For example to add functionality to the `PageView` class, you must define a
For example, to add functionality to the `PageView` class, you must define a
class derived from `PageViewExtension`.

At the time of writing these extension base-classes are defined:
- `NotebookExtension`: for functions that act on signals of the notebook
- `PageViewExtension`: for functions that add functionality to the editor
window, or want to add side panes next to the editor
- `InsertedObjectTypeExtension`: special extension for plugins that want to
define an object type (e.g. equation) that can be rendered in line in the
define an object type (e.g. equation) that can be rendered inline in the
text -- see also to `zim.plugins.base.imagegenerator` module
- `MainWindowExtension`: for any other changes to the mainwindow that are not
handled by a `PageViewExtension`

When you define a subclass of such an extension class it will be loaded
When you define a subclass of such an extension class, it will be loaded
automatically by the plugin for each instance of the target component.

Key interfaces for extensions are: adding actions, adding widgets, connecting
to signals and calling methods on the extended object.

Apart from extensions there is one other class that will also be used
Apart from extensions, there is one other class that will also be used
automatically: Classes derived from the `Command` class are used to handle
commandline arguments in the form "`zim --plugin yourplugin`".

Expand All @@ -99,18 +99,18 @@ commandline arguments in the form "`zim --plugin yourplugin`".

Preferences are maintained by the plugin object and are global for the
application. That means that they apply in the same way for all notebooks.
If your plugin has behavior that should be different per notebook you need to
If your plugin has a behavior that should be different per notebook, you need to
use the notebook properties instead.

Preferences can be defined by adding a list of `plugin_preferences` to your
plugin class. Within the plugin these are accessible through the `preferences`
dict and in the user interface they will show up in the plugin configuration
dict and in the user interface, they will show up in the plugin configuration
in the preferences dialog.

Notebook properties can be defined similarly by adding a list of
`plugin_notebook_properties` to the plugin class. To obtain the properties
for a specific notebook as a dict you need to call the plugin method
`notebook_properties()`. In the user interface they will show up in the
`notebook_properties()`. In the user interface, they will show up in the
properties dialog.

## Actions
Expand All @@ -130,15 +130,15 @@ extensions and actions defined by other plugins.
Zim is build using the Gtk / GObject toolkit. This toolkit relies heavily on
the concept of "signals" to collaborate between classes.

In short this means that any class can define a number of signals that are
In short, this means that any class can define a number of signals that are
emitted for various events. Objects that are interested in these events can
register an event handler using the `connect()` method.

Zim defines a `SignalConnectorMixin` class in `zim.signals` with some
convenience methods for classes that want to connect to signals.

For classes that do not derive for GObject classes but do want to emit their
own signales zim has it's own `SignalEmitter`class in `zim.signals`.
For classes that do not derive from GObject classes but do want to emit their
own signals zim has its own `SignalEmitter`class in `zim.signals`.


Keep in mind that with each `connect()` an object reference is created to the
Expand All @@ -163,18 +163,18 @@ See the python style guide for best practices. Some additional remarks:
statements could be optimized away
* Writing test cases is good, full test coverage is better.
Run `./test.py --cover` to get a coverage report.
* Use signals for colaboration between classes where possible
* Use signals for collaboration between classes where possible
* Signal handlers have a method name starting with "do_" (for signals of the
same classe) or "on_" (for signals of collaborating classes)
same class) or "on_" (for signals of collaborating classes)


### Test suite

Zim comes with a full test suite, it can be executed using the `test.py`
script. See `test.py --help` for it's commandline options.
script. See `test.py --help` for its commandline options.

This test suite will at least test for all plugins that they can be loaded
and contain proper information.
This test suite will at least test all plugins that can be loaded
and contain the proper information.

To test the specific functions of your plugin, you need to write your own test
case. Have a look at test cases of existing plugins for ideas how to do that.
Expand All @@ -188,7 +188,7 @@ and open a merge request.
Some things to consider:
* Make sure the plugin not only solves your own problem, but is also applicable
for a more generic use case that many people may have
* Each plugin should have it's own page in the user manual that explains what
* Each plugin should have its own page in the user manual that explains what
it does and how to use it.
* Each plugin should come with its own test cases for the test suite. Other
developers may not use your plugin, so if it breaks later on it may go
Expand Down
Loading

0 comments on commit 13d8c46

Please sign in to comment.