Hi Brynn, indeed, you got the wrong book, Brynn. Just wait a day or two (or however long it'll take to contact Mick and get a couple of things sorted out), then you'll see. We're definitely going to need someone who renames the images that will be in that book. You don't need to work on it yet.
> -- Not so silly. - Oh :) > -- Since we already do have the technical style of manual, outdated > though it may be, I would suggest getting the new one finished and > published first. - I agree. > -- Perhaps Tav would consider releasing the content of his current > manual, to be used as a starting point for the technical one? - I already had asked him about this, and, AFAIR, his answer went into the direction of 'This may be difficult to do (because the book is copyrighted and a publisher holds the rights), don't count on it ever happening. Rather start something new.' > -- Likely certain people would be better suited for writing this more > technical one. I know for myself, I couldn't write it, no matter how > hard I tried. Often I find myself writing in simple language, even when > I know the reader doesn't need it simplified. Must be in my DNA, haha. - There may be others reading it, aside from the person who asked. > -- I wonder if having 2 manuals would be confusing for users? I think > as long as the titles of the manuals makes it very clear, it would be > ok. Such as Introduction to Inkscape for the beginnners' manual or > Technical Inkscape Manual for the other. Something like that. (And > also make sure the URLs include the distinction, so searching isn't > confusing either.) - Yes, I agree 100%. > Somewhat random thought. I guess both Floss Manuals and Booktypes can > be themed or branded? Perhaps at some time during this > manual-translating and then writing process, the community can have a > discussion about Inkscape branding? I'm not sure if we can say it's > overdue, but I would suggest that the time has come :-) - flossmanuals does appear to have an option for adding some kind of home page. It seems to be a bit complicated, but possible. Not so much for branding the book, there are three themes to choose from, which is an experimental option (and I haven't tested). But as it's html, it may be possible to do some post-processing... (*This* kind of thing is a lot more controllable with readthedocs/Sphinx.) It's not very high priority, though. However, it would be extremely cool if we could manage to have a pdf or a set of web pages ready for inclusion in one of the next Inkscape versions this year. Maren Am 12.05.2017 um 08:00 schrieb brynn: >> (Btw. what do you think of helping with the translation by making sure > that all images get uploaded? When I copy-paste from the French book, I > get all the images, but they are just links to the original book, not > part of the one I'm editing. And it takes quite some time to rename the > files to something English, upload, add a useful placeholder text and > then exchange the links. I'd prefer to spend that time on translating.) > > Sure, if I'm just taking the images from one and putting into the other, > I could do that. I just didn't like the idea of making new screenshots, > using my theme. Although, at least the images I've looked at so far, > already have English names. > > Hhmm.... Hopefully Sylvain can answer the questions I asked about the > work that has been done to date. (in a different message) > (https://sourceforge.net/p/inkscape/mailman/message/35828296/) Could I > be looking at the wrong documents? Besides different chapters, I'm > seeing vastly different content between the French and the translated > English. It's not just translated, it appears to be entirely rewritten, > and also using completely different images! > > I might think I was mistakenly looking at the original Inkscape Floss > Manual, except both of the ones I'm looking are on the fr subdomain. > Let's get this straightened out, so I'm working on the right documents. > So using "L'outil Sélecteur", which is Selection Tool, right? To me, > this page: > > https://fr.flossmanuals.net/start-with-inkscape/select-tool/ > > is not just a translation of > > https://fr.flossmanuals.net/inkscape/selector-tool-a/ > > I certainly don't mind editing the pages that are already translated, to > put the same images from the French manual, but I'd have to make major > text edits too. (Or we, or whomever.) > > Surely one of the 2 I'm looking at is the wrong one? > > > Re: "silly idea" Some comments. > > -- Not so silly. > -- Since we already do have the technical style of manual, outdated > though it may be, I would suggest getting the new one finished and > published first. > -- Perhaps Tav would consider releasing the content of his current > manual, to be used as a starting point for the technical one? > -- Likely certain people would be better suited for writing this more > technical one. I know for myself, I couldn't write it, no matter how > hard I tried. Often I find myself writing in simple language, even when > I know the reader doesn't need it simplified. Must be in my DNA, haha. > -- I wonder if having 2 manuals would be confusing for users? I think > as long as the titles of the manuals makes it very clear, it would be > ok. Such as Introduction to Inkscape for the beginnners' manual or > Technical Inkscape Manual for the other. Something like that. (And > also make sure the URLs include the distinction, so searching isn't > confusing either.) > > >> (btw. I have volunteered to set this up, seems you overlooked ;-) - for > customization, translation and version branches, I'd still have to learn > a bit, but it doesn't appear to be too hard). > > No, I read it. But since I was "voting" for the Booktype option, I > didn't have any reason to make a comment about setting up the Sphinx > option. > > I sincerely hope I have a wrong manual that I'm looking at, and that we > don't have a serious problem with the translation being not strictly a > translation! > > Somewhat random thought. I guess both Floss Manuals and Booktypes can > be themed or branded? Perhaps at some time during this > manual-translating and then writing process, the community can have a > discussion about Inkscape branding? I'm not sure if we can say it's > overdue, but I would suggest that the time has come :-) > > All best, > brynn > > -----Original Message----- From: Maren Hachmann > Sent: Wednesday, May 10, 2017 5:07 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) > > @jazznico: Is there a way to transfer books between the French > flossmanuals site and the English one? I.e. would it be possible to > export and import a book? Or would it be possible to have a language > selection menu on flossmanualsfr instead, with English available for > selection? This would make it easier for our international editors to > deal with the interface. > > Hi Brynn, > > thanks for taking a closer look! (I'm so glad someone was able to take > the time for this.) > > FLOSS is the abbreviation for 'Free/Libre Open Source Software'. > The websites are flossmanualsfr.net / flossmanuals.net respectively. > They allow for collaborative writing of manuals for FLOSS. > > I fully understand the need for a WYSIWYG editor. The one from Booktype > is quite okay. Where it lacks is when you want to insert a file or image > - because you need to upload it first, then you need to find out that > the link to it that you need to enter in the insertion dialog is > '/static/filename.ext'. That's more difficult than it would need to be > (but you can use the same image file on different pages this way). > > (Btw. what do you think of helping with the translation by making sure > that all images get uploaded? When I copy-paste from the French book, I > get all the images, but they are just links to the original book, not > part of the one I'm editing. And it takes quite some time to rename the > files to something English, upload, add a useful placeholder text and > then exchange the links. I'd prefer to spend that time on translating.) > > About the 'location', I've had this silly idea: > > As a first step, we create/translate/update this introductory manual at > flossmanuals (if possible at the English site, to make it easier for > contributors). It's a great way for getting people started with Inkscape. > > As a second step, or in parallel, we could also have a more > glossary-like, more technical manual, that explains what each menu item > /LPE/... does. This technical manual could also be used by developers to > document their changes, and it could use the more technical style with > Sphinx/reST/readthedocs. It could even start out simple, with keywords / > lists, and be refined by people who don't like those ;-) > > (btw. I have volunteered to set this up, seems you overlooked ;-) - for > customization, translation and version branches, I'd still have to learn > a bit, but it doesn't appear to be too hard). > > The one issue I see with this split is that it would spread resources > (us) a bit wide, maybe. But from the time when I started using Inkscape, > I know that having a manual like the one Elisa wrote would have helped > me a lot - I barely understood a word in Tav's manual. > > Now, as an advanced user, I (claim I) know everything that Elisa > explains, but Tav's more technical manual contains so much more info, > which I'm now able to understand (and often have the urge to update). > > So that's why I think that having two different manuals wouldn't be such > a bad idea. The technical manual could be written by the more technical > users and, hopefully, devs (when they change something). > > Well, just an idea. Let me know if you think it's crap ;-) > > Kind Regards, > Maren > > Am 10.05.2017 um 07:47 schrieb brynn: >> Hi Everyone, >> I've tried to read up and study and understand the info which >> Maren presented. Because my understanding is extremely limited, I >> hesitate to offer any comments at all. But for whatever it might be >> worth, here they are....along with a couple of questions. >> >> First, one of your last comments: >> >>> All of them would be FLOSS, have support for internal linking, allow to >> insert images and allow editing via browser. >> >> I think you're using "FLOSS" as a generic umbrella term, as >> opposed to the FLOSS Manuals, right? Because a couple of the Cons are >> lack of wysiwyg, which I've had the understanding Floss Manuals has >> (although I haven't seen it yet). So you don't mean that Floss Manuals >> can be used for the writing, for all of them, and then exported out or >> transfered elsewhere for publishing, right? >> >> Gitlab Wiki + X >> It seems to me like the lack of a wysiwyg editor is the most limiting >> factor (at least for as much as I understand). I'm just thinking of >> people who might be interested in joining the manual or documentation >> team. This is a good non-coding opportunity for non-programmers, to >> contribute to the project. They might be less likely to participate if >> they had to learn, even a simple language like Markdown, or whatever you >> call the code that wikis use. >> >> Gitlab Editor + Sphinx / readthedocs >> >>> - learning curve for admin (theming, plugins,...) >> >> You must mean that someone else besides Martin would be the admin for >> the manual project? Or, as admin for the gitlab account, is there >> something about this option that he would need to learn still? >> >> All the pros for this option make it sound so good (at least what I can >> understand). But still no wysiwyg editor. I still think that might >> scare away some potential contributors. >> >> Booktype >> >> So far, this sounds like the best option to me. >> >> Gitbook >> >> The 5 contributor limit for free hosting sounds untennable to me. >> >> So based on my feeble understanding of all this, I'd vote for >> Booktype. >> >> All best, >> 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
