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.rst > > 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 <ma...@goos-habermann.de >> <mailto:ma...@goos-habermann.de>>: >> >> 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 <chironsylv...@orange.fr >> <mailto:chironsylv...@orange.fr> >> > <mailto:chironsylv...@orange.fr <mailto:chironsylv...@orange.fr>>>: >> > >> > 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 > ------------------------------------------------------------------------------ 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
