ART (brief) reference manual - Any interest?

Big Time Disclaimer ™ - I debated with myself whether or not to even post this. I’m not a developer, not a color scientist, not a mathematician and not a pro photographer. I’m so far from expert that it’s laughable to even think of myself in those terms. So if this is a recurring thing that @agriggio or others have addressed and / or refused before, or if I’ve unknowingly contravened some protocol, just tell me to shut up – No hard feelings.

OK, that said… :slight_smile:

I’ve seen questions about ART documentation and indeed, initially looked for it myself. I think from a user POV a basic high-level (user-supported?) reference of sorts could offer value.

Would there be any interest in such a document?

RawPedia is a tremendous resource and well worth reading in detail. But to have to effectively “learn” RawTherapee (i.e., read RP) in order to then learn ART is probably a little daunting to potential new ART users. I was familiar with RT before ART, so I can’t put myself fully in their shoes, but it seems likely. I realize ART wasn’t created, nor still does exist, just to build user share but it’s a great tool that I think deserves use.

What I’m thinking of would be much, much smaller than RawPedia (obviously) and would – as much as possible within reason – simply link to, or otherwise reference, relevant information in RawPedia. Sort of an “ART diff” on RP, plus a little. In other words, leverage RP as much as possible but put all the basic info together in one spot rather than send new users on a wild RawPedia chase…

ART and RawTherapee are diverging so whatever is specifically documented about ART (even if initially pulled from RP for the functional duplicates) will remain valid unless intentionally changed. Anything new would be ART-specific and in need of documenting anyway.

So…

I kinda have what might be a start… maybe? Or maybe I’m just overestimating the value of what little I’ve done :stuck_out_tongue_winking_eye:

I was putting together semi-random notes for my personal use (using the Joplin note app) when it occurred to me that maybe someone else could benefit. However, it’s not complete and there’s certainly no guarantee of accuracy yet (especially when my “understanding” is involved!). But maybe with others’ input the holes could be filled?

@agriggio - As the ART developer, janitor and Chief Bottle Washer (as the old saying went), what do you think? Any point in uploading what I have or is this a non-need? If no, I’ll go away but if yes, what format, where, how, would be best? I can export from Joplin in Markdown, HTML, PDF, etc.

Once again, they’re just notes – Not anything perfectly structured nor finished. But they’re there…

Thanks!!

8 Likes

Hi,
This is great! I’m looking forward to reading what you have! As for the format, I can either embed it in the existing wiki (which already has some docs, including user-contributed ones, to be completely fair – though I agree they are insufficient), or just link to it. If you prefer the former, I’d need something in markdown; for the latter, any web-readable format is fine.

Thanks!!

OK, I’ve attached two files here…

ART_reference.zip - Contains exports in every relevant format Joplin offers (not knowing what might be preferred):

  • Markdown
  • Markdown with front matter
  • HTML file
  • HTML directory

ART_reference.pdf - Just for quick viewing convenience

ART_reference.zip (16.3 MB)
ART_reference.pdf (4.5 MB)

Notes


  • This started entirely for my own use, as a few notes on random tools. Then I decided to include all tools for completeness and then at the last minute tacked-on some shallow coverage of the File Browser and Queue. However, upon re-reviewing Barry Thomas’ excellent Quick Start I think just somehow combining the tools reference with his work would be far better. He’s done a vastly superior job than I in that regard. Also, since I was originally writing to myself only, some editing will be required to make the text more concise and suitable for mass consumption.

  • My aim, to reduce errors, was to originate as little as possible, but rather copy / link / adapt existing documentation from others who know what they’re talking about. For the most part, that’s what this is. But there are a few places where I already had something (and didn’t bother to replace it) or didn’t find anything pre-existing. In particular, please review my “understanding” of what you explained about Color Similarity masking.

  • I’ve used the tag “MORE_INFO_NEEDED” throughout just as a general heads-up flag. Where I found nothing, didn’t understand what I read (well enough) or thought further elaboration would help, I tagged it.

  • The formatting may appear superficially consistent, but it needs serious attention. Between my minimal Markdown knowledge and the (unfortunately buggy) Joplin editor, formatting options were limited. Then again, maybe that’s the point of Markdown…? At any rate, for example, I used a lot of bullets to group things together. I’m sure you can do a better job.

  • Any and everything is fair game - Please correct as needed. You know the classic ‘bad dream’ where you’re in a public place, partially undressed? There’s a tiny bit of that for me here – My misunderstandings are on display for all to see. :grin:

Thanks.

9 Likes

Thanks a lot for this!
I have put the current draft here:
https://bitbucket.org/agriggio/art/wiki/Reference

It’s not yet linked from the main page, as I need to go through it and correct a few (minor) inaccuracies, but it’s already tremendously helpful!

Looking good! Once those TODOs get replaced with real information (and my mistakes are fixed) hopefully it’ll be of some value.

I’m sure you noticed the relative lack of local editing / masking content, as well as straight-up copied quotes from your forum activity. They need to be tweaked into more contextual documentation rather than just isolated copy / paste snippets, IMO.

And like I mentioned before, given the quality of Barry’s Quick Start, if you want to lop off all but the tool references, that’s fine with me. Up to you.

I had gone to the trouble of anonymizing (pixellating) a couple of items in one or two of the screen shots, but I realize now that I completely overlooked several others. Oh well :slight_smile: …there’s nothing personally identifiable there, beyond my first name which is inconsequential (obviously).

One thought – All of this exists in the context of FOSS / GPL, but I don’t know if there needs to be any (more specific) attribution, credits or such. It’s certainly not original with me. I copied wholesale from RawPedia, but ART itself was forked, so… I don’t mind at all my name being associated with it, but I want to make sure no one thinks I’m trying to take any credit.

Thanks!

Hi,

I’ve added an attribution notice for RawPedia at the beginning. As far as I know, this should be enough to comply with the license. If you used other sources too, it would be good to list them as well.

Hi,

one more thing – in case it was not clear (probably it wasn’t indeed :slight_smile: : I am quite happy to see this effort, but this is something I am not willing to do myself, sorry. I put the content in the ART wiki so that it can be cloned and easily edited by other interested people (assuming they exist…), and I will be happy to accept merge requests to add the missing descriptions and/or improve what is there. However, it is very unlikely that I will work on it myself, at least in the near future (with the exception of correcting a couple of inaccuracies as I mentioned above).

Absolutely! Good to see ART getting its own (forked) documentation.

Understood, no problem. :+1:

My only intent in the “MORE_INFO_NEEDED / TODO” markers was to indicate where I didn’t understand something to a point of explaining it with “authority” (i.e., so that readers wouldn’t be mislead) and / or thought someone more knowledgeable might contribute insight, clarification, etc.

After your corrections are done I’ll review the TODOs and provide verbiage where I can. No rush.

So do (will) I need to clone <something> in order to edit it? Sorry – I’m totally unfamiliar wtih BitBucket / Jira / this wiki / etc. and have no experience working with them. Do I have access to do that? I can (usually! :slight_smile: ) follow instructions if there are some, though.

Thanks!!

Yes, the wiki is in a git repository that can be cloned (there should be a button in the top right corner of the page). Then you can edit and submit pull requests as in a usual git workflow.

HTH

Yes, that looks like some serious work. Haven’t read it yet, just scrolled through it and saw 2 or 3 sentences.

I will definitely read it (some day) and see if I can help at some point. (I think I’m doing quite well with ART, but also don’t have any technical background knowledge to explain things properly)

So far, I have a note…

Tone-EQ, Regularization:

The biggest changes happen between 0 and 1, the other values are mostly for fine tuning. A general recommendation is to keep the setting at 1

I personally would disagree with those points. But apart from my feelings, I would suggest to not insert (artistic) recommendations in the manual as long as there is not a serious technical reason for telling people to use something “with care”, but to just explain the functions and effects of adjustments.

Thanks, but 99.999% of the “serious work” is from others, just collated here. :slight_smile:

FYI – This is one of several “TODO” pieces that will need revision. This one was originally copied from one of @agriggio’s posts, simply for my personal reference. That was before the idea expanded with the subsequent thought these pieces might be revised by someone more knowledgeable than me. Any input is appreciated.

I’ll monitor here for a while …not to mention read up on cloning a git repository and all that. I’ve logged into git and filed a bug report here and there, but nothing more. It may be a little while, though with the holidays and all.

1 Like

OK, got it cloned and will review. I’ll submit a pull request at some point. :slight_smile:

Thanks.

Looking very good.
My first thought is that the editor tabs, ie exposure etc, should be bolder, possibly underlined, and have the tab icon next to it. This would make it easier for a newcomer to understand.
Thanks for the effort.

The tab icons are a good idea, so I’ve added them – although I’ve not submitted them back so only for me at the moment :slight_smile: . I’ve also corrected a few typos and other minor things.

As far as the overall styling goes I’m trying to not specify too much so it can follow suit with the other info on the ART wiki.

Thanks for the feedback.

I feel like this is one of those ideas that, once done, will be another step toward the software being perceived as on par with other, more established FOSS projects. Users will be interested once they see it. As the movie says, Build it and they will come.

1 Like

Well that took less time than I expected (had some time to kill today). I’ve edited the Markdown to correct a few typos, clean up my wording and add clarifications, etc. There are only a few TODOs left, but any commentary from me would be empirical at best (and very likely incorrect).

So I’m ready to send it back. However, I need assistance…

The clone yesterday (?) was the first time I’ve used git. :slight_smile: I’ve been reading on the Bitbucket support site how to create a pull request, but I’m not finding the “create” option it mentions.

Am I just being blind or in the wrong place?

Pointers? Cheat sheet? Slap on the head? :stuck_out_tongue_winking_eye:

Thanks.

You have to be logged in to see the button, could it be that? Anyway I’m not very familiar with the BB interface myself – if it’s too complicated, you can also upload a zip file here if you prefer.

Thanks in advance!

@lphilpot I thought for a while to do some doc, but I had not enough knowledge or courage to set up something.
I appreciate your willingness to set up a documention. I have a few questions:

  • do you intend to fork rawpedia and use it as the basis for this doc. There are a lot of chapters applicable to ART. Or just link to it when applicable?
  • do you foresee participation of other users? and do you have already an idea of the procedure? I suppose the straightforward method will be to modify/correct your doc repository. If you require other people to complement/correct the doc through pull requests to your own doc repository, I fear you will not get a lot of contributions. So you should grant access directly to it, as it is done with rawpedia wiki.

Thanks again for the effort and to @agriggio for help.

I was logged in and found a “Create” button / dropdown list but it had nothing about pull requests on it. If I was a dev, merging branches, etc., I’d invest the time to learn the git command line. But I assumed for this one time the BItbucket GUI would suffice.

At any rate, here’s a zip of the Markdown file and its image folder. I don’t see myself really doing anything more. I’ve already exceeded the limits of my knowledge LOL.

Thanks.
ART_reference_20221217.zip (4.0 MB)

1 Like