Comments (8)
@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.
from eless.
from eless.
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.
from eless.
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 offill-column
,auto-fill-mode
) to a function inbuild.el
?
- Move
- 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 :)
from eless.
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/else
s 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. :)
from eless.
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.
from eless.
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. :)
from eless.
This issue will auto-resolve once #16 is done.
from eless.
Related Issues (20)
- Make eless run on emacs 22.1 HOT 17
- Get emacs binary name from an env var HOT 2
- Replace sed -r s/foo/bar/I with BSD compatible equivalent HOT 2
- Fix building using "make all" on macOS HOT 12
- Invalid regex: "Invalid regular expression" error on macOS HOT 15
- Test various eless usage scenarios on Travis
- man pages are not readable on macOS HOT 79
- Support Perl man pages HOT 2
- Default theme HOT 2
- Installation instructions HOT 17
- View multiple files in sequence with eless HOT 1
- Document how markdown-mode can be installed to use eless as CLI md viewer
- man page with colors HOT 18
- Make the test for info .. | eless work on Travis HOT 3
- Customize faces HOT 3
- `make install` fails without meaningful error message if makeinfo is not installed HOT 2
- Error when filename has parentheses HOT 3
- Reconsider emacs dependency for brew formula HOT 3
- How can I use eless in vterm? HOT 1
- passing updated man page
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from eless.