Hi Maren,
Yes. You got everything correct... AFAIK. Sorry about taking too long to reply to this thread again. This month (April) is being mostly hectic for me.
Retaking our previous conversations: I would love to help, somehow, to solve the project documentation issues we have (or will soon have in the near future). I know it sounds pretentious... but it's not. This email was inspired by this email thread here >> https://sourceforge.net/p/inkscape/mailman/message/35608481/
I strongly believe that GitHub would be amazing for the Inkscape app and all... but since this is out of question because it's not open source we can stick to the GitLab for the docs as well. I believe we could do some testing with Sphinx on GitLab to be sure it is a good tool and that people have positive experience using it in the long run.
From the (small I confess) research I did here are some interesting facts...
Good reasons for us to use sphinx are:
- Software license: BSD. - Platforms it runs: Windows, Linux, Mac, BSD, and Unix. - Programming languages it supports: C, *C++*, Java, PHP, *Python*, Ruby, and JavaScript (also Ada and Fortran). - Output formats are: *HTML*, CHM(Windows only probably), *PDF*(indirectly), LaTex, PostScript(indirectly), Man Pages, and *epubs* (generated epubs produce a validation fail on epub chech according to wikipedia).
Other goodies are:
- 10 themes; - Jinja2 templating; - Python plugins several in sphinx-contrib, e.g. using aafigure, actdiag, Google Chart, or gnuplot - Table of Contents, Index; - cross referencing; - syntax highlighting with Pygments custom objects (such as functions and classes)
I strongly believe that having a tool to help us document code (C++ and Python especially) as well as assembling the user guide in the SAME TOOL and ENVIRONMENT is a HUGE plus! Also by being able to allow our users, collaborators, volunteers and fans all over the world to use a tool that will run on virtually all of the main Operating Systems (Windows Linux and Mac (just like the Inkscape app itself)) is a another GREAT advantage for us.
Using this tool we would be not hard because we would... well.. document it in the Gitlab pages. All of the instructions. Having an Official Inkscape Doc place would be amazing and would avoid some of the emails we get (I know... they are not that many... even though...).
I believe it also makes a lot of sense to have the docs in the same git repository service for simplicity and easier to be discovered.
Sorry for writing all that much. I would love to hear the community feedback on this.
We could also copy Gimp in the way that they distribute their manual as a separate bundle to be downloaded and installed separately (not sure this will apply to us) and Blender because I strongly believe they also use Sphinx in their documentation activities. ;-)
Hope you all have an amazing week!
--Victor Westmann
2017-04-08 18:27 GMT-07:00 Maren Hachmann <maren@...325...>:
Hi Victor,
thanks for getting into this, and learning about all of this!
Am 09.04.2017 um 01:07 schrieb Victor Westmann:
Hi Sylvain,
I just did a simple change of language on the latest (0.92.1) Inkscape app and, even though it's impressive the application supports so many different languages, it needs to be restarted to do so. Which would make the work of a single person capturing the same Inkscape window in a lot of different languages longer and a little bit tedious.
I went to Edit > Preferences (or Ctrl + Shift + P) > Interface > Selected my language of choice...
I have no idea of how much engineering it would demand -- and if this is even possible -- but I believe that for one single person to capture the same screenshot -- for our manual and documentation purposes -- multiple times(for the different languages) it would be better if it could change language of the UI without restarting the application and if we could do so using a few keyboard shortcuts. Maybe I'm asking too much here.
- Each translator could do his/her own screenshots, so that would spread
the work out. Translation is important, but I'd say that it's not the primary focus. It would be more important to me to get an up-to-date documentation in English first. If really needed, there would be ways to automate the process (but I'm not sure that's necessary). I don't expect we'd have more than 3 or 4 manual translation languages in the near to far future (of course, more is nice :) ).
Since the Inkscape already has a great number of languages but it needs to be restarted to show them, maybe we would need to define a standard Operating System (at least in the case of Windows and macOS machines) for consistency.
This seems far more complicated than I have anticipated before. I believe that having, initially, the images in English would be ideal.
Another challenge that came to my mind is: IF we happen to make a new official documentation manual for the Inkscape online (more or less on the "Read the docs" style) how would we make it?
Two options here:
- Would we change the entire manual for each major Inkscape release?
(0.93.x, 0.94.x...) 2. Or would we keep the old manuial (as long as the features described in it are the same) and only append a section like: NEW FEATURES IN VERSION 0.93 and make it incremental? (I like this approach better)
- I would choose neither. I'm hoping we can leverage version control for
this, and a system that supports this by using tags on a version, or by using separate branches. Else we'd make one manual for every major release, each based upon the previous one. So, incremental: yes. Appendix: no. But this would mean that no changes could be made to previous manual versions... That would require branches, one for each version.
I think Tav made his manual kind of 'universal', by adding the version numbers right into the text. That's fine for a limited set of versions, or maybe for sub-versions, but I find it gets confusing when there are major changes.
If the version control / branches / tagging / backporting thing doesn't work (as would probably be the case with flossmanuals), I'd go with separate manuals. We can only ship (i.e. include with Inkscape) one per version anyway.
Getting the screenshots and making a lot of numbers inside circles and then pointing them out would be a long work, even longer if we consider a way to include all the multiple languages.
- The files could be prepared as SVG, then you'd only need to exchange
the screenshot within it. In most cases, numbering items on the screenshot won't be needed, though, I think.
Another challenge (just brainstorming here, I don't want to get anyone upset, just trying to anticipate problems before they happen so we can solve and overcome them) what if we change to a different language (let's say mine PT_BR) and the strings weren't translated correctly or are in English?
- Then the user will be happy that at least there is a partial
translation :-) That's better than nothing. But really we'd only need to include languages where there was a translator working on it.
This makes me go back to the approach of trying to get the images in plain EN English idiom. We would change everything else (text). This way the manual would be produced faster and quicker. And we could get more volunteers to collaborate in it.
I believe we also strongly need a DEV documentation as well because we get a lot of emails on the others lists asking how to compile Inkscape on X platform. :-)
Thoughts anyone?
- Dev documentation is supposed to become included in the Inkscape
source code repository (at least that seems to be the favourite location for it for developers). For that one, some automated way of document generation from comments in the code, plus files that can live in the repo itself would be mandatory. Currently, that documentation can be found in the Wiki (and on the Jenkins server... at least an outdated version of it).
On another note, if the Hackfest will take place in Paris, then Elisa and Cédric will probably also take a shot at the manual issue. It would be so cool if we could get started soon :)
Btw. I always thought that the 'Initiation à Inkscape' manual was completely different from the English flossmanuals manual, contents-wise.
From what I have seen, the French one is more of a guide, that describes
the main functionality for new users (e.g. it explains usage by topic, and copy-paste and saving a file are at the end, in the chapter 'Advanced techniques'). The English, and more outdated, one is more of a reference, more like Tav's manual.
In my opinion, the 'official' manual should be more along the reference line, so all that undocumented, advanced functionality will get a chance of being documented. So I would rather start from the outdated, English one. But that's to be discussed, and any up-to-date manual is better than no manual :)
Hope I got everything you said correctly, Victor, thanks again, Maren
--Victor Westmann
2017-04-07 14:42 GMT-07:00 Sylvain Chiron <chironsylvain@...364... mailto:chironsylvain@...364...>:
Le 06/04/2017 à 19:06, Victor Westmann a écrit : > I was just wondering if new languages, based on the Englishmanual,
> would use Inkscape images in English or if they would like to retake the > same screenshots in different languages? It would be pleasant to be able to propose translated images, the original ones being used as default. I like doing perfect work — :). -- Sylvain ------------------------------------------------------------
Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot _______________________________________________ Inkscape-translator mailing list Inkscape-translator@lists.sourceforge.net <mailto:Inkscape-translator@lists.sourceforge.net> https://lists.sourceforge.net/lists/listinfo/inkscape-translator <https://lists.sourceforge.net/lists/listinfo/inkscape-translator>
Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot
Inkscape-translator mailing list Inkscape-translator@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-translator
Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot _______________________________________________ Inkscape-translator mailing list Inkscape-translator@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-translator