The darktable user manual is largely outdated. Problem is it uses an esoteric kind of XML required by a brittle software stack (Saxon) to be compiled into HTML or PDF.
This complexity steers away many contributors.
But thanks to Chris Elston, @secretlifeofmatt and @paperdigits, it is being rewritten in Markdown with a better "tutorial" approach.
Contribute :

@darktable @secretlifeofmatt @paperdigits wonderful. writing XML by hand is the worst experience. it took me about 2 hours to add 1 sentence to the #nixos manual. i did that twice! never again.

but we finally decided to switch to markdown, too. i think that is the right direction to make contributing as easy as possible ✨

@davidak oh that is awesome! I noticed they were using docbook >.<

I'm a NixOS user as well :)

@darktable @secretlifeofmatt @paperdigits

but why on github and not on @codeberg

Give your free project a free home.


No tracking. Your data is not for sale.

@mondstern because there will always be a newer, cooler and nicer plateform somewhere else, but at some point the job needs to be done. We can't switch platforms every year, it's too much overhead for everyone.

(To be clear, "the job" is developing image processing software, not developing migration scripts and other tools to set the tools to set the tools to do the job).

@secretlifeofmatt @paperdigits @codeberg

@darktable @mondstern @paperdigits @codeberg I really appreciate your huge work, but quitting Microsoft's github is not a matter of features, but privacy and freedom.

staying on Github is a matter of features. Leaving it would be a matter of ideology, at the expense of features. Besides, everything we host on Github is public anyway, the most private things would be email adresses but any other Git platform will store them in commits just as well.

@paperdigits @codeberg @mondstern

@darktable @paperdigits @codeberg @mondstern Yes, every choice usually is ideology. I was just stating that changing from github was not a matter of being "cooler" or "newer".

The problem with github is not you but the company behind it. They have already blocked some developers (iranian, if I remember correctly).

In general, I prioritize ideology (or human rights and privacity, I would say) before features. Being ethical.

@marcelcosta @darktable @codeberg @mondstern I'm sure codeberg is great, but this kind of bikeshedding is not productive.

@paperdigits @darktable @codeberg @mondstern I'm sorry, but I disagree. I was not focusing in codeberg (which may be great) but in Microsoft's github. Personally, the main reason I use most of the free software is because ethical motivation. So is not a trivial aspect.

@marcelcosta @darktable @codeberg @mondstern I'm sorry I don't understand. Are you saying you're not going to contribute because of github? Will you not read the docs because github? Or something else?

@paperdigits @darktable @codeberg @mondstern No, at least at the short run. But Microsoft controlling the majority of the free software is something that concerns me for sure. Do you think it doesn't matter?

"Embrace, extend, extinguish".

@marcelcosta @darktable @codeberg @mondstern They certainly do no control our project. It's git, so you just clone it, then push it somewhere else.

It s disappointing that we are some 800 person hours into rewriting the docs, and all you can say is "ugh, Microsoft." No thanks.

@paperdigits @darktable @codeberg @mondstern If you read my comments, the first think I do is thank your effort and your very good software.

And if you think that the reppository owner don't have some degree of control in the process... well, ok. I'm not saying I will not appreciate your efforts and your software, am I just concerned about Microsoft embrace of the free software community.

@marcelcosta @darktable @paperdigits @mondstern

I agree. Darktable is cool. The new documentation is great. Politics are important and shape our world.

:) I agree on all points!

Keep up the great work!

@marcelcosta @darktable @codeberg @mondstern when github becomes an obvious hindrance, I'm sure we'll leave. But I don't think anyone in the project sees that yet, even if you still view Microsoft as an existential threat.

@paperdigits @marcelcosta @darktable @codeberg @mondstern github, gitlab, gitea,.. all use git and the code is not tied to anyone of them, that cool. So, if anyone can move the code away from gitlab, why is Micro$oft so interested in it? Well, I imagine it is for the same reason the bought Linkedin, the value of the site is the social network. And given the precedence we have with Facebook and company, perhaps it is not a good idea to help build Microsoft's proprietary social network.

Github is Facebook.

@tuttle @marcelcosta @darktable @codeberg @mondstern I don't need you to mansplain github. We are on github because the main project is there, because of the network effect, and because someone else maintains github. Before github the project used redmine, which was a strain on the small Dev team. The darktable team moved before Microsoft acquired github. Moving would be another burden on the project that we don't need.

@paperdigits @tuttle @darktable @codeberg @mondstern Mansplain? I didn't notice your gender.

I'm sorry, but I don't think this discussion is useful...
@paperdigits @darktable @codeberg @mondstern Wow... 😨 Several things:

1. My intention wasn't judging anyone from the darktable project, a software I love, admire and use for several years (which I explicit in the first message). If anyone felt so, I do apologize.

2. I was not the first asking to move from github, I was just elaborating on other user's comment than moving from github to other free software solutions was a matter of ethics (you can disagree, but the focus is there) rather than more features or coolness. Thats why I don't understand a direct message saying something like "your opinion doesn't bother us".

3.I'm not the only one concernedwith github purchased by Microsoft. Projects like KDE, Gnome or Gimp migrated to gitlab right after the transaction. In addition, developers from some countries were blocked shortly after.

@marcelcosta @darktable @codeberg @mondstern have you read the article you linked? Github blocks those countries not by their own choice, but because the US government tells them they must do so.

If you don't like github, don't use it. We all understand the trade offs being made, and thus far we have reasoned that the effort necessary to move *all the people* (not the code so much) to another platform is not worth it.

@paperdigits @darktable @codeberg @mondstern Why your aggressive attitude? I didn't say being cohoerent with comunitary life was easy, neither when or even if you should do the change.

@marcelcosta @darktable @codeberg @mondstern This is not aggressive, this is a retort to your comments. Are you under the impression that you get to offer your opinion without hearing others?

@paperdigits @darktable @codeberg @mondstern Well, one can give opinions in many ways. I felt some agressiveness from your comments. You excluded me from darktable community just because I think microsoft represents a threat to society. You didn't focus on the words of admiral and love I had for your project and the time you spend developing it.

@marcelcosta @darktable @mondstern wrong, you exclude yourself from the project by refusing to use github (apparently). I haven't denied your contributions in any way. I have expressed my frustration in sinking a lot of hours into something, only to be lectured by multiple people about topics I'm already well aware of, thought about, and came to different conclusions. It seems you can't handle different opinions, and that is OK with me.

@paperdigits @darktable @mondstern mmm... Go fork yourself is excluding, I would say. I never said I would stop using darktable. I always appreciated your work. I don't know why you are frustated. I can handle different opinions, but you aren't counter arguing me but complaining because I focus on github.

@marcelcosta @darktable @mondstern I've given you several reason why we are on github and why we are not moving (now). I've countered your point about github blocking countries.

We've built a new house and you're lecturing us about the ethics of the store where we bought the nails, but you don't understand how that is frustrating... OK then, not sure what to tell you.

@paperdigits @darktable @mondstern I never asked to move now. I didn't initiate that lecture you are referring to, and when I gave my opinion was taking care to also appreciate your efforts and project. If we cannot find a point of agreement here, we will be in circles forever, sorry.
Show newer

@marcelcosta @darktable @mondstern if the ethics of it all are so important to you and everyone else on this thread who are choosing to focus on platform choice rather than the efforts us volunteers have put into trying to improve a project that we value, the please maintain a separate code base on a platform that aligns with your ethics. The people who agree with you will flock to that and improve darktable so much that we will be overwhelmed and grateful.

@paperdigits @darktable @mondstern I would happily donate monthly to the project (I didn't find any link, maybe I should look further) to support human resources and infrastructures as a community.

@darktable Rewritten in Markdown? Just use pandoc on the HTML version♥

@Sandra @darktable
Rewritten was a key word here. It's not a straight transfer. And saying what we should have done after the fact isn't enormously helpful.

@elstoc @darktable I didn’t know that it was after the fact because the post I replied to says that it was ongoing!

It said “is being rewritten”

@Sandra @darktable

Ok fair enough. It's actually pretty much complete in English and we mostly need to work out how to manage translation to other languages, plus some basic look-and-feel stuff.

@Sandra @darktable we have improved, edited, and restructured the docs, so it wasn't just a conversion.

@mpjgregoire @darktable @secretlifeofmatt because making everyone learn rst misses the point of having an easily editable source completely.

At some point you have to choose some tools and go for it. We choose a popular tool chain because its popular.

Why not asciidoc? Troff? Nroff? Latex? Our own custom XML format! This argument goes on and on

@paperdigits @darktable @secretlifeofmatt Oh sure, it's desirable to have a mark-up format that's easy to use, but there are several of those. The fact that Markdown is popular is a perfectly good reason to pick that particular format.

Sign in to participate in the conversation

Server run by the main developers of the project 🐘 It is not focused on any particular niche interest - everyone is welcome as long as you follow our code of conduct!