I Will Now Say This About That

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@nullabigmail.com
Me? Recently had a near-defenestration experience.

Org Exporting & CSS

I'm getting closer. Slowly.

Been dinking around with Emacs org-mode exporting and making it look decent with CSS.

Although I was inspired by Sphinx, and will check it out, I decided to start with Emacs' org-mode and see if I could style that adequately. I use Emacs every day, using Org-mode is simpler than switching to reStructuredText, and if I can stay with Emacs, I don't have to learn another tool.

But, although it's easy to write using org-mode, and dead simple to export from it to HTML, the world of styling that HTML with CSS is hellishly crude.

There is nothing wrong with using the rudimentary styling that exporting from org-mode produces, except that it hurts to look at it. Totally functional in the same way that bolting iron plates together is a functional way to make a boat. It works if you do it right, but it's neither pleasant to look at nor easy to live with.

There is a "Projects using Sphinx" page with lots of examples.

"PyEMD" is a good example: clean, uses the default theme, readable, totally fine.

And we do have a couple of Emacs projects that use themes based on this, but they are hard to track down and not exactly easy to figure out. I'm basically documenting what I've found so I don't lose it all somehow.

(1) DISTRO.TUBE This is what I like best

DistroTube.com is a site created by Derek Taylor [DT], creator of the DistroTube [DT] video channel on YouTube and Odysee [LBRY]. I create videos about GNU/Linux, free software, open source software and related interests. This site was created in Emacs and written in Org Mode. I use Org Export to convert the “org” files into HTML, and I based the design on the popular “ReadTheOrg” theme from Org-HTML-Themes

It has two themes, and offers the CSS for both: htmlize and readtheorg

(2) FNIESSON is up next: "How to export Org mode files into awesome HTML in 2 minutes". This was apparently the inspiration for DistroTube

Though you can easily override CSS stylesheets and add your own HTML themes, we can say (or write) that Org mode provides a /basic/ HTML support. Org-HMTL themes is an open source framework for providing you with a list of very nice (cross-browser) themes for all your Org documents. Use them to style your docs, and your colleagues will come up to tell you that you are a genius!

OK, fine, but not quite there is what I think. fniessen

(3) GONGZHITAAO For me this is a relatively minor contribution, though I'm glad it's there. Everything helps. I'm willing to learn from anyone and everyone, and I'm grateful that they've shared.

Start at Living in Emacs.

He has a demo page, with a presence on at GitHub as well, where you can grab the CSS ("Simple and clean CSS for Org-exported HTML").

(4) JESSEKELLY881 CSS here. See it in action at Imagine, with the CSS here. And there is another view at Rethink.

(5) JUAN JOSÉ GARCÍA RIPOLL He has A CSS Stylesheet For Exporting Org-Mode Files. I'm guessing that the page you get to is the result of his CSS, which is directly accessible at this location.

(6) NORANG Org Mode - Organize Your Life In Plain Text! is famous among Emacs users. I can't say that I'm nuts about the theme he (Bernt Hansen) uses, but it's functional and it's there. I did use his HTML as a sort of test bed to help tune what will be my CSS. You can find his CSS here.

(7) ORG-SPEC This is another example. Can't say that I'm ecstatic, but it's better than I could have done at this stage. I'm keeping the links for future reference because no matter what, I always have more to learn. See "Document", the CSS is also directly accessible here.

At GitHub, see thi-ng. See the info on THOMASF, below, where you can get access to "solarized-dark.css" and "solarized-light.css"

(8) MOWEN I don't know of a sample page, but the CSS is available at GitHub.

(9) NEILSEN See Emacs org-mode examples and cookbook. Not wildly lovely according to me, but it's there and I'm once again grateful. CSS is directly accessible here.

(10) SAKURA See sakura demo, and GitHub - oxalorg_sakura. "Sakura: a minimal classless css theme. Just drop it in and watch the websites blossom!"

There is an example website using sakura: ComputableVerse. And the CSS is directly accessible here.

(11) THOMASF See solarized-css. "To provide general solarized light and dark colorshcemes for HTML documents that mostly relies on standard HTML elements."

Examples and more info are at Github - solarized-css. Directly access the CSS (light) and (dark). And see the HTML test page.

 

---

See tabs at the top for definitions and books.
Have anything worth adding? Then try sosayseff+nosey@nullabigmail.com
Me? Caught picking my nodes again. Embarrassing, as always.

Orgling These Days

So I'm plugging at it, plugging along, plugging holes in my ignorance, plugging them with clumps of knowledge.

I've recently been fairly deeply into "The Org Manual", Release 9.4. I went through the whole thing, taking notes (in org-mode) on whatever looked useful and what did not look too impossibly confusing and deep and possibly never useful.

Yesterday I read that Richard Stallman once read "The Org Manual" and from it could not figure out what org-mode was, or how to use it, so I'm reassured. There is a lot to it, and it can get impossibly confusing.

It is easy to create a document consisting of notes with various heading levels, some quotes, some links, maybe a table or two, some code samples, and so on, and then to export that from org-mode to HTML. No probs.

What I'm currently trying to do is to find styling for that HTML.

Because org-mode for Emacs has been around since 2003, one would assume that there would be a host of themes and CSS files for styling the exported HTML. But nope. Unlike the usual rat's nest of interlocking, mutually-interdependent modes, modules, add-ons, and configuration files needed to get anything working in Emacs, styling HTML exported from org-mode is an almost empty category.

I have found a few resources, but all of them are clunky and will be inconvenient to use. I do have enough to work with though, enough to cover my needs, for the basics, but it will still be goofy going forward.

At least for now. The future, as always, will have to take care of itself.

I got started in this direction by one day discovering Sphinx. Sphinx was developed by and for the Python community to generate, convert, and display documentation in easily-readable formats.

At least for me though, for now though, Sphinx seems too involved. I'm using Emacs for most of my work, and if I can generate decently-styled HTML from the text files I create, I'm OK with that. Even if I have to keep things over toward the really simple end of the scale. I'm not sure that I need to do that, but maybe. And if I stick with Emacs, I don't need to add another tool set and learn all its quirks, foibles, and foolish dead ends.

I want to ease into this, and can add the whells and bissles later, when I know how to spell them and all such-like, and do Feel A Great Need.

And, oddly enough, the best CSS I've found so far is what has been taken from Sphinx and converted to be used with org-mode. Oddly enough, and strangely, given the age of Emacs (45 years) and org-mode (18 years).

But the Emacs world is not like that. The Emacs world is full of half-finished dream projects all piled up together in one tangled endless mass just daring you to come looking, lying in wait for the innocent, steaming with promises, choked with nippers and stingers and sticky webs. Some people get things working and others don't. I'm mostly in the second category. Getting too deeply into Emacs eventually means that you will devote 100% of your time to it, and that you can never again return to the surface.

So anyway.

A couple of weeks back I was seriously wondering if I should devote any time at all to continuing with org-mode and HTML and styling at all, and found in my saved files a copy of "Org Mode Is One of the Most Reasonable Markup Languages to Use for Text" by Karl Voit, and changed my mind. I'll stick with org-mode for now.

Voit compares org-mode to Mmarkdown, reStructuredText, AsciiDoc, Wikitext, and some others, like Markdown Extra, MultiMarkdown, GitHub Flavored Markdown, and CommonMark.

He concludes that org-mode

• is intuitive, easy to learn and remember
• is standardized
• is consistent
• can be easily typed
• makes sense outside of Emacs
• has excellent tool support (within Emacs)

That is, he concludes (in case you came in late), that org-mode is the all-around bestest.

Maybe, maybe not, but since I already use Emacs daily and already use org-mode daily, and can simply and quickly export HTML, and that I think that I have found a not-terrible way to style the HTML that I export from org-mode in a not-terrible-looking way, I'm pretty well set for the present.

So I'll check out Sphinx in a week or two just so I know what it is, and then I'll get on to re-learning the rest of what I want to re-learn, if I can remember what the hell that was.

 

Refs:
The Org Manual
Richard Stallman
Org-mode
Emacs
Sphinx
Python
Org Mode Is One of the Most Reasonable Markup Languages to Use for Text

 

---

Have anything to add? Then email sosayseff+snorp@nullabigmail.com
Me? Frantically trying to get my nose hairs under control. Yet again.

I Still Don't Know

I still don't know. Been reading. Been disorganized lately. Still learning, sort of directed learning, but mostly still random at this point.

Finished one book on Python. OK.

Finished one book on Nim. OK too. Like Python but compiled and exceedingly fast and strikes me as seeming to make more sense as a programming language, though it's not fully-fleshed. But a real possibility.

Finished reading about Go. Sounds OK too, if you like that sort of thing. Like C but smarter. More modern. But still like C. When do we get off the C-Train? All the elegance of assembly language and all the charm of a bowl of alphabet soup without the hot water. I've pretty much had enough of that world.

Am reading Niklaus Wirth's long essay on programming from a few years back, which is essentially an explanation of Oberon. I've always felt attuned to the way Wirth thinks, and Oberon always sounded good, better than Modula-2, which was better than Pascal, but as with the rest of Wirth's work, it's an idea that no one ever wanted to pay attention to. A true shame, is what I think. Still, it's at least a good read about a world that might have been.

Am currently reading "Learn You A Haskell For Great Good". Also interesting. May try this, or else Nim, or both. Haskell is stable, complete, last version released in 2010. That's a feature, not a lack — it's done. No doubt some minor tuning will come along, but no one is out there swearing, trying to pull off major chunks of it and replace them with "Well, let's see if this damn thing works then" parts.

Anyway, I have choices.

Just finished going through "The Org Manual" and taking notes. Nuts. Crazy nuts. Wildly complex when my intention is that since I use Emacs, and am getting better at Org-Mode, and like it for a whole bunch of things, that maybe I should stick to it for generating project plans and documentation while I re-learn programming, and "computer science" in my waning days.

But Org-Mode for publishing complex documents or entire web sites is nasty-looking, and still very clunky and confusingly complex for just pooping out single-page HTML documents but we'll see. Maybe. Since I already use Emacs every day.

Sphinx is up next. Just about every system these days, at least Linux systems, has Python installed, and it gets continually updated, and Sphinx relies on Python, and Sphinx uses a Markdown variant called RestructuretText, and all of that is modern and current and universal, so then Sphinx may be the way to go.

Can't tell yet. Still learning how to format and export and style Org-Mode, which will take another week or two, at my pace these days, and I could end up using both systems in the end, Org-Mode for smaller, less formal things, and Sphinx for bigger, more formal things, like I'd do on a job if I ever had a job again.

Anyway, I want to create personal tutorials for both methods. Get it all figured out, document it, have it ready to go without re-learning anything, just look up my personal tutorials, and use whichever system seems right in the moment.

Then I'll move on to re-learning programming, decide on an environment, and do some stuff. Not a bad life. Not bad.

 

---

Have anything to add? Then email sosayseff+noseyjoe@nullabigmail.com
Me? Still fizzy.