Commit 069f692e authored by Maren Hachmann's avatar Maren Hachmann
Browse files

Update README instructions and style.

(cherry picked from commit e7ef9b01)
parent 72b2a875
Pipeline #386280340 passed with stages
in 23 minutes and 45 seconds
Inkscape Documentation
======================
# Inkscape Documentation
This includes all files required for creating localized documentation for Inkscape.
......@@ -10,17 +9,16 @@ At the time of this writing this includes:
It also has rules to create translation statistics (*statistics*).
Translating Documentation in this repository
--------------------------------------------
## Translating Documentation in this repository
**What needs translation?**
### What needs translation?
An overview about the status of translations in the Inkscape project is available at:
- https://inkscape.org/doc/devel/translations-statistics-master.html (for Inkscape master branch)
- https://inkscape.org/doc/devel/translations-statistics092.html (for the 0.92.x series)
- https://inkscape.org/doc/devel/translations-statistics-1.1.x.html (for the 1.1.x series)
**How do I get the files?**
### How do I get the files?
If you feel comfortable using git and/or the GitLab webinterface, the preferred way is to fork this repository and work on a new branch in this fork.
......@@ -29,7 +27,7 @@ At a later point, we may add info here about different versions that need to be
For non-programmers, the quickest option to obtain the files is to download the [zip archive](https://gitlab.com/inkscape/inkscape-docs/documentation/repository/0.92.x/archive.zip).
**Which files need to be translated?**
### Which files need to be translated?
You can find po files ready for translation in the following subdirectories:
- keys
......@@ -38,7 +36,7 @@ You can find po files ready for translation in the following subdirectories:
If there isn't a file for your language yet, you can create a new one by copying the files 'keys.pot', 'man.pot' or '\<tutorial_name.pot\>' and renaming the copy to '<your_language_code>.po'.
**Is there anything important I need to know?**
### Is there anything important I need to know?
- The translation files for the manual contain some unusual formatting, e.g. <pre>C\<E\<lt\>defsE\<gt\>\></pre> Please leave these strings intact.
- For the tutorials, we also need translations of the header and footer SVGs and for some of the screenshot PNG files.
......@@ -47,29 +45,59 @@ If there isn't a file for your language yet, you can create a new one by copying
To translate it, you will have to recreate the text object yourself (use a generic sans-serif font with appropriate license, e.g. ‘DejaVu Sans’ or ‘Bistream Vera Sans’, in italic)
and convert it to a path when you're done. Also consider the translucent ‘tutorial’ text path in the background.
**I'm ready. How do I submit my translations?**
### I'm ready. How do I submit my translations?
The preferred way is to create a merge request using the GitLab webinterface.
Alternatively you can create a new new issue (https://gitlab.com/inkscape/inkscape-docs/documentation/-/issues) and attach your edited file.
Alternatively you can create a new issue (https://gitlab.com/inkscape/inkscape-docs/documentation/-/issues) and attach your edited file.
You may add the tags 'documentation' and 'translation' to it.
If you need help with the process feel free to contact us in our chat room at https://chat.inkscape.org/channel/documentation
## Updating documentation
Creating documentation
----------------------
### Tutorials
If using Ubuntu, you need to install (at least) the packages `gnome-doc-utils` and `python-pexpect`.
To update tutorials, open the file `<tutorial name>.xml` in the subdirectory for the tutorial of your choice in the `tutorials` directory and edit away. Use the current syntax in the file as a guide.
Each of the subdirectories has a README with detailed information on how to use (including more info on software requirements).
### Man page
Also you'll find a Makefile in each subdirectory for usage with GNU make (use `make help` for usage information)
To update the man page entries, you need to edit the files `inkscape.pod.in` and `inkview.pod.in` in the `man` subdirectory. The syntax here is a bit exotic, but there [exists documentation](https://perldoc.perl.org/perlpod) for it. You can ignore the warning message at the beginning that says not to edit the file directly. That message transfers into the derived documents, which are the actual target for that message to appear.
### Keyboard shortcuts
To update the keyboard shortcuts, you need to edit the file `keys.xml` in the `keys` subdirectory. Use the already existing examples in the file as a guide for choosing the correct syntax.
## Generating documentation on your own computer
While GitLab offers a way to auto-generate documentation files to check the results, you may wish to generate the documentation files locally on your own computer to check whether your changes produce the desired result.
In order to do this, first, download the [zip file](https://gitlab.com/inkscape/inkscape-docs/documentation/-/archive/master/documentation-master.zip) for this repository and extract the archive to your disk, or (better) clone the repository via git.
If using Ubuntu (>= 20.04) – or a derivative like Linux Mint –, you need to use the following commands to install all the necessary packages for generating the documentation:
'''
$ sudo add-apt-repository ppa:inkscape.dev/stable
$ sudo apt-get update
$ sudo apt-get install git make less wget unzip gettext po4a libxml2-utils \
python3-libxml2 python3 python3-pip python3-lxml \
python3-pexpect inkscape fonts-liberation tidy xsltproc
$ pip3 install --user --upgrade scour itstool
'''
Do not include the `$` sign when pasting the commands line-by-line. This will also install the current stable Inkscape version from the ppa.
If you're using another operating system / Linux distribution, we may be able to provide help with finding the correct packages / software to install [in the chat](https://chat.inkscape.org/channel/documentation), but there's no guarantee that it will work.
Each of the subdirectories in the repository has a README with detailed information on how to use (including more info on software requirements).
Also you'll find a Makefile in each subdirectory for usage with GNU make (use `make help` for usage information).
If you're feeling lucky (or know that you have all requirements installed)
you can also use the convenience targets from the top level Makefile:
- use `make` to generate all documentation
- use `make all` to generate all documentation
- use `make clean` to delete generated files again, for a clean new trial
- use `make help` to see additional usage information
*Note: As git does not track file modification times `make` might not be able to determine which targets need to be
re-made after checking out new files. In order to re-make all files use `make --always-make` (or `make -B`).*
\ No newline at end of file
re-made after checking out new files. In order to re-make all files use `make --always-make` (or `make -B`).*
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment