Clojure tutorial

[magomimmo]

@Daniil-Osokin could you give me an help please? I do not understand where is the issue.

[Daniil-Osokin]

@magomimmo Looks like you should rename clojure_java folder to closure_dev_intro to fix that warning. But now Docs is failed.

[Daniil-Osokin]

@magomimmo I'll dig it =)

[magomimmo]

thanks! I'm almost ready with a new contribution on easily showing images in named windows from the REPL.

[magomimmo]

I'm suspecting that's the issue depends on the .. code:: cljwhich is not supported by sphinx. I'll try by using a bashunless someone knows how to add a new code highlighter for clojure language.

[magomimmo]

@Daniil-Osokin hi, honestly there to much incidental complexity for publishing a tutorial on opencv. Or someone publishes a better an complete howto on crerating tutorial, or I think people would not be motivated enough to afford such a PITA.

My best

[Daniil-Osokin]

@magomimmo Yes, rst can be a challenge. If you have an idea, how to improve original tutorial, please, share it, and we will improve the tutorial!

[magomimmo]

@Daniil-Osokin Someone suggested me git-scribe but I never tested it. My personal preferences goes to markdown format (eventually extended as github does). Thanks for your help. I'm going to take a look at it.

my best

[magomimmo]

https://github.com/schacon/git-scribe

[magomimmo]

@Daniil-Osokin Hi Daniil. I give up. No way to solve the build bug even by doing what you suggested. Now instead of a warning I receive a failure. Could you eventually fork my clojure-tutorial repo, fix it and push request back to me. I wasted not less than 10 hours with this such a stupid publishing system and you wasted your time too.

You should definitely find something more agile than sphinx/rst. It's the most frustrating experience I had in writing tutorials.

My best

[magomimmo]

@vpisarev @Daniil-Osokin: Hi Vadim, as I wrote above, I give up. I really can't waste my time with this terrible sphinx/rst pair. It's a pity, because I'm becoming really productive by using opencv in the clojure REPL and it's an experienced that should be shared. I was also able to overcome the absence of namedWindow and imshow methods in the java API with really 3 lines if clojure code based on seesaw (swing is a big PITA too).

OpenCV is a really great library, but the it's documentation system is more than a PITA. If someone will be able to fix the build problem of my clojure tutorial she/he will be very welcome.

[Daniil-Osokin]

@magomimmo Thank you for the effort! It's really strange, usually there is no such problems with rst, but, you see, something is happened here. I'll try to resolve it.

[magomimmo]

@Daniil-Osokin thanks Daniil. Take into account that the I used pandoc to translate from markdown format to rst. perhaps this could be the problem.

[magomimmo]

@Daniil-Osokin thanks so much.

[Daniil-Osokin]

@magomimmo You are welcome!

[Daniil-Osokin]

@kirill-kornyakov Could you please review this request?

[magomimmo]

@kirill-kornyakov I changed the license from EPL to BSD. I kept the failing unit test as is for the reasons explained in the previous comment.

Thanks

[kirill-korniakov]

So, I like the tutorial in general, and I think we can take it as is. But it would be great if the sample actually calls OpenCV. I understand that the idea is to use the library interactively, but if we can show a simple OpenCV call from the project, that would be perfect!

[magomimmo]

@kirill-kornyakov I have to admit that I do not completely understand your comment. What does it mean "actually calling OpenCV? Obviously I could modify the source code of the default lein generated project (i.e. the core.clj source file) for doing the same things I did in the REPL (e.g. blurring an image). Is it what you mean by actually calling OpenCV?

Take into account that I'm writing a new clojure tutorial in which I interactively display an image in a window from the REPL. This fills the gaps of the current OpenCV Desktop Java API limitations regarding the namedWindow and imshow functions non being available without incurring in the big pain of directly using Swing.

[kirill-korniakov]

Yes, this is what I mean. I'm asking about the same code that you did in REPL.

Here is my motivation. Forget about your tutorial. Somebody clones OpenCV repo, and then starts to read sources. At some moment he goes to the java/clojure folder and finds your sample. But this sample doesn't contain OpenCV code! That's what bothering me. We have a sample in the OpenCV repo, that doesn't call OpenCV at all.

So, what I'm asking is to make the sample project a little bit more illustrative. So, even if people are not familiar with your tutorial, they could at least check the syntax and recognize LISP + OpenCV code.

[magomimmo]

@kirill-kornyakov done! my best

[kirill-korniakov]

Perfect! My last question (sorry if I'm too pedantic today)...

Will everything work if we remove the samples/java/clojure/simple-sample/resources/images/blurred.png file? It seems that this file is rewritten by the program, so we can probably remove it from the repo (since we're trying to minimize its size).

[magomimmo]

On Dec 10, 2013, at 4:57 PM, Kirill Kornyakov notifications@github.com wrote:

Will everything work if we remove the samples/java/clojure/simple-sample/resources/images/blurred.png file?

correct. we could remove it. it was there because the original README.md required it to show the blurred image.

but it does not hurt if you leave it there as well.

[kirill-korniakov]

That's not true. People are very nervous about the repo size, especially about images. We have multiple copies of Lena, and your tutorials adds 4 "new" images. So, if we can remove the image, better to do it before it becomes part of the public history.

And you know, it seems that you'll need to rewrite the branch's history in order to avoid the image in the repo history... @SpecLad, do you think we should squash the commits here, so we have more compact history?

[magomimmo]

That's not true. People are very nervous about the repo size, especially about images.

you should put all the images used by tutorials or whatever in a single place. We have multiple copies of Lena, and your tutorials adds 4 "new" images. So, if we can remove the image, better to do it before it becomes part of the public history.

I can remove it. But it will save just one image of the four and as you said it will be in the branch history anyway. And you know, it seems that you'll need to rewrite the branch's history in order to avoid the image in the repo history... @SpecLad, do you think we should squash the commits here, so we have more compact history?

let me know what I should do to rewrite the branch history.

[magomimmo]

@kirill-kornyakov @SpecLad I removed the blurred.png image. I think that you should be able to squash the commit while merging (but I'm not sure about that)

[magomimmo]

This should do the trick from your side:

git merge --squash clojure-tutorial
git commit -m 'add clojure tutorial'

my best

[SpecLad]

I'm suspecting that's the issue depends on the .. code:: cljwhich is not supported by sphinx.

It isn't? Sphinx uses Pygments, which supports just about everything, Clojure included. In fact, I just did a little test, and it worked fine.

@SpecLad, do you think we should squash the commits here, so we have more compact history?

Probably. I don't think all of them should be squashed, because some of them represent real evolution of the tutorial (plus it'd muddle authorship information), but at least the commit that deletes the blurred image should be joined with the one that adds it, so that the image disappears altogether. And maybe the various small fixes could be joined with their parents, but I don't care that much.

This should do the trick from your side

I'd rather you did it, because a) it will be tested by the buildbot (I know, there shouldn't be any difference, but better safe than sorry), and b) because then this PR won't be marked as merged.

let me know what I should do to rewrite the branch history.

Interactive rebase is your friend.

[SpecLad]

Incidentally, is that lena.png the same file as samples/cpp/tutorial_code/images/lena.png? Because if not, it should be (same reason; saving space).

[magomimmo]

@SpecLad I previoulsy substituted bash to clj because I did not know if you were supporting clojure highlight or not. Goood to now (I'll query-replace again with clojure).

I'll get the lena.png from the folder you said, but what if someone changes that tutorial? You should definitely created a shared resources/ folder to save any static resources used by samples.

I have to say that the incidental complexity of you sphinx/ReST is really too much for people helping you in creating tutorials and samples.

Why don't use github stuff (markdown is MUCH, MUCH MORE agile and LESS, LESS fragile than Sphinx/ReST (IMHO it sucks a lot).

I will see what to do with the squash, but you should not overload your helpers with such thinks that depends on your infrastructure.

Last thing: someone should write a more readable howto contribute tutorial then the one currently available. I understand that most of you are accustomed with the incidental complexity of the used programming languages, but it is not sufficient to pretend third parties willing to collaborate to go throw this pain.

My best

[magomimmo]

Incidentally, is that lena.png the same file as samples/cpp/tutorial_code/images/lena.png?

why should I do something that almost no other tutorials did? i saw tons of lena.jpg, lena.png around. BTW, did you decide to use such a bad white-balanced picture to show how to correct it or it was just a very bad picture? Because if not, it should be (same reason; saving space).

only few tutorials did that. You should do the same in all the others tutorials

my best

Reply to this email directly or view it on GitHub.

[SpecLad]

I'll get the lena.png from the folder you said, but what if someone changes that tutorial?

I'm not saying you should reference that particular file in your tutorial - you can copy in into your directory. An exact copy won't affect the size of the repository.

You should definitely created a shared resources/ folder to save any static resources used by samples.

Yes, we should...

Why don't use github stuff (markdown is MUCH, MUCH MORE agile and LESS, LESS fragile than Sphinx/ReST (IMHO it sucks a lot).

Does it support tables of contents? Search indexing? Includes? Literal includes? Substitutions? Function references? Any references?

why should I do something that almost no other tutorials did? i saw tons of lena.jpg, lena.png around

Because we'd like to prevent further spread of this (incidentally, all of the lena.jpgs are the same file).

You should do the same in all the others tutorials

Too late for that.

[magomimmo]

I'm not saying you should reference that particular file in your tutorial - you can copy in into your directory. An exact copy won't affect the size of the repository.

it's an exact copy Why don't use github stuff (markdown is MUCH, MUCH MORE agile and LESS, LESS fragile than Sphinx/ReST (IMHO it sucks a lot).

Does it support tables of contents? Search indexing? Includes? Literal includes? Substitutions? Function references? Any references?

https://help.github.com/articles/github-flavored-markdown https://help.github.com/articles/creating-pages-with-the-automatic-generator

mimmo

[magomimmo]

@Daniil-Osokin @kirill-kornyakov @SpecLad

I did my ultimate tentative. I was not able to remove the commit where the blurred.png were added to samples/java/clojure/simple-sample/resources/images. In any case that should be an exact copy of the one used in the tutorial, so there should not been waste of space.

I never had so much trouble in publishing a tutorial on an open source project. IMHO you should not overload free contributors with such bothering issues caused by the incidental complexity of your documentation platform.

As said, I also suggest to write a much clearer tutorial on how to contribute, because the one currently available online has not been helpful at all with all the issues I had in this thread.

My best

[kirill-korniakov]

Mimmo, thank you for the effort, we appreciate it. But please keep in mind that OpenCV doesn't have tech writers at all. That means that if you see any issues with how-to-contribute tutorial, you're invited to contribute to it! Again, nobody is updating the documentation systematically. If you don't like something, feel free to send your suggestions in a form of another pull request. I think you're an ideal candidate to make that tutorial more friendly, especially for newcomers.

[kirill-korniakov]

BTW, something is really wrong with this PR at the moment. GitHub says that there are 250+ commits in it, and it seems to me that something went wrong during the merge...

[SpecLad]

https://help.github.com/articles/github-flavored-markdown https://help.github.com/articles/creating-pages-with-the-automatic-generator

I don't see how this answers my question...

[magomimmo]

I did the rebase against the 2.4. branch. perhaps in the mean time something checnged there. I'll quickly redo all the stuff starting from a clean branch and I will submit with another branch name.

On Dec 11, 2013, at 1:03 PM, Kirill Kornyakov notifications@github.com wrote:

BTW, something is really wrong with this PR at the moment. GitHub says that there are 250+ commits in it, and it seems to me that something went wrong during the merge...

— Reply to this email directly or view it on GitHub.

[magomimmo]

Mimmo, thank you for the effort, we appreciate it. But please keep in mind that OpenCV doesn't have tech writers at all. That means that if you see any issues with how-to-contribute tutorial, you're invited to contribute to it!

I'll do it the future as I have time. Now I'm playing with opencv and clojure/seesaw to overcome the current limitations of the Java API not supporting namedWindow and imshow functions.

I believe Clojure/Seesaw (which is a super smart wrapper of java swing) could be even used on the java desktop platform for offering the same Qt features.

Again, nobody is updating the documentation systematically. If you don't like something, feel free to send your suggestions in a form of another pull request. I think you're an ideal candidate to make that tutorial more friendly, especially for newcomers.

As I have time I'll do it — Reply to this email directly or view it on GitHub.

[magomimmo]

in few minutes I'll send a fresh PR mimmo

[magomimmo]

search the web for "github markdown " you always find something helpful. just to make a very quick sample, I searched for "github markdown toc" and I found this.

https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#table-of-contents

you want markdown definitions? search google and so on.