Am still plugging away at a system for producing documentation using Emacs' Org-Mode. Fun.
But not easy, I'll tell you. And maybe not fun either.
Everyone says (all the Emacsters anyhow) that there is lots of great documentation available for anyone who wants to run riot in the fields of Emacs. Sure. Right. Like, totally.
And there is a lot there, but it's mostly useless. Emacs documentation suffers from severe Nerd Syndrome — it is useless unless you already understand the subject. Just like man pages.
Try reading a man page to find out what's what and why and where and when and how to do just One Simple Thing. Then write down all you've learned. If you are an actual human you will take your pencil and sheet of paper and try to kill one with the other, while swearing, a lot. This stuff can't be deciphered. It's good only if you already know it and only need to refresh your memory on the details.
Same with the "GNU Emacs Manual" "The Org Manual" "Worg, the Org-Mode Community" and so on. All of them. Crazy shit. All crazy shit. Endless gibberish. But don't bother mentioning it to anyone. They'll only put you down or (maybe better/maybe worse) will just ignore you and go back to their secret playpens and decoder rings.
This stuff takes a lifetime of commitment. People do amazing things with Emacs but it takes a lifetime of commitment. You have to go all-in, warp your brain, destroy your life, do nothing else forever, and then you'll end up with a thousand new lines of elisp to add to your personal init.el file to make Emacs do that One Crazy Thing that you can't live without.
Then you can write about it. And share your code. And no one else will be able to run it without severe customizing, so they'll all write their own version, and share their code, and yea, it shall propagate unto the ends of the earth. But all of us humans who just want to do a thing or two will remain in the darkness because of ye olde WTF Principle.
I'm a newbie. I've been using Emacs only 25 years, so go ahead, write me off, dismiss me, laugh loudly and long. I'm only now finding value in Org-Mode and hope to figure out how to export my damn notes to damn HTML for a more readable form of damn documentation that can't be accidentally edited via damn finger fumbling while only trying to read it, and yes, I have been having some fun because I am making some progress. Finally.
I can do all the formatted writing I want, and have the CSS I need almost ready, and for my basic use cases I can now export my notes and get a decent result, but progress has been on the order of one small issue solved per day, so it is slow.
Yesterday, for example, I found out how to get Org to export levels "*" through "******" as "h1" through "h6", instead of "h1" through "h4", plus ordered lists for all deeper levels. Woot.
OK, fine, but I've been hunting for an answer to this for over a week. I found a hint in the documentation for the "default" export options, where it said something to the effect that the "H" option could be set to mumble mumble mumble something mumble mumble, so I guessed and tried "#+OPTION H:6" and it actually worked. Good guess for once, but it was only a guess. A hunch. A flying leap. Something that couldn't hurt. And not obvious in any way.
So why the hell was the Org-Mode HTML exporter not set to produce that result by default? Why not? And why was this not clearly documented, with a clear example?
No. Emacs has lousy documentation. Lots of extremely detailed lousy documentation. If I didn't use Emacs for writing and jotting down my notes about various things I wouldn't bother, but it's the best editor I've ever used. For writing.
I can cut and paste blocks of text, generate columns when I rarely need to do columns, open multiple views of a single file, insert tidy tables at will, and lots of other cool things that are available by default. "Dired" is worth it all by itself. That's a major time-saver right there, and I truly love a lot of what Emacs can do, but go one millimeter too deep and you're in an alternate reality with no way home.
So poop on it.
As I said, I'm close to getting enough of Org-Mode and HTML exporting figured out, along with some really nice CSS to match, that it will be worth it, I think. Since I already use Emacs all day, every day, and am comfortable using Org-Mode for organizing my notes, it will pay to stay on this crazy train. I hope.
I was going to try out Sphinx and AsciiDoc just to compare them to what Emacs and Org-Mode can do, but I don't think it's worth it at this point. If Emacs and Org-Mode can meet my needs, then that's fine. As I said, I already use Emacs, and Org-Mode is simple, I know it, and the only hurdle is exporting. Once I understand exporting and have it working to my satisfaction, I'm home free. There is no point in installing, learning, and configuring new software that uses different markup, as far as I can tell now.
And I will be glad when I've reached that point. Maybe in a week. All I want to do is to export some of my personal notes to HTML for my own use. I can hope, can't I? Please?
Have anything worth adding? Then try sosayseff+nosey@gmail.com
Me? Recently had a near-defenestration experience.