Am 08.05.2017 um 13:13 schrieb brynn: > Oh, thank you so much for explaining it! Well I'll get subscribed on > FLOSS and give the editing a test. > > And I'll also read through your notes now, and share comments about the > other options, if I have any that are different from yours. > >> However, it lacks some features that > would be very useful for us, e.g. customization, versioning with undo, > support for different software versions and languages. > > Versioning? I thought the whole point of a manual which the community > can maintain, would be to have A manual, which is theoretically always > being edited (although more around Inkscape release times) and always up > to date. Do you mean that if people wanted to print as an ebook or > download PDF, those would have versions?
- I mean that we need to have a way to prepare a manual for the next release, while not showing those changes in the one that is publicly available. So, e.g. the fillet/chamfer lpe doesn't need to be explained in the manual for 0.91. Screenshots will also look different. But we may want to have the newer version ready on release, so it could be included with the software (long-term goal, not achievable for the next couple of versions at least, I think). Also, as we both know, people may use different versions, and will not want to read the wrong instructions. > Languages? It seems like FLOSS does provide support for, well, at least > 2 different languages, case in point, the French version which is being > translated. Do you mean some kind of automatic translation? - No, I mean that I would like to have multiple languages in one place, not in two completely separate places, as it is with Booktype. This is so they could share screenshots, and images. Chapters that are not translated will have a fallback in English. So partial translations would also make sense, and the untranslated parts would always be kept in sync with the English ones (because they *are* the English ones, which are shown when a translation of that file is missing). Take a look at the django documentation to see how it's organized. You can select different language and program versions there in the overlayed numbers at the bottom right: https://docs.djangoproject.com/en/1.10/topics/i18n/translation/ Maren > Thanks again, > brynn > > > -----Original Message----- From: Maren Hachmann > Sent: Sunday, May 07, 2017 2:54 PM > To: brynn ; C R ; Inkscape Devel List ; Inkscape-Docs > Subject: Re: [Inkscape-devel] Any chance we can make some docs material? > (targeting the moon) > > Am 05.05.2017 um 16:04 schrieb brynn: >> Hi Maren and all, >> I appreciate your research into, and review of.....well I don't >> even understand what this is. >> >> Could someone give me a simple explanation? I'm still thinking >> "translate French FLOSS manual" and then update and expand the >> translation as a FLOSS doc. I don't think we should abandon that, after >> all the work that Sylvain and Hineringi have put in. Not to forget the >> French team too. > > - Yes, that would be one of the options (the last one in the list I > posted). > But there are more ways to write documentation, especially if you're > dealing with maintaining different versions of the software (and thus > the manual) in parallel, and different languages. > > I'm not suggesting abandoning that book. On the contrary, yesterday I've > translated one more short chapter (and found the editor to be less > comfortable than the one we have on our django website, esp. for > inserting files/pictures), and I've just sent out a private email to > Hinerangi, because I think she might not be listening here currently, > but we'd need her consent for a licence change from GPL (which is > generally deemed unsuitable for documentation) to a CC licence. > > But it would be entirely possible to manage the book's contents on a > different website, using a different system. > >> Are we moving away from FLOSS because of its license? This is a >> fine point which I don't get. Could someone make this simple for me, >> too? > > - No, the licence discussion is not related to the discussion about > finding a suitable editing platform. > > The website where the book lives currently, flossmanualsfr.com, is a > fine website for writing books. However, it lacks some features that > would be very useful for us, e.g. customization, versioning with undo, > support for different software versions and languages. > > Likewise, the other suggested platforms lack features (especially in > contributor-usability), and there exist other platforms that people may > know about. > > I was hoping to get some input on what is more important to people. To > me as someone who would probably be working on the more organizational > side, the frontend doesn't matter so much. I'm used to doing my editing > in a text editor, and to use a preview. I'm also used to > installing/running software on my computer, for testing my edits locally > (which wouldn't be mandatory, though - a website that allows to edit the > texts is available for each of the items on the list). What matters to > me is that it is easy to have multiple versions and translations > available, and to be able to automate the process. Also, to allow people > who aren't involved in the project yet to do quick edits and request > their inclusion into the manual. And to have a highly customizable > output - concerning output formats (ebook formats, html, pdf, maybe even > an 'app'), and styling of those (which I think CR might enjoy). > > But I know that many of the possible editors might be afraid of the > gitlab workflow, and I wanted people to be able to take a look at the > different options. > > I've got one more platform to add to the list (as 'looked at, I'd > discourage usage'): > > *************** > > Gitbook > > WHAT: node.js-based modern toolchain to build docs from > markdown/Asciidoc (locally installable version available) - disclaimer: > didn't test, only read. > > PROS: > - comes with an editor that is graphical, and integrates support for > the version control part, so users do not need to worry about learning > git or finding their way around the git**b user interfaces. > - includes support for multiple language versions > - customizable templates / themes > - free hosting available > > CONS: > - the above mentioned editor is proprietary. There exists a > no-longer-in-development open source legacy version. > - free hosting limited to 5 contributors > - all in all (if you take away the limited hosting and the non-free > editor) similar to the readthedocs version, but building on a system I > wouldn't be able to deal with, userbase / maturity is probably a lot > smaller/less than the one of readthedocs/sphinx. > > Homepage: https://www.gitbook.com/ > Source repo example: https://github.com/GitbookIO/gitbook/tree/master/docs > Example web page: > https://www.gitbook.com/book/frontendmasters/front-end-handbook/details > > **************** > > Kind Regards, > Maren > >> Thanks, >> brynn >> >> -----Original Message----- From: Maren Hachmann >> Sent: Tuesday, May 02, 2017 5:59 PM >> To: C R ; Inkscape Devel List ; Inkscape-Docs >> Subject: Re: [Inkscape-devel] Any chance we can make some docs material? >> (targeting the moon) >> >> Hi, >> >> sorry for the delay. I've been trying things out a bit, and I feel I >> haven't seen enough yet, but I won't have time tomorrow, so posting >> anyway now. >> >> So, it seems that what we still need for a manual (any kind) is a >> platform to create it (not only write, but also output to different >> formats). >> >> I have had a chance to look at 3 different platforms on my list, and I'm >> trying to outline the pros and cons, as I perceive them, please add >> yours to the list. There are many more platforms in existance (see also: >> https://github.com/PharkMillups/beautiful-docs#generating-docs), and if >> anyone here has some experience with them, please add. >> >> ************* >> >> - Gitlab Wiki + X, as suggested by Martin. >> >> WHAT: An online Wiki on gitlab with a source code editor, associated >> with a gitlab project. >> >> PROS: >> - custom-made to suit the project's individual needs (no specifics >> yet) >> - Preview functionality >> >> CONS: >> - only (limited set of) Markdown, RDoc or AsciiDoc >> - limited formatting options, formatting not so much about 'roles' >> of formatted text, but more about 'looks' >> - the backend isn't written yet >> - no option for branches via interface (so we could start writing >> for trunk, and continue fixing for stable) >> - no direct translation support >> - support for the backend depends upon a single individual, no user >> community >> - no WYSIWYG editor >> - no GUI access to git repo, for managing where to put uploaded >> files etc. >> - no GUI for undoing a change (like in a 'normal' Wiki), or looking >> at a diff >> >> EXAMPLE (frontend): https://gitlab.com/inkscape/inkscape-web/wikis/home >> >> ************* >> >> - Gitlab Editor + Sphinx / readthedocs: >> >> WHAT: A git repository with an online source code editor and >> documentation update on readthedocs.org on save (i.e. commit). >> >> PROS: >> - available quickly (didn't know how it works exactly, but got it >> all up and running with test content within an evening) >> - uses git and reStructured Text >> - allows to have branches, so devel version features can be >> documented when they are coded >> - supports translations (not entirely sure how, though, haven't >> tested it yet, wanted to send this email instead. E.g. Django docs are >> translated. Fallback to English if no translation of a document. I think >> they use different branches.) >> - free theming, separately for each output format >> - free hosting, can also use our own domain name with >> readthedocs.org, e.g. docs.inkscape.org >> - after installing some programs, tool chain runs locally >> - preview via gitlab editor or local editor >> - same toolchain can be used for developer documentation (includes >> code documentation from docstrings) >> - extensible via plugins (haven't had a chance to take a closer look >> yet or test any) >> - I think it's possible to add a 'edit this page on gitlab' link to >> each page, to get new contributors, even when using readthedocs.org (not >> tested, but read that others did similar things) >> - extremely wide range of export formats via plugins >> - infinite hierarchy nesting >> - syntax highlighting (e.g. for command line usage instructions, or >> extension writers) >> - video embedding (not tested) >> >> CONS: >> - learning curve for admin (theming, plugins,...) >> - learning curve for editors (syntax, workflow) >> - no WYSIWYG editor, only preview (incomplete, because doesn't >> support all sphinx stuff) >> >> EXAMPLE: >> - repository: >> https://gitlab.com/Moini/inkscape-extensions-multi-bool/tree/master/docs >> - rendered documentation: >> http://inkscape-multi-bool-extension.readthedocs.io/en/latest/index.html >> >> ************* >> >> - Booktype: >> >> WHAT: A web portal for creating books, hosted by friends of the Inkscape >> project. >> >> PROS: >> - available right now, no further setup required >> - best interface by far, easy and intuitive to use >> - team functions, user roles, chat >> - prevents concurrent editing >> - wide range of export and import formats >> - support for themes/settings for specific export formats (e.g. >> different font sizes etc.) >> - free hosting and maintenance via flossmanuals(fr) >> - community of experienced documentors >> >> CONS: >> - confinement to django database for version control, more difficult >> to get data out of it again for editing >> - no direct translation support (make a copy of the book, copy >> changes over after doing a comparison in the history) >> - limited versioning support (only the latest one can be >> edited) >> - we'd need to ask someone to add CC-By-SA licence (currently, the >> options I got were CC-By, GPL. I guess this would be quick and easy to >> solve.) >> >> EXAMPLE (rendered documentation): >> https://www.flossmanualsfr.net/initiation-inkscape/ >> >> ************* >> >> All of them would be FLOSS, have support for internal linking, allow to >> insert images and allow editing via browser. >> >> ************* >> >> I wish it were possible to combine the ease of use of the booktype >> frontend with the portability, branch support, sustainability and >> versatility of the gitlab/sphinx/readthedocs backend... >> >> (In German that's called the 'eierlegende Wollmilchsau' - egg-laying >> wool- and milk-giving pig...) >> >> For the sphinx option, I believe I'd be able to take on the first setup >> and some of the tasks that come with customization and extending, as >> well as basic maintenance. For Booktype, anyone of the documentation >> writers could do that easily. >> >> Regards, >> Maren >> >> >> >> >> ------------------------------------------------------------------------------ >> >> >> Check out the vibrant tech community on one of the world's most >> engaging tech sites, Slashdot.org! http://sdm.link/slashdot >> _______________________________________________ >> Inkscape-devel mailing list >> inkscape-de...@lists.sourceforge.net >> https://lists.sourceforge.net/lists/listinfo/inkscape-devel >> > ------------------------------------------------------------------------------ Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot _______________________________________________ Inkscape-docs mailing list Inkscape-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-docs
