Set more org-* vars to make eless-build work for other people

[kaushalmodi]

Step 1 probably would be to make M-x eless-build workable from emacs -Q.

[kaushalmodi]

@alphapapa Would you like to update to the latest on master and try building using this updated guide?

At the end of it, at least for eless, the only changed line should be the one with the commit hash. There should be no whitespace changes.

[kaushalmodi]

d665210

[alphapapa]

Well, I looked at these updated instructions:

- =emacs -Q=
- *First* open a non-org file like =build/build.el=.
  - The emphasis on opening a non-org file is so that the
    older-than-required version of =org= in =emacs -Q= doesn't get
    auto-loaded.  The next step would be to install newer version of
    org to a temp location, and that step will fail due to mixed org
    versions.
  - You will be prompted to mark certain /Local Variables/ settings as
    safe.  You can review the =.dir-locals.el= file in this project
    for that.
    #+INCLUDE: ".dir-locals.el" :src emacs-lisp
  - Approving that permanently with the exclamation mark will ensure
    that you will be able to run =M-x eless-install-dependencies= or
    =M-x eless-build= after this point.
- Do =M-x eless-install-dependencies=.
  - You will need to do this step only for the very first time you
    start working on this project.
  - This step will also /autoload/ =build/build.el=.
- Do =M-x eless-build=.
- Run the tangled =eless= through [[http://www.shellcheck.net/][shellcheck]] to ensure that there are
  no errors.
- Understand the changes made in =eless=, /plus/ all the other files.
  - I build the HTML documentation using the Org version from =master=
    branch. So if you build the HTML documentation using the latest
    stable as of today (version =9.0.7=), your HTML export will look a
    bit different (absence of nested =<code>= blocks inside =<pre>=),
    but that's OK.
  - Also the randomly generated hyperlinks and section numbers (if you
    added/removed/moved documentation sections) will be different in
    the HTML and Info exports.
  - .. and the =git rev-parse= returned commit hash will be different.
  - Other than that, you shouldn't see any unexpected changes.
- Provide a PR.
- If changes are only to the Wiki, I believe you can push them
  directly using =git= or manually edit those [[https://github.com/kaushalmodi/eless/wiki][here]]. /I have to yet
  figure out how to keep the non-git Wiki changes and changes in
  =eless.org= in sync./

If I may be completely honest, I feel like that's overkill for what's essentially a single-file project like this. It's very cool, in a way, how you have integrated everything so that it builds from an single Org source file; this could be a very interesting example of what's possible with Org Babel. But to ask a new contributor to go through all that just to submit a PR seems like too much, especially when it comes to installing extra copies of dependencies in a separate directory just to build this project.

And, just FYI, while I appreciate the convenience that dir- and file-local variables provide, I just experienced how irritating they can be while trying to pull the latest changes with Magit. After nearly every keypress I was interrupted by another prompt to apply local variables, not even knowing what the source of those variables was (I guess it was dir-local variables in the wiki subrepo? I'm still not sure), and I did not want to stop at that moment to read through them and mark them for permanent application. Arguably, a potential contributor shouldn't have to deal with applying local variables, and especially shouldn't have to go to the trouble to mentally parse all of them and decide whether to mark them permanently safe in his own config. I know that I, for one, don't want to pollute my local config with marking as safe local variables for projects I only touch occasionally.

Have you considered setting up a Makefile that does all of those steps? Maybe look at the MELPA Makefile for examples. It seems like most, if not all, of that could be automated.

I hope I don't sound too critical here; I really appreciate eless and your work on it, and I am quite impressed by how you have integrated so much into a single Org file building with Babel. It just seems like too much to ask an outsider to deal with manually. :)

Thanks.

[kaushalmodi]

If I may be completely honest, I feel like that's overkill for what's essentially a single-file project like this.

I know :) That's very understandable. If I put myself in someone else's shoes, I wouldn't want to pollute my Customize-set variables from all the different projects I touch.

It's just that it's my first time using Org Babel to this serious level and it got too addictive.

But to ask a new contributor to go through all that just to submit a PR seems like too much, especially when it comes to installing extra copies of dependencies in a separate directory just to build this project.

That's because I chose to build the HTML documentation too. Thinking about that, no one will read that in entirely as the same stuff is exported to Wikis too. I will require htmlize and rainbow-delimiters softly and not force installing those to the user. If the user doesn't have those, the HTML documentation just won't be updated.

Going further, a future contributor only has to provide a PR for the .org file, and not for the script and docs. That should reduce the load on them. The only requirement for them then would be to have org installed from (M)Elpa.

And, just FYI, while I appreciate the convenience that dir- and file-local variables provide, I just experienced how irritating they can be while trying to pull the latest changes with Magit.

My intention to put things in .dir-locals.el was to "automate" things. But I can see that it didn't turn out exactly like that.

I can simply wrap the settings from .dir-locals.el into an elisp function. Running that function would do setq-local of the settings in eless.org buffer. After tangling the org file to check that eless gets generated fine, they need to submit PR only for the org file.

This whole experiment is making me think of what could be the best flow for collaborating on an Org-based project like this.. As you see, the flow is not yet solidified and will keep on changing for some more time.

After nearly every keypress I was interrupted by another prompt to apply local variables, not even knowing what the source of those variables was (I guess it was dir-local variables in the wiki subrepo? I'm still not sure),

The .dir-locals.el is in the project root:

#+INCLUDE: ".dir-locals.el" :src emacs-lisp

That org source wasn't intended for the first time contributors to read.. this was.. The #+INCLUDE auto-expands the .dir-locals.el and throws it verbatim into the CONTRIBUTING.org. The beauty is that each time .dir-locals.el changes, CONTRIBUTING.org will change automatically.. I basically didn't want to manually sync up multiple things:

• documentation in the code
• documentation in Wikis/HTML/Info
• CONTRIBUTING.org

Arguably, a potential contributor shouldn't have to deal with applying local variables, and especially shouldn't have to go to the trouble to mentally parse all of them and decide whether to mark them permanently safe in his own config. I know that I, for one, don't want to pollute my local config with marking as safe local variables for projects I only touch occasionally.

Agree.

Have you considered setting up a Makefile that does all of those steps? Maybe look at the MELPA Makefile for examples. It seems like most, if not all, of that could be automated.

I'll have a look. It is automated at the moment but .dir-locals.el makes things a bit inconvenient. In summary these steps might make the process smoother:

• Send PR only for the org file
• Require user to have only org 9.x (Else they couldn't confirm if their changes made only the changes they expected in eless.
  • Move .dir-locals.el settings (most if not all? thinking of fill-column, auto-fill-mode) to a function inbuild.el?
• In the worst case, user can send a PR for eless directly, and I will integrate that into the org file.

I hope I don't sound too critical here;

Nope, I like it. This flow does need improvement.

I really appreciate eless and your work on it, and I am quite impressed by how you have integrated so much into a single Org file building with Babel.

Thanks!

It just seems like too much to ask an outsider to deal with manually. :)

We are all here to learn. I am still learning how to make this flow fit for all :)

[alphapapa]

Cool, yeah, again I'm quite impressed with how much you've done with Babel. I wonder if the things you learn could be rolled into some kind of best-practices how-to for this sort of thing.

BTW, one other issue you might want to consider: I had to fix indentation in source blocks manually, because some if/elses spanned multiple source blocks. This required a sequence like 1) look at diff, count spaces in the removed lines, 2) open source block, 3) disable aggressive-indent-mode (not everyone uses that, of course), 4) mark-whole-buffer, 5) indent-rigidly to fix indentation, 6) apply source block changes, 7) save and verify indentation in new diff. A bit of a hassle when you have to do it in 4 or 5 blocks. :)

Of course, the only way I know of to fix this would be to either a) not allow if/else to spawn multiple blocks (which seems a bit anti-literate-programming, but I guess embedded comments might suffice), or 2) use something like Outorg or Lenticular to make the primary mode the source code mode and Org a secondary mode. Neither is optimal. It would be cool if Org could somehow combine source blocks behind the scenes for indentation purposes...

I hope that when things settle down a bit and you arrive at some conclusions, you'll have time to write some blog articles teaching us what you've learned. :)

[kaushalmodi]

I had to fix indentation in source blocks manually

I see the issue. I should make those blocks as noweb blocks so that the noweb ref instance decides the indentation, and the code in the source blocks can be without any indentation (just as I did with the whole elisp code (snippet). If that does not turn out to be an element implementation, then I guess it will be the option a) as you said.. to not split the if/else blocks,

It would be cool if Org could somehow combine source blocks behind the scenes for indentation purposes...

or.. just auto-indent the whole eless post-tangling.

Also I was almost going to add this to .dir-locals.el too :P

    ;; Do not add the default indentation of 2 spaces when exiting the *Org Src*
    ;; buffer (the buffer you get when you do «C-c '» while in a block like
    ;; #+BEGIN_SRC
    (setq org-edit-src-content-indentation 0)

I hope that when things settle down a bit and you arrive at some conclusions, you'll have time to write some blog articles teaching us what you've learned. :)

I fear I'll forget everything.. and that's why the emphasis on documentation. Thanks for your detailed feedback.

[alphapapa]

I should make those blocks as noweb blocks so that the noweb ref instance decides the indentation

I didn't know that was possible! Very cool.

or.. just auto-indent the whole eless post-tangling.

Also a good idea, similar to aggressive-indent-mode, which I really enjoy using.

Also I was almost going to add this to .dir-locals.el too :P

That sounds like a very good idea. I have that set to 2, but it would be good to set it for consistency.

I fear I'll forget everything.. and that's why the emphasis on documentation. Thanks for your detailed feedback.

I understand what you mean! Just yesterday I was looking at some code in one of my Emacs packages, and it had been so long that I forgot I had even written some of those functions, and it was like looking at someone else's code. I sure am thankful for docstrings. :)

Well, at some point someone needs to point out eless as a great example of what's possible with Org Babel. Maybe add it to worg (although I'm not sure how much people really use that anymore; it seems like blogs and Planet Emacsen and /r/emacs, etc are more popular)? I wouldn't be surprised if you are the first person to integrate some of these features into a Babel-based build like this. :)

[kaushalmodi]

This issue will auto-resolve once #16 is done.