Hi Maren and Duarte,
I know you guys are long time translators for the Inkscape project.
Do you guys know if the Inkscape project has some kind of official documentation/book/guide/wiki?
I stumbled upon www.gitbook.com and am using it for a couple of years now and I love it. Do you guys think this is feasible at some level?
Just wanted to share some new ideas and insights on possible improvements on the project.
Your thoughs and ideas are more than welcome!
--Victor Westmann
I'm not that long-time translator at all, I just started contributing for the new website by chance.
Never even got into documentation, or UI, not very familiar with that area, but as far as I know Inkscape documentation resides in the Official Wiki http://wiki.inkscape.org/wiki/index.php/Inkscape, which I believe combines both manual, wiki, documentation and development info.
I don't know how it would fit into existing documentation, or if would create too fragmentation by scattering information, but it could work. Like most things in Open Source projects, I guess it's success would depend more on having active quality contributors, rather than the underlying system or platform used.
On 04-04-2017 00:19, Victor Westmann wrote:
Hi Maren and Duarte,
I know you guys are long time translators for the Inkscape project.
Do you guys know if the Inkscape project has some kind of official documentation/book/guide/wiki?
I stumbled upon www.gitbook.com http://www.gitbook.com and am using it for a couple of years now and I love it. Do you guys think this is feasible at some level?
Just wanted to share some new ideas and insights on possible improvements on the project.
Your thoughs and ideas are more than welcome!
--Victor Westmann
Le 04/04/2017 à 02:17, Duarte Ramos a écrit :
Never even got into documentation, or UI, not very familiar with that as far as I know Inkscape documentation resides in the Official Wiki http://wiki.inkscape.org/wiki/index.php/Inkscape, which I believe combines both manual, wiki, documentation and development info.
The wiki is somewhat frozen now as we are planning to move the documentation to GitLab.
I don't know how it would fit into existing documentation, or if would create too fragmentation by scattering information, but it could work.
We are planning to leave the wiki so we can choice another platform. The wiki using MediaWiki doesn’t really serve our needs.
Like most things in Open Source projects, I guess it's success would depend more on having active quality contributors, rather than the underlying system or platform used.
I agree — :). But it could help — ;). -- Sylvain
On Tue, Apr 4, 2017 at 2:19 AM, Victor Westmann wrote:
Hi Maren and Duarte,
I know you guys are long time translators for the Inkscape project.
Do you guys know if the Inkscape project has some kind of official documentation/book/guide/wiki?
Not exactly official, but originally written by some of the project's contributors.
http://write.flossmanuals.net/inkscape/about-inkscape/
AFAIK, the French version is supposed to be more up-to-date.
Alex
Hi,
Exactly the french version is up to date. https://www.flossmanualsfr.net/initiation-inkscape/
but in french.
And booktype only need an account and a browser.
Regards
2017-04-04 15:13 GMT+02:00 Alexandre Prokoudine < alexandre.prokoudine@...5...>:
On Tue, Apr 4, 2017 at 2:19 AM, Victor Westmann wrote:
Hi Maren and Duarte,
I know you guys are long time translators for the Inkscape project.
Do you guys know if the Inkscape project has some kind of official documentation/book/guide/wiki?
Not exactly official, but originally written by some of the project's contributors.
http://write.flossmanuals.net/inkscape/about-inkscape/
AFAIK, the French version is supposed to be more up-to-date.
Alex
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
Le 06/04/2017 à 16:35, Elisa Godoy de Castro Guerra a écrit :
Exactly the french version is up to date. https://www.flossmanualsfr.net/initiation-inkscape/
(Re)published January 30th, 2015.
Le 06/04/2017 à 02:37, Maren Hachmann a écrit :
I'd also suggest looking into flossmanuals, maybe make an account and see how it works. Sylvain, you've been doing some work there, I believe?
Yeah, I wanted to review the French book (to update/improve the screenshots, fix the spelling, improve the language and terms) but it is very long and it’s not very funny alone… We once thought about doing it with Hinerangi, but apparently she does not have time for it.
An English translation is started and no body works on it: https://fr.flossmanuals.net/start-with-inkscape/
Kind regards, -- Sylvain
Hi there,
I checked the Blender manual again and it uses Sphinx. It supports multiple translations and people are able to download the manual for offline use, which is great.
The only things that worry me are that it would be difficult to deal with images on different languages. I believe that we could set as the default manual language the English language since it is the most widely accepted and supported in software.
I was just wondering if new languages, based on the English manual, would use Inkscape images in English or if they would like to retake the same screenshots in different languages? In the Blender manual they kept everything in English even if the manual is written in German or Spanish.
I found a very good website with a lot of documentation research already done: https://github.com/PharkMillups/beautiful-docs#generating-docs
Will start my research from there.
--Victor Westmann
2017-04-06 8:24 GMT-07:00 Sylvain Chiron <chironsylvain@...364...>:
Le 06/04/2017 à 16:35, Elisa Godoy de Castro Guerra a écrit :
Exactly the french version is up to date. https://www.flossmanualsfr.net/initiation-inkscape/
(Re)published January 30th, 2015.
Le 06/04/2017 à 02:37, Maren Hachmann a écrit :
I'd also suggest looking into flossmanuals, maybe make an account and see how it works. Sylvain, you've been doing some work there, I believe?
Yeah, I wanted to review the French book (to update/improve the screenshots, fix the spelling, improve the language and terms) but it is very long and it’s not very funny alone… We once thought about doing it with Hinerangi, but apparently she does not have time for it.
An English translation is started and no body works on it: https://fr.flossmanuals.net/start-with-inkscape/
Kind regards,
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 https://lists.sourceforge.net/lists/listinfo/inkscape-translator
Le 06/04/2017 à 19:06, Victor Westmann a écrit :
I was just wondering if new languages, based on the English manual, 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
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.
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:
1. 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)
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.
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?
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?
--Victor Westmann
2017-04-07 14:42 GMT-07:00 Sylvain Chiron <chironsylvain@...364...>:
Le 06/04/2017 à 19:06, Victor Westmann a écrit :
I was just wondering if new languages, based on the English manual, 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 https://lists.sourceforge.net/lists/listinfo/inkscape-translator
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 English manual, > 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
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
Hi Victor,
those facts you researched here sound promising to me, and I very much like the jinja2 templates (because I'm using this for my blog already, and because it's very similar to the system the django Inkscape website uses). Plugins sound cool, too, and I personally like that they're written in Python.
I think I might have enjoyed setting up readthedocs (which uses sphinx, and directly outputs the results as pdf, epub and html) using gitlab and https://readthedocs.org/, but it appears that discussion is moving towards a custom solution, and that I might not even take part in it at all (for licencing reasons).
I agree with you on the point that using one tool for both would save us a lot of work in learning the tool. I also agree with you that high visibility (instead of hiding in a Wiki) would be a benefit. Hosting in a non-Wiki repo would also make it easier to organize downloadable example files in a way we want.
The thing it's lacking is a good GUI, which is probably why Martin and Chris want to leverage the Gitlab Wiki for it.
Oh - wow: I just found out that the Gitlab file editor supports rst. Well, that changes things a bit, I think. Preview works. You can click on 'Edit' to be able to switch between source code and preview. So easy!
Here's an example: https://gitlab.com/Moini/inkscape-realscale-extension/blob/rest_test/test.rs...
Works like a charm and would solve the user interface issue. Sigh...
Kind Regards, Maren
Am 26.04.2017 um 05:42 schrieb Victor Westmann:
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/ 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... mailto: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: > > 1. 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...> > <mailto: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 English manual, > > 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> > <mailto: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> > <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 <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 <mailto:Inkscape-translator@lists.sourceforge.net> https://lists.sourceforge.net/lists/listinfo/inkscape-translator <https://lists.sourceforge.net/lists/listinfo/inkscape-translator>
Sorry, for those who haven't been following the discussion on inkscape-devel, and don't understand what mean entirely, please take a look at the threads titled "Any chance we can make some docs material? (targeting the moon)" on the devel mailing list. If you intend to write or translate a manual, you'd be very welcome to add your ideas to the pool.
Maren
[1] https://sourceforge.net/p/inkscape/mailman/inkscape-devel/?style=threaded
Am 30.04.2017 um 23:54 schrieb Maren Hachmann:
Hi Victor,
those facts you researched here sound promising to me, and I very much like the jinja2 templates (because I'm using this for my blog already, and because it's very similar to the system the django Inkscape website uses). Plugins sound cool, too, and I personally like that they're written in Python.
I think I might have enjoyed setting up readthedocs (which uses sphinx, and directly outputs the results as pdf, epub and html) using gitlab and https://readthedocs.org/, but it appears that discussion is moving towards a custom solution, and that I might not even take part in it at all (for licencing reasons).
I agree with you on the point that using one tool for both would save us a lot of work in learning the tool. I also agree with you that high visibility (instead of hiding in a Wiki) would be a benefit. Hosting in a non-Wiki repo would also make it easier to organize downloadable example files in a way we want.
The thing it's lacking is a good GUI, which is probably why Martin and Chris want to leverage the Gitlab Wiki for it.
Oh - wow: I just found out that the Gitlab file editor supports rst. Well, that changes things a bit, I think. Preview works. You can click on 'Edit' to be able to switch between source code and preview. So easy!
Here's an example: https://gitlab.com/Moini/inkscape-realscale-extension/blob/rest_test/test.rs...
Works like a charm and would solve the user interface issue. Sigh...
Kind Regards, Maren
Am 26.04.2017 um 05:42 schrieb Victor Westmann:
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/ 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... mailto: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: > > 1. 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...> > <mailto: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 English manual, > > 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> > <mailto: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> > <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 <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 <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
Hi Victor,
I've been thinking about rekindling that process, too, and have also already looked into a couple of different platforms - but none of them was able to fullfill all requirements, and I didn't want to build something home-made for this (can't maintain). Also, I currently lack the time to lead such an effort.
So, currently I can just confirm Sylvain and Alex:
- the Wiki is not a good place, it's going to be shut down in the long run, sadly.
- there is a Booktype instance, with a book that needs to be updated, which is hosted by flossmanuals, and can be used as a starting point. It could be edited any time, as far as I know.
Bryce suggested that we'd use the same system we use for the included tutorials, so we can also export to SVG. I don't really think that makes a lot of sense, though. It's great for 'interactive', hands-on tutorials, and it has the advantage of creating po files for easy translation, but it's difficult to edit the original files (and hard to compile the resulting documentation, as far as I understand).
Ideally, a manual platform would (in my opinion):
- use git for version control - use reStructured Text for markup - support translation (like: automatically mark translated pages as outdated, mix translated and untranslated contents if there is only a partial translation) - allow to include SVG images - allow for easy collaboration - supply an editor that makes it easy for non-coders to contribute - export to a couple of different file formats, including html, pdf, and one or more ebook formats - allow for the files in the git repo to be also edited directly, and be able to include the git repo in our own code repos. - be open source (of course)
I believe gitbook already fulfills a lot of those requirements, but I don't want to do self-hosting, if that can be avoided (but still want to have the option to export everything and go to a different place with the contents).
But there's also Booktype, Readthedocs, pure Sphinx and a lot more.
Would you like to investigate the different available systems and put up a comparison between them? You can also collect info/user experiences from other open source projects.
Kind Regards, Maren
Am 04.04.2017 um 01:19 schrieb Victor Westmann:
Hi Maren and Duarte,
I know you guys are long time translators for the Inkscape project.
Do you guys know if the Inkscape project has some kind of official documentation/book/guide/wiki?
I stumbled upon www.gitbook.com http://www.gitbook.com and am using it for a couple of years now and I love it. Do you guys think this is feasible at some level?
Just wanted to share some new ideas and insights on possible improvements on the project.
Your thoughs and ideas are more than welcome!
--Victor Westmann
Hi Duarte, Sylvain, Alexandre, and Maren,
Thank you for your reply.
Duarte: I agree. We need to make volunteers engaged in the documentation. At least in the User Guide/UI doc.
Sylvain: Do you think the current wiki does not serve our needs for what particular reason? I would love to propose a separate repository -- or at least (one or two) folder(s) inside the main project -- for user guide doc and developer docs. I strongly believe we need to make these processes crystal clear and, as much as possible, give incentives for people to get involved in solving things they don't like (bugs or minor issues).
Alexandre: I think this is a great manual! The only setbacks, IMO, are the fact that we cannot download it in any format (HTML, PDF) and that we cannot translate it to other languages (even though this process can be difficult to engage people from time to time). I believe that this manual is a good model for us to follow. Good call.
Sylvain: I really enjoy the way Blender (https://docs.blender.org/ manual/en/dev/index.html) and Axialis (company that sells windows products) makes their help/tutorial files: http://www.axialis.com/ tutorials/tutorial-iw012.html
So what we're looking here is:
Git integration, SVG compatibility, Multiple output formats, Localization Collaboration Simple to use Markup language ...
Challenge accepted! :)
--Victor Westmann
2017-04-04 10:28 GMT-07:00 Maren Hachmann <maren@...325...>:
Hi Victor,
I've been thinking about rekindling that process, too, and have also already looked into a couple of different platforms - but none of them was able to fullfill all requirements, and I didn't want to build something home-made for this (can't maintain). Also, I currently lack the time to lead such an effort.
So, currently I can just confirm Sylvain and Alex:
- the Wiki is not a good place, it's going to be shut down in the long
run, sadly.
- there is a Booktype instance, with a book that needs to be updated,
which is hosted by flossmanuals, and can be used as a starting point. It could be edited any time, as far as I know.
Bryce suggested that we'd use the same system we use for the included tutorials, so we can also export to SVG. I don't really think that makes a lot of sense, though. It's great for 'interactive', hands-on tutorials, and it has the advantage of creating po files for easy translation, but it's difficult to edit the original files (and hard to compile the resulting documentation, as far as I understand).
Ideally, a manual platform would (in my opinion):
- use git for version control
- use reStructured Text for markup
- support translation (like: automatically mark translated pages as
outdated, mix translated and untranslated contents if there is only a partial translation)
- allow to include SVG images
- allow for easy collaboration
- supply an editor that makes it easy for non-coders to contribute
- export to a couple of different file formats, including html, pdf, and
one or more ebook formats
- allow for the files in the git repo to be also edited directly, and be
able to include the git repo in our own code repos.
- be open source (of course)
I believe gitbook already fulfills a lot of those requirements, but I don't want to do self-hosting, if that can be avoided (but still want to have the option to export everything and go to a different place with the contents).
But there's also Booktype, Readthedocs, pure Sphinx and a lot more.
Would you like to investigate the different available systems and put up a comparison between them? You can also collect info/user experiences from other open source projects.
Kind Regards, Maren
Am 04.04.2017 um 01:19 schrieb Victor Westmann:
Hi Maren and Duarte,
I know you guys are long time translators for the Inkscape project.
Do you guys know if the Inkscape project has some kind of official documentation/book/guide/wiki?
I stumbled upon www.gitbook.com http://www.gitbook.com and am using it for a couple of years now and I love it. Do you guys think this is feasible at some level?
Just wanted to share some new ideas and insights on possible improvements on the project.
Your thoughs and ideas are more than welcome!
--Victor Westmann
Being mainly a Blender user I can only say good things about Blender manual. I think it is a Sphinx based system, and works quite well. Then again I still feel its success mostly stems from the amount of work and effort from the developers that went into building it, rather that the platform itself.
I do like that the sphinx system allows (I believe) a searchable, downloadable offline format for local use. Think packing the manual along with the Inkscape release for local use.
On 04-04-2017 19:31, Victor Westmann wrote:
Hi Duarte, Sylvain, Alexandre, and Maren,
Thank you for your reply.
Duarte: I agree. We need to make volunteers engaged in the documentation. At least in the User Guide/UI doc.
Sylvain: Do you think the current wiki does not serve our needs for what particular reason? I would love to propose a separate repository -- or at least (one or two) folder(s) inside the main project -- for user guide doc and developer docs. I strongly believe we need to make these processes crystal clear and, as much as possible, give incentives for people to get involved in solving things they don't like (bugs or minor issues).
Alexandre: I think this is a great manual! The only setbacks, IMO, are the fact that we cannot download it in any format (HTML, PDF) and that we cannot translate it to other languages (even though this process can be difficult to engage people from time to time). I believe that this manual is a good model for us to follow. Good call.
Sylvain: I really enjoy the way Blender (https://docs.blender.org/manual/en/dev/index.html https://docs.blender.org/manual/en/dev/index.html) and Axialis (company that sells windows products) makes their help/tutorial files: http://www.axialis.com/tutorials/tutorial-iw012.html http://www.axialis.com/tutorials/tutorial-iw012.html
So what we're looking here is:
Git integration, SVG compatibility, Multiple output formats, Localization Collaboration Simple to use Markup language ...
Challenge accepted! :)
--Victor Westmann
2017-04-04 10:28 GMT-07:00 Maren Hachmann <maren@...325... mailto:maren@...325...>:
Hi Victor, I've been thinking about rekindling that process, too, and have also already looked into a couple of different platforms - but none of them was able to fullfill all requirements, and I didn't want to build something home-made for this (can't maintain). Also, I currently lack the time to lead such an effort. So, currently I can just confirm Sylvain and Alex: - the Wiki is not a good place, it's going to be shut down in the long run, sadly. - there is a Booktype instance, with a book that needs to be updated, which is hosted by flossmanuals, and can be used as a starting point. It could be edited any time, as far as I know. Bryce suggested that we'd use the same system we use for the included tutorials, so we can also export to SVG. I don't really think that makes a lot of sense, though. It's great for 'interactive', hands-on tutorials, and it has the advantage of creating po files for easy translation, but it's difficult to edit the original files (and hard to compile the resulting documentation, as far as I understand). Ideally, a manual platform would (in my opinion): - use git for version control - use reStructured Text for markup - support translation (like: automatically mark translated pages as outdated, mix translated and untranslated contents if there is only a partial translation) - allow to include SVG images - allow for easy collaboration - supply an editor that makes it easy for non-coders to contribute - export to a couple of different file formats, including html, pdf, and one or more ebook formats - allow for the files in the git repo to be also edited directly, and be able to include the git repo in our own code repos. - be open source (of course) I believe gitbook already fulfills a lot of those requirements, but I don't want to do self-hosting, if that can be avoided (but still want to have the option to export everything and go to a different place with the contents). But there's also Booktype, Readthedocs, pure Sphinx and a lot more. Would you like to investigate the different available systems and put up a comparison between them? You can also collect info/user experiences from other open source projects. Kind Regards, Maren Am 04.04.2017 um 01:19 schrieb Victor Westmann: > Hi Maren and Duarte, > > I know you guys are long time translators for the Inkscape project. > > Do you guys know if the Inkscape project has some kind of official > documentation/book/guide/wiki? > > I stumbled upon www.gitbook.com <http://www.gitbook.com> <http://www.gitbook.com> and am using it > for a couple of years now and I love it. Do you guys think this is > feasible at some level? > > Just wanted to share some new ideas and insights on possible > improvements on the project. > > Your thoughs and ideas are more than welcome! > > > --Victor Westmann >
Am 04.04.2017 um 20:31 schrieb Victor Westmann:
Hi Duarte, Sylvain, Alexandre, and Maren,
Thank you for your reply.
Duarte: I agree. We need to make volunteers engaged in the documentation. At least in the User Guide/UI doc.
Sylvain: Do you think the current wiki does not serve our needs for what particular reason? I would love to propose a separate repository -- or at least (one or two) folder(s) inside the main project -- for user guide doc and developer docs. I strongly believe we need to make these processes crystal clear and, as much as possible, give incentives for people to get involved in solving things they don't like (bugs or minor issues).
Alexandre: I think this is a great manual! The only setbacks, IMO, are the fact that we cannot download it in any format (HTML, PDF) and that we cannot translate it to other languages (even though this process can be difficult to engage people from time to time). I believe that this manual is a good model for us to follow. Good call.
Sylvain: I really enjoy the way Blender (https://docs.blender.org/manual/en/dev/index.html https://docs.blender.org/manual/en/dev/index.html) and Axialis (company that sells windows products) makes their help/tutorial files: http://www.axialis.com/tutorials/tutorial-iw012.html http://www.axialis.com/tutorials/tutorial-iw012.html
Some random thoughts:
- The blender thing looks like a readthedocs instance to me. They seem to have set up their own readthedocs server (which I'd really like a lot... but can't do. Of course there is free (?) hosting at readthedocs).
What I couldn't find for readthedocs was the option to edit the pages from the website interface, with a graphical editor that will help with correct formatting. This isn't an issue for developer documentation, they are used to pulling from a git repo, editing using an editor on their desktop, testing locally and pushing back. But for user docs where users can contribute, it's a relevant hurdle, I believe.
Does anyone know if readthedocs has a graphical, online-editing tool, which I just wasn't able to find?
OTOH, I think gitlab has a markdown editor with preview. Does it have one for reST, too?
Funny enough, readthedocs uses django. And the inkscape.org website uses django, too... Probably it would be hard to integrate one into the other, but that would be really, really cool...
So what we're looking here is:
Git integration, SVG compatibility, Multiple output formats, Localization Collaboration Simple to use Markup language
...
Challenge accepted! :)
- Yay :-D
Maren
--Victor Westmann
2017-04-04 10:28 GMT-07:00 Maren Hachmann <maren@...325... mailto:maren@...325...>:
Hi Victor, I've been thinking about rekindling that process, too, and have also already looked into a couple of different platforms - but none of them was able to fullfill all requirements, and I didn't want to build something home-made for this (can't maintain). Also, I currently lack the time to lead such an effort. So, currently I can just confirm Sylvain and Alex: - the Wiki is not a good place, it's going to be shut down in the long run, sadly. - there is a Booktype instance, with a book that needs to be updated, which is hosted by flossmanuals, and can be used as a starting point. It could be edited any time, as far as I know. Bryce suggested that we'd use the same system we use for the included tutorials, so we can also export to SVG. I don't really think that makes a lot of sense, though. It's great for 'interactive', hands-on tutorials, and it has the advantage of creating po files for easy translation, but it's difficult to edit the original files (and hard to compile the resulting documentation, as far as I understand). Ideally, a manual platform would (in my opinion): - use git for version control - use reStructured Text for markup - support translation (like: automatically mark translated pages as outdated, mix translated and untranslated contents if there is only a partial translation) - allow to include SVG images - allow for easy collaboration - supply an editor that makes it easy for non-coders to contribute - export to a couple of different file formats, including html, pdf, and one or more ebook formats - allow for the files in the git repo to be also edited directly, and be able to include the git repo in our own code repos. - be open source (of course) I believe gitbook already fulfills a lot of those requirements, but I don't want to do self-hosting, if that can be avoided (but still want to have the option to export everything and go to a different place with the contents). But there's also Booktype, Readthedocs, pure Sphinx and a lot more. Would you like to investigate the different available systems and put up a comparison between them? You can also collect info/user experiences from other open source projects. Kind Regards, Maren Am 04.04.2017 um 01:19 schrieb Victor Westmann: > Hi Maren and Duarte, > > I know you guys are long time translators for the Inkscape project. > > Do you guys know if the Inkscape project has some kind of official > documentation/book/guide/wiki? > > I stumbled upon www.gitbook.com <http://www.gitbook.com> <http://www.gitbook.com> and am using it > for a couple of years now and I love it. Do you guys think this is > feasible at some level? > > Just wanted to share some new ideas and insights on possible > improvements on the project. > > Your thoughs and ideas are more than welcome! > > > --Victor Westmann >
Le 04/04/2017 à 20:31, Victor Westmann a écrit :
Sylvain: Do you think the current wiki does not serve our needs for what particular reason?
A too complex interface, I think it’s the main reason. The community seems to agree that it should be replaced. But above all it lacks maintainers, of course.
Challenge accepted! :)
This should probably be discussed on inkscape-devel…
Le 05/04/2017 à 14:57, Maren Hachmann a écrit :
OTOH, I think gitlab has a markdown editor with preview. Does it have one for reST, too?
There seems to be for files but not for wikis. https://gitlab.com/gitlab-org/gitlab-ce/issues/12948 -- Sylvain
Hi Maren, Sylvain,
Maren, agreed. We need to have something, if possible, for the users to edit on the browser. Let's try to search for this one. Sylvain, it's just a research on possible tools. What harm does it cause?
One question though: is it ok that the doc tool/system/platform is independent of the project hosted place? Gitlab. Does it have to be in Gitlab or is it ok if we search options like GitHub and other services/tools?
--Victor Westmann
2017-04-05 8:56 GMT-07:00 Sylvain Chiron <chironsylvain@...364...>:
Le 04/04/2017 à 20:31, Victor Westmann a écrit :
Sylvain: Do you think the current wiki does not serve our needs for what particular reason?
A too complex interface, I think it’s the main reason. The community seems to agree that it should be replaced. But above all it lacks maintainers, of course.
Challenge accepted! :)
This should probably be discussed on inkscape-devel…
Le 05/04/2017 à 14:57, Maren Hachmann a écrit :
OTOH, I think gitlab has a markdown editor with preview. Does it have one for reST, too?
There seems to be for files but not for wikis. https://gitlab.com/gitlab-org/gitlab-ce/issues/12948 -- 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 https://lists.sourceforge.net/lists/listinfo/inkscape-translator
Le 05/04/2017 à 21:26, Victor Westmann a écrit :
Sylvain, it's just a research on possible tools. What harm does it cause?
Well, yes, you can discuss later…
One question though: is it ok that the doc tool/system/platform is independent of the project hosted place? Gitlab. Does it have to be in Gitlab or is it ok if we search options like GitHub and other services/tools?
GitHub is closed source thus it is out.
It would probably be better on GitLab, or even better: integrated in the website. I think your creativity should decide here — :). -- Sylvain
Am 05.04.2017 um 21:26 schrieb Victor Westmann:
Hi Maren, Sylvain,
Maren, agreed. We need to have something, if possible, for the users to edit on the browser. Let's try to search for this one. Sylvain, it's just a research on possible tools. What harm does it cause?
- I believe this is very helpful. The developer / documentation community can benefit from the exploration - it doesn't limit choices, but provides info, so that people can make a choice, or at least have a base for a discussion.
To me, it makes more sense to present something like this to people when there is info in it.
But maybe moving to inkscape-docs makes sense? That's where others (Elisa, jazzynico) who have an interest in seeing a community-generated manual come to life, and who do have experience in creating manuals, might read it and join in, and contribute to the list of options.
One question though: is it ok that the doc tool/system/platform is independent of the project hosted place? Gitlab. Does it have to be in Gitlab or is it ok if we search options like GitHub and other services/tools?
- I don't know. I'd rule out github, because it has a low probability of being adopted, but exploring a diverse set of options, so there is something to compare, seems like a good idea to me. Focussing on the most promising candidates, maybe, and doing less exploring for the others?
I'd also suggest looking into flossmanuals, maybe make an account and see how it works. Sylvain, you've been doing some work there, I believe?
I've always been wanting to do a test run of readthedocs, maybe I'll get around to try it out with an extension that I've worked on.... But I'm not sure when I could get around to doing this, so don't wait for me, please.
Victor, there's also on the developer mailing list a discussion thread, where Bryce describes his 'optimal manual writing system', after I asked about different documentation systems: https://sourceforge.net/p/inkscape/mailman/message/35608481/ (that thread also explains about the Wiki going to be closed down)
Please let us know when/where you've started compiling a list of criteria, so we can join in adding any that appear useful, and then maybe can help with filling in the gaps.
Maren
--Victor Westmann
2017-04-05 8:56 GMT-07:00 Sylvain Chiron <chironsylvain@...364... mailto:chironsylvain@...364...>:
Le 04/04/2017 à 20:31, Victor Westmann a écrit : > Sylvain: Do you think the current wiki does not serve our needs for what > particular reason? A too complex interface, I think it’s the main reason. The community seems to agree that it should be replaced. But above all it lacks maintainers, of course. > Challenge accepted! :) This should probably be discussed on inkscape-devel… Le 05/04/2017 à 14:57, Maren Hachmann a écrit : > OTOH, I think gitlab has a markdown editor with preview. Does it have > one for reST, too? There seems to be for files but not for wikis. https://gitlab.com/gitlab-org/gitlab-ce/issues/12948 <https://gitlab.com/gitlab-org/gitlab-ce/issues/12948> -- 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
participants (6)
-
Alexandre Prokoudine -
Duarte Ramos -
Elisa Godoy de Castro Guerra -
Maren Hachmann -
Sylvain Chiron -
Victor Westmann