Re: [darktable-dev] Introducing dtdocs
Thank you Hubert -- I hadn't realized that a considerable part of the manual was already rewritten. I'll wait for the new translation workflow then! J. Hubert Kowalski writes: > Hi Jeronimo, > > Take a look at https://elstoc.github.io/dtdocs/ - as you'll see the manual > there is reworded to be more concise and to the point without additional > fluff and all contributors so far took measures to ensure that language is > clear english (both maintainers are native english speakers), which IMO > makes it perfect for translation. That however comes at a cost of having to > reword/retranslate parts of manual. > > wt., 20 paź 2020 o 18:00 Jeronimo Pellegrini napisał(a): > >> Hi Mica, >> >> Thank you for the work on getting a more modern translation >> system. (And I'm really happy to see that Weblate is licensed as >> GPLv3!) >> >> I would certainly want to still work with Emacs; not necessarily >> with .po files. Just something that has an Emacs mode... >> (I'm willing to help write an Emacs mode, so long as I don't >> do that alone, because I'm quite overworked. I do have some >> experience with Emacs Lisp.) >> >> If I need to change to a different format and use a special >> update-weblate tool, that's ok! >> >> When you mention that part of the manual needs to be retranslated >> because it was rewritten, do you mean the parts that were changed >> in recent commits in git/master? If it is so, then I've been >> translating those as they come, and the whole thing should be >> up to date -- I hope. >> Or are those changes somewhere else (another git branch)? >> >> J. >> >> Mica Semrick writes: >> > Hi Jeronimo, >> > >> > Thank you for your all your work; last I had looked br_PT was the most >> > up-to-date. >> > >> > We haven't really defined exactly what the translation workflow will >> > look like, but if we get feedback from translators that they still want >> > to work with PO files, I know we can certainly accommodate that. >> > >> > Weblate can do nice things like use and keep a translation memory, >> > leverage machine translation, and who knows what else; I haven't had >> > time to fully dive into it yet. I am not aware of what emacs can do. >> > >> > I think a decent portion of the manual would need to be retranslated, as >> > a good chunk of it has been rewritten. As I mentioned previously, I can >> > make translation memories from the current PO files and import them into >> > weblate or make them available to you via some other means. Since there >> > are a lot of new writings, I don't think that the old translations will >> > match up very well. I'm open to exploring machine translation for a >> > first pass if you'd like to do that. >> > >> > I'm also open to any other suggestions you may have. >> > >> > Best, >> > Mica >> > >> > >> > On 10/19/20 3:44 AM, Jeronimo Pellegrini wrote: >> >> Hello, >> >> >> >> (I sent this from an email address different from the one >> >> registered in the mailing list and it didn't seem to be >> >> sent, so I'm sendingit again from the correct email. Sorry >> >> for any duplicates) >> >> >> >> I have been working on the pt_BR translation (of both darktable and >> >> its manual). I usually translate using po-mode in Emacs, but of >> >> course I can adapt to some extent. :) >> >> >> >> How much of my workflow would change? One thing that would be difficult >> >> for me is to translate directly on a web browser. I may be >> >> old-fashioned, but really, I never got to do any reasonable work >> >> on web interfaces. Will it still be possible to use an editor >> >> to do translation work? >> >> >> >> Also - would the darktable manual translation need to be re-entered >> >> or reworked? You mentioned that translated segments would be suggested, >> >> so I suppose the whole document would need to be entered again in >> >> weblate -- is this correct? >> >> >> >> Thanks, >> >> Jeronimo >> >> >> >> Mica Semrick writes: >> >> >> >>> Before we open translations on weblate, I will take the current PO >> >>> files, for both the application strings and the user guide, and make >> >>> translation memory files out of them. I can then import them into >> >>> weblate (PO editor also supports TMX files in recent versions), and if >> >>> possible, translated segments from the old manual will be suggested in >> >>> the dtdocs translation. I don't have high hopes for a lot of matches, >> >>> since quite a bit of dtdocs has been rewritten, and translations just >> >>> don't work like that. >> >>> >> >>> The other possibility is that we use machine translation for the first >> >>> round, then let translators edit that translation. We did machine >> >>> translation from one of AP's French articles to English, and I was not >> >>> impressed with the quality of the translation, but hey, we can always >> >>> give it another shot. >> >>> >> >>> On 10/17/20 3:12 PM, jys wrote: >> On Sat, Oct 17, 2020, at 09:34, Pascal Obry wrote: >> > >> > Probably a good move and I
Re: [darktable-dev] Introducing dtdocs
Hi Mica, Thank you for the work on getting a more modern translation system. (And I'm really happy to see that Weblate is licensed as GPLv3!) I would certainly want to still work with Emacs; not necessarily with .po files. Just something that has an Emacs mode... (I'm willing to help write an Emacs mode, so long as I don't do that alone, because I'm quite overworked. I do have some experience with Emacs Lisp.) If I need to change to a different format and use a special update-weblate tool, that's ok! When you mention that part of the manual needs to be retranslated because it was rewritten, do you mean the parts that were changed in recent commits in git/master? If it is so, then I've been translating those as they come, and the whole thing should be up to date -- I hope. Or are those changes somewhere else (another git branch)? J. Mica Semrick writes: > Hi Jeronimo, > > Thank you for your all your work; last I had looked br_PT was the most > up-to-date. > > We haven't really defined exactly what the translation workflow will > look like, but if we get feedback from translators that they still want > to work with PO files, I know we can certainly accommodate that. > > Weblate can do nice things like use and keep a translation memory, > leverage machine translation, and who knows what else; I haven't had > time to fully dive into it yet. I am not aware of what emacs can do. > > I think a decent portion of the manual would need to be retranslated, as > a good chunk of it has been rewritten. As I mentioned previously, I can > make translation memories from the current PO files and import them into > weblate or make them available to you via some other means. Since there > are a lot of new writings, I don't think that the old translations will > match up very well. I'm open to exploring machine translation for a > first pass if you'd like to do that. > > I'm also open to any other suggestions you may have. > > Best, > Mica > > > On 10/19/20 3:44 AM, Jeronimo Pellegrini wrote: >> Hello, >> >> (I sent this from an email address different from the one >> registered in the mailing list and it didn't seem to be >> sent, so I'm sendingit again from the correct email. Sorry >> for any duplicates) >> >> I have been working on the pt_BR translation (of both darktable and >> its manual). I usually translate using po-mode in Emacs, but of >> course I can adapt to some extent. :) >> >> How much of my workflow would change? One thing that would be difficult >> for me is to translate directly on a web browser. I may be >> old-fashioned, but really, I never got to do any reasonable work >> on web interfaces. Will it still be possible to use an editor >> to do translation work? >> >> Also - would the darktable manual translation need to be re-entered >> or reworked? You mentioned that translated segments would be suggested, >> so I suppose the whole document would need to be entered again in >> weblate -- is this correct? >> >> Thanks, >> Jeronimo >> >> Mica Semrick writes: >> >>> Before we open translations on weblate, I will take the current PO >>> files, for both the application strings and the user guide, and make >>> translation memory files out of them. I can then import them into >>> weblate (PO editor also supports TMX files in recent versions), and if >>> possible, translated segments from the old manual will be suggested in >>> the dtdocs translation. I don't have high hopes for a lot of matches, >>> since quite a bit of dtdocs has been rewritten, and translations just >>> don't work like that. >>> >>> The other possibility is that we use machine translation for the first >>> round, then let translators edit that translation. We did machine >>> translation from one of AP's French articles to English, and I was not >>> impressed with the quality of the translation, but hey, we can always >>> give it another shot. >>> >>> On 10/17/20 3:12 PM, jys wrote: On Sat, Oct 17, 2020, at 09:34, Pascal Obry wrote: > > Probably a good move and I understand that rewording was needed but > that it is tad harsh for translators. I may be optimistic/wrong here, but the situation for translators may not be quite as bad as it sounds. From the parts of the re-worked docs that I looked at, the emphasis has been on making the language resemble compact native English. Assuming that translators tend to do the same when writing their own native language, there may not be much need for changes overall. Translators would need to scan for *semantic* changes, and hopefully most of these would be related to updated information, which they would already need to deal with anyway. > That's my main concerns. Having the doc "away" from main repo will not > help. I don't know why exactly, but I've seen that on different > projects. Maybe because the doc is away it feels less part of the > project and there is less incentive to car
Re: [darktable-dev] Introducing dtdocs
Hi Jeronimo, Take a look at https://elstoc.github.io/dtdocs/ - as you'll see the manual there is reworded to be more concise and to the point without additional fluff and all contributors so far took measures to ensure that language is clear english (both maintainers are native english speakers), which IMO makes it perfect for translation. That however comes at a cost of having to reword/retranslate parts of manual. wt., 20 paź 2020 o 18:00 Jeronimo Pellegrini napisał(a): > Hi Mica, > > Thank you for the work on getting a more modern translation > system. (And I'm really happy to see that Weblate is licensed as > GPLv3!) > > I would certainly want to still work with Emacs; not necessarily > with .po files. Just something that has an Emacs mode... > (I'm willing to help write an Emacs mode, so long as I don't > do that alone, because I'm quite overworked. I do have some > experience with Emacs Lisp.) > > If I need to change to a different format and use a special > update-weblate tool, that's ok! > > When you mention that part of the manual needs to be retranslated > because it was rewritten, do you mean the parts that were changed > in recent commits in git/master? If it is so, then I've been > translating those as they come, and the whole thing should be > up to date -- I hope. > Or are those changes somewhere else (another git branch)? > > J. > > Mica Semrick writes: > > Hi Jeronimo, > > > > Thank you for your all your work; last I had looked br_PT was the most > > up-to-date. > > > > We haven't really defined exactly what the translation workflow will > > look like, but if we get feedback from translators that they still want > > to work with PO files, I know we can certainly accommodate that. > > > > Weblate can do nice things like use and keep a translation memory, > > leverage machine translation, and who knows what else; I haven't had > > time to fully dive into it yet. I am not aware of what emacs can do. > > > > I think a decent portion of the manual would need to be retranslated, as > > a good chunk of it has been rewritten. As I mentioned previously, I can > > make translation memories from the current PO files and import them into > > weblate or make them available to you via some other means. Since there > > are a lot of new writings, I don't think that the old translations will > > match up very well. I'm open to exploring machine translation for a > > first pass if you'd like to do that. > > > > I'm also open to any other suggestions you may have. > > > > Best, > > Mica > > > > > > On 10/19/20 3:44 AM, Jeronimo Pellegrini wrote: > >> Hello, > >> > >> (I sent this from an email address different from the one > >> registered in the mailing list and it didn't seem to be > >> sent, so I'm sendingit again from the correct email. Sorry > >> for any duplicates) > >> > >> I have been working on the pt_BR translation (of both darktable and > >> its manual). I usually translate using po-mode in Emacs, but of > >> course I can adapt to some extent. :) > >> > >> How much of my workflow would change? One thing that would be difficult > >> for me is to translate directly on a web browser. I may be > >> old-fashioned, but really, I never got to do any reasonable work > >> on web interfaces. Will it still be possible to use an editor > >> to do translation work? > >> > >> Also - would the darktable manual translation need to be re-entered > >> or reworked? You mentioned that translated segments would be suggested, > >> so I suppose the whole document would need to be entered again in > >> weblate -- is this correct? > >> > >> Thanks, > >> Jeronimo > >> > >> Mica Semrick writes: > >> > >>> Before we open translations on weblate, I will take the current PO > >>> files, for both the application strings and the user guide, and make > >>> translation memory files out of them. I can then import them into > >>> weblate (PO editor also supports TMX files in recent versions), and if > >>> possible, translated segments from the old manual will be suggested in > >>> the dtdocs translation. I don't have high hopes for a lot of matches, > >>> since quite a bit of dtdocs has been rewritten, and translations just > >>> don't work like that. > >>> > >>> The other possibility is that we use machine translation for the first > >>> round, then let translators edit that translation. We did machine > >>> translation from one of AP's French articles to English, and I was not > >>> impressed with the quality of the translation, but hey, we can always > >>> give it another shot. > >>> > >>> On 10/17/20 3:12 PM, jys wrote: > On Sat, Oct 17, 2020, at 09:34, Pascal Obry wrote: > > > > Probably a good move and I understand that rewording was needed but > > that it is tad harsh for translators. > > I may be optimistic/wrong here, but the situation for translators may > not be quite as bad as it sounds. From the parts of the re-worked docs that > I looked at, the emphasis has been on making the
Re: [darktable-dev] Introducing dtdocs
Hi Jeronimo, Thank you for your all your work; last I had looked br_PT was the most up-to-date. We haven't really defined exactly what the translation workflow will look like, but if we get feedback from translators that they still want to work with PO files, I know we can certainly accommodate that. Weblate can do nice things like use and keep a translation memory, leverage machine translation, and who knows what else; I haven't had time to fully dive into it yet. I am not aware of what emacs can do. I think a decent portion of the manual would need to be retranslated, as a good chunk of it has been rewritten. As I mentioned previously, I can make translation memories from the current PO files and import them into weblate or make them available to you via some other means. Since there are a lot of new writings, I don't think that the old translations will match up very well. I'm open to exploring machine translation for a first pass if you'd like to do that. I'm also open to any other suggestions you may have. Best, Mica On 10/19/20 3:44 AM, Jeronimo Pellegrini wrote: Hello, (I sent this from an email address different from the one registered in the mailing list and it didn't seem to be sent, so I'm sendingit again from the correct email. Sorry for any duplicates) I have been working on the pt_BR translation (of both darktable and its manual). I usually translate using po-mode in Emacs, but of course I can adapt to some extent. :) How much of my workflow would change? One thing that would be difficult for me is to translate directly on a web browser. I may be old-fashioned, but really, I never got to do any reasonable work on web interfaces. Will it still be possible to use an editor to do translation work? Also - would the darktable manual translation need to be re-entered or reworked? You mentioned that translated segments would be suggested, so I suppose the whole document would need to be entered again in weblate -- is this correct? Thanks, Jeronimo Mica Semrick writes: Before we open translations on weblate, I will take the current PO files, for both the application strings and the user guide, and make translation memory files out of them. I can then import them into weblate (PO editor also supports TMX files in recent versions), and if possible, translated segments from the old manual will be suggested in the dtdocs translation. I don't have high hopes for a lot of matches, since quite a bit of dtdocs has been rewritten, and translations just don't work like that. The other possibility is that we use machine translation for the first round, then let translators edit that translation. We did machine translation from one of AP's French articles to English, and I was not impressed with the quality of the translation, but hey, we can always give it another shot. On 10/17/20 3:12 PM, jys wrote: On Sat, Oct 17, 2020, at 09:34, Pascal Obry wrote: Probably a good move and I understand that rewording was needed but that it is tad harsh for translators. I may be optimistic/wrong here, but the situation for translators may not be quite as bad as it sounds. From the parts of the re-worked docs that I looked at, the emphasis has been on making the language resemble compact native English. Assuming that translators tend to do the same when writing their own native language, there may not be much need for changes overall. Translators would need to scan for *semantic* changes, and hopefully most of these would be related to updated information, which they would already need to deal with anyway. That's my main concerns. Having the doc "away" from main repo will not help. I don't know why exactly, but I've seen that on different projects. Maybe because the doc is away it feels less part of the project and there is less incentive to care for it? Again, possibly optimistic, but the new setup has a distinct advantage in that text can now be easily edited even within the github web interface itself, reducing the need for contributors to maintain a local git repository just to "scratch an itch" regarding updates or other improvements. In a sense, some technical burden has been shifted to the maintainers of the repo, who will need to sift through (possibly many) issue reports and accept (or not) PRs, perform any needed copy editing, etc... but they seem willing to do this. :-) ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org
Re: [darktable-dev] Introducing dtdocs
Hello, (I sent this from an email address different from the one registered in the mailing list and it didn't seem to be sent, so I'm sendingit again from the correct email. Sorry for any duplicates) I have been working on the pt_BR translation (of both darktable and its manual). I usually translate using po-mode in Emacs, but of course I can adapt to some extent. :) How much of my workflow would change? One thing that would be difficult for me is to translate directly on a web browser. I may be old-fashioned, but really, I never got to do any reasonable work on web interfaces. Will it still be possible to use an editor to do translation work? Also - would the darktable manual translation need to be re-entered or reworked? You mentioned that translated segments would be suggested, so I suppose the whole document would need to be entered again in weblate -- is this correct? Thanks, Jeronimo Mica Semrick writes: > Before we open translations on weblate, I will take the current PO > files, for both the application strings and the user guide, and make > translation memory files out of them. I can then import them into > weblate (PO editor also supports TMX files in recent versions), and if > possible, translated segments from the old manual will be suggested in > the dtdocs translation. I don't have high hopes for a lot of matches, > since quite a bit of dtdocs has been rewritten, and translations just > don't work like that. > > The other possibility is that we use machine translation for the first > round, then let translators edit that translation. We did machine > translation from one of AP's French articles to English, and I was not > impressed with the quality of the translation, but hey, we can always > give it another shot. > > On 10/17/20 3:12 PM, jys wrote: >> On Sat, Oct 17, 2020, at 09:34, Pascal Obry wrote: >>> >>> Probably a good move and I understand that rewording was needed but >>> that it is tad harsh for translators. >> >> I may be optimistic/wrong here, but the situation for translators may not be >> quite as bad as it sounds. From the parts of the re-worked docs that I >> looked at, the emphasis has been on making the language resemble compact >> native English. Assuming that translators tend to do the same when writing >> their own native language, there may not be much need for changes overall. >> Translators would need to scan for *semantic* changes, and hopefully most of >> these would be related to updated information, which they would already need >> to deal with anyway. >> >>> That's my main concerns. Having the doc "away" from main repo will not >>> help. I don't know why exactly, but I've seen that on different >>> projects. Maybe because the doc is away it feels less part of the >>> project and there is less incentive to care for it? >> >> Again, possibly optimistic, but the new setup has a distinct advantage in >> that text can now be easily edited even within the github web interface >> itself, reducing the need for contributors to maintain a local git >> repository just to "scratch an itch" regarding updates or other >> improvements. In a sense, some technical burden has been shifted to the >> maintainers of the repo, who will need to sift through (possibly many) issue >> reports and accept (or not) PRs, perform any needed copy editing, etc... but >> they seem willing to do this. :-) >> > ___ > darktable developer mailing list > to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org
Re: [darktable-dev] Introducing dtdocs
Sorry, I must not have explained myself well enough. For dtdocs, we have pretty much chosen our tool chain, and we intentionally did not announce anything to avoid this type of bike shedding. While markdown has its negatives, the positive is that if you've written a comment on the internet in the last several years, you've probably written markdown, if you know so or not. By "actionable criticism," I meant please make sure your criticism is applicable and actionable on the current dtdocs project. I don't think we're interested in generalized markup discussion, tool chain discussions, or any thing else of that sort. Again, the decisions have been made. If you feel we've absolutely made the wrong decision with markdown, you're free to fork the repo, convert it to the markup flavor that suits you, and edit the content there. We won't use RTD since the point is that we host the documentation ourselves. Hugo gives us a pretty simple and straight forward way to publish things, the dependencies are very minimal, and it integrates well into CI systems. If you feel that things are missing, please open an issue, but the sentiment of "eventually it'll be missing something because tool XYZ is better" isn't really helpful. For context: my profession is documentation and has been for the last 12 years. I've maintained large documentation sets in LaTeX, docbook, DITA XML, FrameMaker, and more. I've maintained docs using just git and I've maintained them using proprietary systems that cost millions of dollars. I've architected new documentation sets that covered hundreds of products and customized the publishing pipeline around them. - mica On 10/16/20 5:13 PM, Moritz Moeller wrote: On 17.10.20 01:41, Mica Semrick wrote: You have specifically pointed out where you think markdown is falling short in this case. For me MD vs Sphinx is mostly about roles, extensions, citations, line comments, footnotes etc. that you have in Sphinx but not in MD. MD was designed for writing texts on the Web. ReST + Sphinx was designed for writing documentation. Here is a longer version of that, written by someone else: https://eli.thegreenplace.net/2017/restructuredtext-vs-markdown-for-technical-documentation/ With that said: I prefer MD syntax over ReST any day as long as it doesn't take anything away I think is standard for good documentation. E.g. being able to have an index auto-generated. Sadly it does. Worst, there is no real standard in MD. CommonMarkdown is different everywhere. Maybe a feature you grew fond of when using MD in Jupyter Notebooks' MD is not available on GiHub's MD etc. > Feedback is welcome, but please try to make it actionable. We're > aiming for improvement. With the above in mind – if I were to start a documentation project now I'd probably use this: https://myst-parser.readthedocs.io/en/latest/ Which is kinda ReST + MD having a baby. :) It would mean all the work you done could be used, mostly as-is. But you would have all the bonuses of ReST + Spinx on top that MD + Sphinx would not give you. Even if you switched from MD + Hugo to MD + Sphinx. Oh, and use readthedocs to handle building and serving. Because, again, that is an ecosystem build for serving documentation as static pages online. Hugo is nice but it was meant to build static websites. Which surely represent a superset, containing static online documentation, but broad enough that it will leave many things to be desired, sooner or later. And btw: https://darktable.readthedocs.io/ is available. ;) Beers, .mm P.S.: For context: I wrote software documentation in MD several times during the last decade. I wrote software documentation in ReST using Sphinx several time (that was before Sphinx added MD support). I also have BG writing docs in LaTex from way before. With that being said I feel entitled to be opinionated about the subject. And mind you, I am talking about the perspective of the writer, not the user. ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org
Re: [darktable-dev] Introducing dtdocs
Before we open translations on weblate, I will take the current PO files, for both the application strings and the user guide, and make translation memory files out of them. I can then import them into weblate (PO editor also supports TMX files in recent versions), and if possible, translated segments from the old manual will be suggested in the dtdocs translation. I don't have high hopes for a lot of matches, since quite a bit of dtdocs has been rewritten, and translations just don't work like that. The other possibility is that we use machine translation for the first round, then let translators edit that translation. We did machine translation from one of AP's French articles to English, and I was not impressed with the quality of the translation, but hey, we can always give it another shot. On 10/17/20 3:12 PM, jys wrote: On Sat, Oct 17, 2020, at 09:34, Pascal Obry wrote: Probably a good move and I understand that rewording was needed but that it is tad harsh for translators. I may be optimistic/wrong here, but the situation for translators may not be quite as bad as it sounds. From the parts of the re-worked docs that I looked at, the emphasis has been on making the language resemble compact native English. Assuming that translators tend to do the same when writing their own native language, there may not be much need for changes overall. Translators would need to scan for *semantic* changes, and hopefully most of these would be related to updated information, which they would already need to deal with anyway. That's my main concerns. Having the doc "away" from main repo will not help. I don't know why exactly, but I've seen that on different projects. Maybe because the doc is away it feels less part of the project and there is less incentive to care for it? Again, possibly optimistic, but the new setup has a distinct advantage in that text can now be easily edited even within the github web interface itself, reducing the need for contributors to maintain a local git repository just to "scratch an itch" regarding updates or other improvements. In a sense, some technical burden has been shifted to the maintainers of the repo, who will need to sift through (possibly many) issue reports and accept (or not) PRs, perform any needed copy editing, etc... but they seem willing to do this. :-) ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org
Re: [darktable-dev] Introducing dtdocs
On Sat, Oct 17, 2020, at 09:34, Pascal Obry wrote: > > Probably a good move and I understand that rewording was needed but > that it is tad harsh for translators. I may be optimistic/wrong here, but the situation for translators may not be quite as bad as it sounds. From the parts of the re-worked docs that I looked at, the emphasis has been on making the language resemble compact native English. Assuming that translators tend to do the same when writing their own native language, there may not be much need for changes overall. Translators would need to scan for *semantic* changes, and hopefully most of these would be related to updated information, which they would already need to deal with anyway. > That's my main concerns. Having the doc "away" from main repo will not > help. I don't know why exactly, but I've seen that on different > projects. Maybe because the doc is away it feels less part of the > project and there is less incentive to care for it? Again, possibly optimistic, but the new setup has a distinct advantage in that text can now be easily edited even within the github web interface itself, reducing the need for contributors to maintain a local git repository just to "scratch an itch" regarding updates or other improvements. In a sense, some technical burden has been shifted to the maintainers of the repo, who will need to sift through (possibly many) issue reports and accept (or not) PRs, perform any needed copy editing, etc... but they seem willing to do this. :-) -- jys ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org
Re: [darktable-dev] Introducing dtdocs
Le samedi 17 octobre 2020 à 09:28 +0100, Chris Elston a écrit : > At a rough estimate you should expect the translations to end up > perhaps no more than 50-60% complete in the best-case scenario. Probably a good move and I understand that rewording was needed but that it is tad harsh for translators. Maybe we should have told them upfront about this especially Jeronimo Pellegrini which has done a tremendous amount of work recently on the pt_BR translation. > > I'm still of the opinion that the benefits of a separate repo far > outweigh the negatives. I understand that you don't like having to > monitor a second repo No problem to monitor a second repo on my side. > but you don't necessarily have to be the main > maintainer for dtdocs - Mica and I are more than happy to shoulder > that responsibility That's really appreciated. > and it's clear that we will have other volunteers now that the format > has been simplified. I've put in well over 500 hours on this project > already, so I think I've demonstrated a dedication to > getting and keeping the docs up-to-date. No question about that, I had not even questioned this part. All clear to me that such a huge project is not just pushed for fun and to drop everything after. > It's also important for these sort of things to be copy-edited by > native English speakers and you would end up having to make non- > technical people maintainers on the main > darktable project - which seems risky. Sure. > Plus the issues around > pre-implementation code freezes and the fact that the manual updates > often trail behind the releases by a couple of months. I'm not sure this has anything to do with one repo or two repos. The problem is volunteer to write the doc. I had recently create a momentum on this side, I hope this will continue. > It seems like > maybe you're also arguing that developers can't cope with having to > update more than one repo? That's my main concerns. Having the doc "away" from main repo will not help. I don't know why exactly, but I've seen that on different projects. Maybe because the doc is away it feels less part of the project and there is less incentive to care for it? > There's no argument with dtorg, rawspeed and lua-scripts being > separate repos so I don't really see the difference here. Sure, if a second repo is needed dtorg is the natural choice. Don't get me wrong, I don't want to keep the doc part of darktable, I want the best solution for darktable project in the long term and on this I have a different opinion. But I'll follow you on this one as you are the driving force with Mica and certainly hope the best for this project. -- Pascal Obry / Magny Les Hameaux (78) The best way to travel is by means of imagination http://www.obry.net gpg --keyserver keys.gnupg.net --recv-key F949BD3B ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org
Re: [darktable-dev] Introducing dtdocs
On 17/10/2020 08:25, Pascal Obry wrote: I suppose one difficult point would be to reuse existing translation but this is very important. The pr_BR manual is up to date and the fr_FR one is 90% (was complete for 2.6). As translating the manual needs countless hours we cannot tell the translators to start from scratch again. Bear in mind that I've done quite a lot of rewording and reorganisation of paragraphs, and there is a fair bit of new content. Much of the manual was written by non-native speakers and though technically accurate a lot of the wording needed copy-editing. At a rough estimate you should expect the translations to end up perhaps no more than 50-60% complete in the best-case scenario. On 17/10/2020 08:39, Pascal Obry wrote: I don't agree with that since most of the documentation is written by the developers themselves. Having a separate repo will make ensuring the documentation is updated even harder. And I do really care about documentation as I have pushed hard recently to have things regularly updated. Now for the translators it shouldn't make a difference since a weblate will be used to update/translate if I have properly understood. All in all, in my experience having the documentation next to the project is always better. I'm still of the opinion that the benefits of a separate repo far outweigh the negatives. I understand that you don't like having to monitor a second repo but you don't necessarily have to be the main maintainer for dtdocs - Mica and I are more than happy to shoulder that responsibility and it's clear that we will have other volunteers now that the format has been simplified. I've put in well over 500 hours on this project already, so I think I've demonstrated a dedication to getting and keeping the docs up-to-date. It's also important for these sort of things to be copy-edited by native English speakers and you would end up having to make non-technical people maintainers on the main darktable project - which seems risky. Plus the issues around pre-implementation code freezes and the fact that the manual updates often trail behind the releases by a couple of months. It seems like maybe you're also arguing that developers can't cope with having to update more than one repo? There's no argument with dtorg, rawspeed and lua-scripts being separate repos so I don't really see the difference here. ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org
Re: [darktable-dev] Introducing dtdocs
Hi johnnybit, > I think it should be a separate repo under darktable org, same as > dtorg website. That way dtdocs can have less technical but more > writting oriented maintainers lowering the burden of keeping docs in > main repo. I don't agree with that since most of the documentation is written by the developers themselves. Having a separate repo will make ensuring the documentation is updated even harder. And I do really care about documentation as I have pushed hard recently to have things regularly updated. Now for the translators it shouldn't make a difference since a weblate will be used to update/translate if I have properly understood. All in all, in my experience having the documentation next to the project is always better. > -- Pascal Obry / Magny Les Hameaux (78) The best way to travel is by means of imagination http://www.obry.net gpg --keyserver keys.gnupg.net --recv-key F949BD3B ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org
Re: [darktable-dev] Introducing dtdocs
I think it should be a separate repo under darktable org, same as dtorg website. That way dtdocs can have less technical but more writting oriented maintainers lowering the burden of keeping docs in main repo. sob., 17 paź 2020, 09:26 użytkownik Pascal Obry napisał: > > Congrats! I'm looking forward moving away from docbook. > > I suppose one difficult point would be to reuse existing translation > but this is very important. The pr_BR manual is up to date and the > fr_FR one is 90% (was complete for 2.6). As translating the manual > needs countless hours we cannot tell the translators to start from > scratch again. > > Another question, I suppose this will be merged back at some point in > current darktable repository ? So we will probably need to coordinate. > > Anyway keep us informed about the progress. > > -- > Pascal Obry / Magny Les Hameaux (78) > > The best way to travel is by means of imagination > > http://www.obry.net > > gpg --keyserver keys.gnupg.net --recv-key F949BD3B > > ___ > darktable developer mailing list > to unsubscribe send a mail to > darktable-dev+unsubscr...@lists.darktable.org > > ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org
Re: [darktable-dev] Introducing dtdocs
Congrats! I'm looking forward moving away from docbook. I suppose one difficult point would be to reuse existing translation but this is very important. The pr_BR manual is up to date and the fr_FR one is 90% (was complete for 2.6). As translating the manual needs countless hours we cannot tell the translators to start from scratch again. Another question, I suppose this will be merged back at some point in current darktable repository ? So we will probably need to coordinate. Anyway keep us informed about the progress. -- Pascal Obry / Magny Les Hameaux (78) The best way to travel is by means of imagination http://www.obry.net gpg --keyserver keys.gnupg.net --recv-key F949BD3B ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org
Re: [darktable-dev] Introducing dtdocs
On 17.10.20 01:41, Mica Semrick wrote: You have specifically pointed out where you think markdown is falling short in this case. For me MD vs Sphinx is mostly about roles, extensions, citations, line comments, footnotes etc. that you have in Sphinx but not in MD. MD was designed for writing texts on the Web. ReST + Sphinx was designed for writing documentation. Here is a longer version of that, written by someone else: https://eli.thegreenplace.net/2017/restructuredtext-vs-markdown-for-technical-documentation/ With that said: I prefer MD syntax over ReST any day as long as it doesn't take anything away I think is standard for good documentation. E.g. being able to have an index auto-generated. Sadly it does. Worst, there is no real standard in MD. CommonMarkdown is different everywhere. Maybe a feature you grew fond of when using MD in Jupyter Notebooks' MD is not available on GiHub's MD etc. > Feedback is welcome, but please try to make it actionable. We're > aiming for improvement. With the above in mind – if I were to start a documentation project now I'd probably use this: https://myst-parser.readthedocs.io/en/latest/ Which is kinda ReST + MD having a baby. :) It would mean all the work you done could be used, mostly as-is. But you would have all the bonuses of ReST + Spinx on top that MD + Sphinx would not give you. Even if you switched from MD + Hugo to MD + Sphinx. Oh, and use readthedocs to handle building and serving. Because, again, that is an ecosystem build for serving documentation as static pages online. Hugo is nice but it was meant to build static websites. Which surely represent a superset, containing static online documentation, but broad enough that it will leave many things to be desired, sooner or later. And btw: https://darktable.readthedocs.io/ is available. ;) Beers, .mm P.S.: For context: I wrote software documentation in MD several times during the last decade. I wrote software documentation in ReST using Sphinx several time (that was before Sphinx added MD support). I also have BG writing docs in LaTex from way before. With that being said I feel entitled to be opinionated about the subject. And mind you, I am talking about the perspective of the writer, not the user. ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org
Re: [darktable-dev] Introducing dtdocs
You have specifically pointed out where you think markdown is falling short in this case. Feedback is welcome, but please try to make it actionable. We're aiming for improvement. On 10/16/20 4:38 PM, Moritz Moeller wrote: On 17.10.20 01:30, Mica Semrick wrote: On 10/16/20 2:12 PM, Moritz Moeller wrote: THB I think Markdown is a tad limited for docs like this. Have you had a look at the site yet? Yes I did. Though I don't understand how that relates to the part of my reply you quoted. .mm ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org
Re: [darktable-dev] Introducing dtdocs
On 17.10.20 01:30, Mica Semrick wrote: On 10/16/20 2:12 PM, Moritz Moeller wrote: THB I think Markdown is a tad limited for docs like this. Have you had a look at the site yet? Yes I did. Though I don't understand how that relates to the part of my reply you quoted. .mm ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org
Re: [darktable-dev] Introducing dtdocs
On 10/16/20 2:12 PM, Moritz Moeller wrote: THB I think Markdown is a tad limited for docs like this. Have you had a look at the site yet? ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org
[darktable-dev] Introducing dtdocs
Introducing dtdocs (https://github.com/elstoc/dtdocs)… This project is a complete rewrite of the darktable documentation in markdown, providing a number of advantages over the current user manual: * *simple markup*: The current documentation uses complex and highly brittle xml markup which is very hard to maintain and is a significant impediment to developers documenting new and amended features. The markup to content ratio is unreasonably high (approx 40% of it is markup) and the effort required to make that markup legible is, unless you have an editor designed for it, tiresome. Markdown uses minimal markup allowing developers to concentrate on getting the content right. Hopefully this will encourage more people to contribute to the documentation. If nothing else, new content can be lifted fairly easily from the OP of new pull requests. * *familiar*: Github issues and PRs are written in markdown meaning that the learning curve for creating markdown content is very low * *portable*: With the exception of the yaml metadata headers (which are pretty standard in static site generators such as jekyll, hugo, and pelican) this documentation is written in pure markdown. While it is currently intended to be rendered in the hugo static site generator (SSG), it should be trivial to port it into any other markdown-based SSG, and to render it to ebook formats using the same content. This also has the advantage that most of the content (and rich diffs) render well in github, including links and images (with the exception of some unsupported markdown extensions). * *easy to build*: The current manual relies on a complex set of tools and is often difficult for users to build and test. Using hugo for web rendering (a single binary) makes it trivial for developers to quickly view their changes on a local version of the website. * *fewer images*: Images should be included in the user manual only when they aid understanding of non-standard functionality or concepts. This makes future maintenance simpler as we don’t need to redo the images every time the darktable interface changes. Many images (especially those that just show a collection of basic named bauhaus controls) have therefore been removed. * *simplified and improved content*: While the content is largely based on the current user manual, it has been thoroughly reviewed, copy-edited (so that the content reads better in English) and re-ordered where necessary to improve clarity. Extra content has been written to better explain some of the more complicated aspects of darktable. Finally, guides and examples have been moved to separate sections (rather than sitting alongside module definitions). This allows us to better document and group ‘how to’ guides for operations where multiple techniques are available (e.g. sharpening, monochrome). This work is still in progress. * *separate repo*: Our hope is that this project will eventually be migrated into a separate repository alongside the darktable and dtorg projects. Keeping the documentation separate is particularly useful because it allows the documentation to run on a slightly different schedule to the main darktable project (it doesn’t have to freeze just because a release has been frozen) but the intention is that it would be released at the same version numbers as darktable (when those versions are ready). This also allows less technical authors to be project maintainers without them also being maintainers on the main darktable repository. This version of the user manual is currently up-to-date (in terms of content) with the latest changes in darktable 3.4, including recent user manual updates. However, work is not yet complete. Here’s a short list of our current ToDo items * Translation workflow – the current intention is to use Weblate and we’re hoping we can reuse some of the pre-existing translations * Website style and layout is still being finalised * pdf and epub versions are still WIP * The Guides and Tutorials section will mostly be new content and is awaiting authors * The auto-built Lua API manual is currently out of scope * Other things we haven’t thought of yet While the language has been fully reviewed to make it read better in English, it’s highly likely that errors have been introduced or that rewording has changed the intended meaning and mis-stated some of the actual darktable functionality. So what we need now is reviewers – both from a technical point of view and to help ensure that the manual is as clear and unambiguous as possible. We also welcome any other comments or suggestions that you may have. The manual source is currently hosted at https://github.com/elstoc/dtdocs(published to https://elstoc.github.io/dtdocs/). Please feel free to raise issues on the Github project or submit pull requests if you think anything could
Re: [darktable-dev] Introducing dtdocs
On 16.10.20 19:16, Chris Elston wrote: Introducing dtdocs (https://github.com/elstoc/dtdocs)… This project is a complete rewrite of the darktable documentation in markdown, providing a number of advantages over the current user manual: Fantastic! I suggested using Sphinx a few years back but I got ignored. THB I think Markdown is a tad limited for docs like this. But if I have to choose between the old doc format and Markdown there is no question. It's one of the reasons I never contributed to the DT docs. That may change now. :] Big thumbs up!!! :) .mm ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org
Re: [darktable-dev] Introducing dtdocs
What can I say except - wow! I'm a fan since the start (because whatever I tried I'm too dumb to do current docs). I hope weblate will work out for translations (given that it seems that only pt_BR is translated on regular basis currently) pt., 16 paź 2020 o 19:16 Chris Elston napisał(a): > Introducing dtdocs (https://github.com/elstoc/dtdocs)… > > This project is a complete rewrite of the darktable documentation in > markdown, providing a number of advantages over the current user manual: > >- *simple markup*: The current documentation uses complex and highly >brittle xml markup which is very hard to maintain and is a significant >impediment to developers documenting new and amended features. The markup >to content ratio is unreasonably high (approx 40% of it is markup) and the >effort required to make that markup legible is, unless you have an editor >designed for it, tiresome. Markdown uses minimal markup allowing developers >to concentrate on getting the content right. Hopefully this will encourage >more people to contribute to the documentation. If nothing else, new >content can be lifted fairly easily from the OP of new pull requests. >- *familiar*: Github issues and PRs are written in markdown meaning >that the learning curve for creating markdown content is very low >- *portable*: With the exception of the yaml metadata headers (which >are pretty standard in static site generators such as jekyll, hugo, and >pelican) this documentation is written in pure markdown. While it is >currently intended to be rendered in the hugo static site generator (SSG), >it should be trivial to port it into any other markdown-based SSG, and to >render it to ebook formats using the same content. This also has the >advantage that most of the content (and rich diffs) render well in github, >including links and images (with the exception of some unsupported markdown >extensions). >- *easy to build*: The current manual relies on a complex set of tools >and is often difficult for users to build and test. Using hugo for web >rendering (a single binary) makes it trivial for developers to quickly view >their changes on a local version of the website. >- *fewer images*: Images should be included in the user manual only >when they aid understanding of non-standard functionality or concepts. This >makes future maintenance simpler as we don’t need to redo the images every >time the darktable interface changes. Many images (especially those that >just show a collection of basic named bauhaus controls) have therefore been >removed. >- *simplified and improved content*: While the content is largely >based on the current user manual, it has been thoroughly reviewed, >copy-edited (so that the content reads better in English) and re-ordered >where necessary to improve clarity. Extra content has been written to >better explain some of the more complicated aspects of darktable. Finally, >guides and examples have been moved to separate sections (rather than >sitting alongside module definitions). This allows us to better document >and group ‘how to’ guides for operations where multiple techniques are >available (e.g. sharpening, monochrome). This work is still in progress. >- *separate repo*: Our hope is that this project will eventually be >migrated into a separate repository alongside the darktable and dtorg >projects. Keeping the documentation separate is particularly useful because >it allows the documentation to run on a slightly different schedule to the >main darktable project (it doesn’t have to freeze just because a release >has been frozen) but the intention is that it would be released at the same >version numbers as darktable (when those versions are ready). This also >allows less technical authors to be project maintainers without them also >being maintainers on the main darktable repository. > > This version of the user manual is currently up-to-date (in terms of > content) with the latest changes in darktable 3.4, including recent user > manual updates. However, work is not yet complete. Here’s a short list of > our current ToDo items > >- Translation workflow – the current intention is to use Weblate and >we’re hoping we can reuse some of the pre-existing translations >- Website style and layout is still being finalised >- pdf and epub versions are still WIP >- The Guides and Tutorials section will mostly be new content and is >awaiting authors >- The auto-built Lua API manual is currently out of scope >- Other things we haven’t thought of yet > > While the language has been fully reviewed to make it read better in > English, it’s highly likely that errors have been introduced or that > rewording has changed the intended meaning and mis-stated some of the > actual darktable functionality. > > So what w
